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 帳戶標識碼。 | 識別 GitHub 識別碼的作者,以防內容有問題或問題。 在某些情況下,GitHub 自動化可能會通知作者有關檔案的活動。 |
description |
內容的摘要。 75-300 個字元。 | 用於網站搜尋。 有時在搜尋引擎結果頁面上使用以改善 SEO。 |
ms.author |
作者的Microsoft別名, 不含 “@microsoft.com”。 如果您不是Microsoft員工,請尋找適合在此欄位中使用的Microsoft員工。 | 識別發行項的擁有者。 擁有者負責有關文章內容的決策,以及文章的報告和 BI。 |
ms.date |
格式為 MM/DD/YYYY 的日期。 | 顯示在已發佈頁面上,以指出文章上次經過大量編輯或保證新鮮時間。 日期輸入時沒有時間,且會在UTC時區中解譯為0:00。 向用戶顯示的日期會轉換成其時區。 |
ms.service 或 ms.prod |
服務或產品標識碼。 使用一個或另一個,絕不同時使用兩者。 此值通常會在 docfx.json 檔案中全域設定。 | 用於問題分級和報告。 ms.prod 和 ms.service 是區分之前Microsoft Learn,意在區分在機器上執行的特定產品(內部部署)和(早期)雲端服務。 |
ms.topic |
通常為下列其中一個值:article 、 conceptual 、 contributor-guide 、 overview 、 quickstart 、 reference 、 sample 、 tutorial 、 。 |
識別報告用途的內容類型。 |
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.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 |
文章中不應該翻譯的字詞清單(當地語系化)。 | 使用此元數據來防止「過度配置」。 |