Metadata for Microsoft Learn documentation
We use metadata on Microsoft Learn for content analytics reporting, discoverability of content via search, and driving aspects of the site experience. Metadata can be applied in the article (in the YAML front matter) or globally in the docfx.json file for the repo.
If you're making an edit to an existing article, you probably won't have to change any metadata. However, if you're adding a new article, there are certain required metadata attributes that you'll need to include in the YAML front matter of the file.
Here's an example of metadata applied in the YAML front matter of a Markdown article:
---
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 -->
Note
The ms.prod and ms.technology metadata attributes are being retired from the Learn platform. Starting in January 2024, values in these taxonomies will be consolidated into ms.service and ms.subservice for reporting on content by product.
The following table shows the required metadata attributes. If you omit any of these, you'll likely get a validation error during build.
Field | Value | Why? |
---|---|---|
author |
The author's GitHub account ID. | Identifies the author by GitHub ID in case there are questions about or problems with the content. In some cases, GitHub automation might notify the author of activity involving the file. |
description |
A summary of the content. 75-300 characters. | Used in site search. Sometimes used on a search engine results page for improved SEO. |
ms.author |
The author's Microsoft alias, without "@microsoft.com". If you aren't a Microsoft employee, find a suitable Microsoft employee to use in this field. | Identifies the article's owner. The owner is responsible for decisions about the content of the article, and for the article's reporting and BI. |
ms.date |
A date in the format MM/DD/YYYY. | Displayed on the published page to indicate the last time the article was substantially edited or guaranteed fresh. The date is entered without time and is interpreted as 0:00 and in the UTC time zone. The date displayed to users is converted to their time zone. |
ms.service or ms.prod |
The service or product identifier. Use one or the other, never both. This value is often set globally in the docfx.json file. | Used for issue triage and reporting. ms.prod and ms.service are distinctions made that predate Microsoft Learn, meant to distinguish between specific products run on a machine (on-prem) and the (early) cloud services. |
ms.topic |
Usually one of the following values:article , conceptual , contributor-guide , overview , quickstart , reference , sample , tutorial . |
Identifies the type of content for reporting purposes. |
title |
The page title. | This is the page title that's displayed on the browser tab. It's the most important metadata for SEO. |
Attributes are case-sensitive. Enter them exactly as listed, and use a colon and a space between the attributes and the value. If an attribute value includes a colon (:), a hash (#), or any other special character, you must enclose it either single (') or double (") quotes. For example:
---
title: 'Quickstart: How to use hashtags (#) to make a point on the internet'
---
# Heading 1 <!-- the article title to show on the web page -->
In addition to the required metadata, there are many optional metadata attributes you can add. The following table shows some of the optional metadata attributes.
Field | Value | Why? |
---|---|---|
ms.custom |
For writer or team use only. Commonly used for tracking specific docs or sets of content in telemetry tools. It's a single string value, and it's up to the consuming tool to parse it. Example: ms.custom: "experiment1, content_reporting, all_uwp_docs, CI_Id=101022" Character limit: The maximum string value length is 125 characters. |
ms.custom is a custom field that writers can use to track special projects or a subset of content. |
ms.reviewer |
The Microsoft alias of a person who reviews the content. | |
ms.subservice |
A more specific value that can be used with ms.service to enable more specific reporting on content about a service. Only use ms.subservice if you're also using ms.service . |
ms.subservice by itself isn't valid metadata. The author must associate it with a parent ms.service value. This attribute is a way to drill down further in reporting for a given ms.service . |
ms.technology |
A more specific value that can be used together with ms.prod to enable more specific reporting on content about a product. Only use ms.technology if you're also using ms.prod . |
ms.technology by itself isn't valid metadata. The author must associate it with a parent ms.prod value. This attribute is a way to drill down further in reporting for a given ms.prod . |
ROBOTS |
NOINDEX , UNFOLLOW |
Use ROBOTS in your metadata section to prevent the build and publishing process from showing content on search pages. When you want to use ROBOTS (and yes, it's all capitalized, even though other metadata tags aren't):- Add ROBOTS: NOINDEX to your metadata section.- NOINDEX causes the asset to not show up in search results.- Use NOFOLLOW only when you archive an entire content set. |
no-loc |
A list of words in the article that should never be translated (localized). | Use this metadata to prevent "overlocalization." |