Метаданные для документации По Microsoft Learn
Мы используем метаданные в Microsoft Learn для отчетности по анализу контента, возможности обнаружения содержимого с помощью поиска и вождения аспектов взаимодействия с сайтом. Метаданные можно применить в статье (в начальной части YAML) или глобально в файле docfx.js для репозитория.
При изменении существующей статьи изменять метаданные скорее всего не потребуется. Однако если вы добавляете новую статью, существуют определенные обязательные атрибуты метаданных, которые необходимо включить в интерфейс YAML файла.
Ниже приведен пример метаданных, применяемых в YAML в начале статьи Markdown:
---
title: # the article title to show on the browser tab
description: # 115 - 145 character description to show in search results
author: {github-id} # the author's GitHub ID - will be auto-populated if set in settings.json
ms.author: {ms-alias} # the author's Microsoft alias (if applicable) - will be auto-populated if set in settings.json
ms.date: {@date} # the date - will be auto-populated when template is first applied
ms.topic: getting-started # the type of article
---
# Heading 1 <!-- the article title to show on the web page -->
Примечание
Атрибуты метаданных ms.prod и ms.technology удаляются из платформы Learn. Начиная с января 2024 года значения в этих таксономиях будут консолидированы в ms.service и ms.subservice для отчетности о содержимом по продукту.
В следующей таблице показаны необходимые атрибуты метаданных. Если не указать какой-либо из них, то во время сборки скорее всего возникнет ошибка проверки.
Поле | значение | Почему? |
---|---|---|
author |
Идентификатор учетной записи GitHub автора. | Определяет автора по идентификатору GitHub при наличии вопросов или проблем с содержимым. В некоторых случаях средства автоматизации GitHub позволяют оповестить автора о действиях с файлом. |
description |
Краткое описание содержимого. От 75 до 300 символов. | Используется в поиске по сайту. Иногда используется на странице результатов поиска для улучшения SEO. |
ms.author |
Псевдоним Майкрософт автора без @microsoft.com. Если вы не являетесь сотрудником корпорации Майкрософт, найдите подходящего сотрудника Майкрософт, чтобы указать его в этом поле. | Идентифицирует владельца статьи. Владелец несет ответственность за принятие решений о содержимом статьи, а также за создание отчетов и бизнес-аналитики для этой статьи. |
ms.date |
дата в формате MM/ДД/ГГГГ. | Отображается на опубликованной странице, чтобы указать время последнего существенного изменения статьи или последней проверки ее актуальности. Дата указывается без времени в часовом поясе UTC. Время интерпретируется как 0:00. Дата, отображаемая для пользователей, преобразуется в их часовой пояс. |
ms.service или ms.prod |
Идентификатор службы или продукта. Используйте один из идентификаторов, но не оба одновременно. Это значение часто устанавливается глобально в файле docfx.js. | Используется для рассмотрения проблем и создания отчетов. ms.prod и ms.service являются различиями, которые предопределяют Microsoft Learn, предназначенные для различения конкретных продуктов, выполняемых на компьютере (на предварительном устройстве) и (ранних) облачных службах. |
ms.topic |
Обычно используется одно из следующих значений:article , conceptual , contributor-guide , overview tutorial quickstart reference sample . |
Определяет тип содержимого для создания отчетов. |
title |
Заголовок страницы. | Это заголовок, который отображается во вкладке браузера. Это наиболее важные метаданные для SEO. |
В атрибутах учитывается регистр. Вводите их в точности так, как указано, используя двоеточие и пробел между атрибутами и значением. Если значение атрибута включает двоеточие (:), решетку (#) или любой другой специальный символ, необходимо заключить его в одинарные (') или двойные (") кавычки. Например:
---
title: 'Quickstart: How to use hashtags (#) to make a point on the internet'
---
# Heading 1 <!-- the article title to show on the web page -->
Помимо необходимых метаданных, можно добавить множество необязательных атрибутов метаданных. В следующей таблице показаны некоторые необязательные атрибуты метаданных.
Поле | значение | Почему? |
---|---|---|
ms.custom |
Только для использования автором или командой. Обычно используется для отслеживания конкретных документов или наборов содержимого в средствах телеметрии. Это одиночное строковое значение, и для его синтаксического анализа используется средство потребления. Пример: ms.custom: "experiment1, content_reporting, all_uwp_docs, CI_Id=101022" Ограничение по числу символов: максимальная допустимая длина строкового значения — 125 символов. |
ms.custom — настраиваемое поле, которое может использоваться авторами для отслеживания специальных проектов или подмножества содержимого. |
ms.reviewer |
Псевдоним Майкрософт пользователя, который рецензирует содержимое. | |
ms.subservice |
Более конкретное значение, которое можно использовать для ms.service включения более конкретных отчетов о содержимом службы. Используйте ключ ms.subservice , только если вы используете ключ ms.service . |
Ключ ms.subservice сам по себе не является допустимыми метаданными. Автор должен связать его с родительским значением ms.service . Этот атрибут позволяет детализировать отчеты для заданного ms.service . |
ms.technology |
Более конкретное значение, которое можно использовать вместе с ms.prod тем, чтобы включить более конкретные отчеты о содержимом о продукте. Используйте ключ ms.technology , только если вы используете ключ ms.prod . |
Ключ ms.technology сам по себе не является допустимыми метаданными. Автор должен связать его с родительским значением ms.prod . Этот атрибут позволяет детализировать отчеты для заданного ms.prod . |
ROBOTS |
NOINDEX , UNFOLLOW |
Используйте ключ ROBOTS в разделе метаданных, чтобы содержимое не отображалось на страницах поиска в процессе сборки и публикации. Если вы хотите использовать ключ ROBOTS (и да, его нужно указывать полностью заглавными буквами, несмотря на то, что другие теги метаданных записываются строчными), сделайте следующее:– Добавьте ROBOTS: NOINDEX в раздел метаданных.При указании - NOINDEX ресурс не будет отображаться в результатах поиска.– Используйте NOFOLLOW только при архивировании всего набора содержимого. |
no-loc |
Список слов в статье, которые не должны быть переведены (локализованы). | Используйте эти метаданные для предотвращения избыточной локализации. |