Microsoft Learn 文档的元数据

我们使用 Microsoft Learn 上的元数据来报告、通过搜索发现内容，以及推动网站体验的各个方面。 元数据可以应用于文章中的 YAML 扉页或全局应用于存储库的 docfx.json 文件中。

如果要编辑现有文章，可能不需要更改任何元数据。 但是，如果要添加新文章，则需要在文件的 YAML 扉页中包括某些必需元数据属性。

以下是应用在 Markdown 文章的 YAML 扉页中的元数据示例：

---
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 年 1 月开始，这些分类法中的值将合并到 ms.service 和 ms.subservice 中，以便按产品报告内容。

必需元数据

下表显示了必需的元数据属性。 如果省略了其中任何一个元数据键，则生成期间可能会遇到验证错误。

字段	值	为什么？
author	作者的 GitHub 帐户 ID。	如果对内容有疑问或问题，请根据 GitHub ID 识别作者。 在某些情况下，GitHub 自动化可能会就文件的相关活动通知作者。
description	内容摘要。 75-300 个字符。	用于站点搜索。 有时在搜索引擎结果页上用于改进 SEO。
ms.author	作者的 Microsoft 别名，不带“@microsoft.com”。 如果你不是 Microsoft 员工，请查找适合在此字段中使用的 Microsoft 员工。	识别文章的所有者。 所有者负责决定文章的内容以及文章的报告和 BI。
ms.date	采用 MM/DD/YYYY 格式的日期。	显示在“已发布”页面上，指示上次对文章进行了重大编辑或保证文章处于最新状态的时间。 输入日期时没有时间，解释为 0:00 且采用 UTC 时区。 向用户显示的日期将转换为其所在时区。
ms.service 或 ms.prod	服务或产品标识符。 应使用二者之一，不得同时使用。 此值通常在 docfx.json 文件中全局设置。	用于问题会审和报告。 ms.prod 和 ms.service 是 Microsoft Learn 之前做出的区分，旨在区分计算机（本地）和（早期）云服务上运行的特定产品。
ms.topic	通常是下列值之一：	标识用于报告用途的内容类型。
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	审阅内容的用户的 Microsoft 别名。
ms.subservice	一个更具体的值，可与 ms.service 配合使用，以便对有关服务的内容进行更具体的报告。 如果你还在使用 ms.service，请仅使用 ms.subservice。	ms.subservice 本身不是有效的元数据。 作者必须将其与父 ms.service 值进行关联。 此属性可用于在给定 ms.service 的报告中进一步向下钻取。
ms.technology	一个更具体的值，可与 ms.prod 配合使用，以便对有关产品的内容进行更具体的报告。 如果你还在使用 ms.prod，请仅使用 ms.technology。	ms.technology 本身不是有效的元数据。 作者必须将其与父 ms.prod 值进行关联。 此属性可用于在给定 ms.prod 的报告中进一步向下钻取。
ROBOTS	%>	在元数据部分中使用 ROBOTS，以防止生成和发布过程在搜索页上显示内容。 如果想要使用 ROBOTS（所有字母大写，但其他元数据标记不采用此格式），请执行以下操作： - 将 ROBOTS: NOINDEX 添加到元数据部分。 - NOINDEX 会导致资产不在搜索结果中显示。 - 仅在存档整个内容集时使用 NOFOLLOW。
no-loc	文章中不应翻译（本地化）的字词列表。	使用此元数据可防止“过度本地化”。

另请参阅

• 元数据资源管理器