Метаданные для документации По 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, overviewtutorialquickstartreferencesample.
Определяет тип содержимого для создания отчетов.
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 Список слов в статье, которые не должны быть переведены (локализованы). Используйте эти метаданные для предотвращения избыточной локализации.

См. также