.NET 文件的中繼資料和 Markdown 範本

  • 發行項

此 dotnet/docs 範本包含 Markdown 語法的範例，以及設定中繼資料的指導。

建立 Markdown 檔案時，應將包含的範本複製到新檔案中、依照如下指定來填寫中繼資料，並將以上 H1 標題設為文章標題。

中繼資料

所需的中繼資料區塊位於下列範例中繼資料區塊中：

---
title: [ARTICLE TITLE]
description: [usually a summary of your first paragraph. It gets displayed in search results, and can help drive the correct traffic if well written.]
author: [GITHUB USERNAME]
ms.date: [CREATION/UPDATE DATE - mm/dd/yyyy]
---
# The H1 should not be the same as the title, but should describe the article contents
  • 冒號 (:) 和中繼資料項目的值之間必須有空格。
  • 值中的冒號 (例如標題) 會中斷中繼資料解析器。 在此情況下，請使用雙引號來括住標題 (例如 title: "Writing .NET Core console apps: An advanced step-by-step guide")。
  • 標題：會出現在搜尋引擎結果中。 標題不應與 H1 標題中的標題相同，且不應超過 60 個字元。
  • 描述：會摘要文章的內容。 通常會顯示於搜尋結果頁面，但不會用於搜尋排名。 長度應為 115-145 個字元，包括空格。
  • 作者：作者欄位應包含作者的 GitHub 使用者名稱。
  • ms.date：上次重大更新的日期。 如果您已檢閱並更新整篇文章，請在現有文章中對此進行更新。 錯字或類似內容的小修正，不保證會更新。

其他中繼資料會附加至每篇文章，但我們通常會在資料夾層級套用大多數中繼資料值 (在 docfx.json 中指定)。

基本 Markdown、GFM 和特殊字元

您可透過 Markdown 參考一文了解 Markdown、GitHub Flavored Markdown (GFM) 和 OPS 特定延伸模組的基本知識。

Markdown 會使用 *、' 和 # 等特殊字元來格式化。 如果您希望將其中一個字元包含在內容中，則必須執行以下兩項作業之一：

  • 將反斜線放在特殊字元前面，以「逸出」它 (例如 \* *) 。
  • 例如， * 針對 *) ，使用字元 (的 HTML 實體程式碼。

檔案名稱

檔案名稱使用下列規則：

  • 只包含小寫字母、數字和連字號。
  • 沒有空格或標點符號字元。 檔案名稱中使用連字號來分隔文字和數字。
  • 使用特定的動作動詞，例如 develop、buy、build、troubleshoot。 沒有 -ing 字詞。
  • 不包含 a、and、the、in、or 等短字。
  • 必須是 Markdown 格式且使用 .md 副檔名。
  • 保持檔案名稱合理簡短。 它們是您文章 URL 的一部分。

標題

使用句型大寫。 標題的第一個單字一律為大寫。

文字樣式

斜體
用於檔案、資料夾、路徑 (針對較長的項目，請將其拆成自己的行)、新字詞。

粗體字
用於 UI 項目。

Code
用於內嵌程式碼、語言關鍵字，NuGet 套件名稱、命令列命令、資料庫資料表和資料列名稱，以及不希望可點選的 URL。

如需錨點、內部連結、其他文件的連結、程式碼包含項目和外部連結的資訊，請參閱連結的一般文章。

.NET 文件小組使用下列慣例：

  • 在大多數情況下，我們使用相對連結且不建議在連結中使用 ~/，因為相對連結會在 GitHub 上的來源中解析。 但是，每當連結到相依存放庫中的檔案時，我們會使用 ~/ 字元來提供路徑。 由於相依存放庫中的檔案位於 GitHub 中不同位置，因此無論撰寫方式如何，連結都無法使用相對連結來正確解析。
  • C# 語言規格和 Visual Basic 語言規格包含在 .NET 文件中，包含語言存放庫中的來源。 Markdown 來源在 csharplang 和 vblang 存放庫中管理。

規格的連結，必須指向包含這些規格的來源目錄。 若為 C#，其為 ~/_csharplang/spec，若為 VB，則為 ~/_vblang/spec，如下範例所示：

[C# Query Expressions](~/_csharplang/spec/expressions.md#query-expressions)

組建系統具有一些延伸模組，可讓我們連結到 .NET API 而無需使用外部連結。 請使用下列語法之一：

  1. 自動連結：<xref:UID> 或 <xref:UID?displayProperty=nameWithType>

    displayProperty 查詢參數會產生完整的連結文字。 根據預設，連結文字只會顯示成員或型別名稱。

  2. Markdown 連結：[link text](xref:UID)

    用於您要自訂顯示的連結文字時。

範例：

  • <xref:System.String> 會轉譯為 String \(英文\)
  • <xref:System.String?displayProperty=nameWithType> 會轉譯為 System.String \(英文\)
  • [String class](xref:System.String) 會轉譯為 String 類別 \(英文\)

如需如何使用此標記法的詳細資訊，請參閱使用交叉參考 \(英文\)。

某些 UID 包含特殊字元 '、 # 或 *，UID 值必須分別編碼為 %60 、 %23 和 %2A 。 有時候您會看到括號也會被編碼，但這並非必要。

範例：

  • System.Threading.Tasks.Task'1 會變成 System.Threading.Tasks.Task%601
  • System.Exception.#ctor 變成 System.Exception.%23ctor
  • System.Lazy'1.#ctor (System.Threading.LazyThreadSafetyMode) 變成 System.Lazy%601.%23ctor%28System.Threading.LazyThreadSafetyMode%29

您可以在 https://xref.learn.microsoft.com/autocomplete 中找到類型的 UID、成員多載清單或特定多載成員。 查詢字元字串 ?text=*\<type-member-name>* 可識別出您要查看其 UID 的類型或成員。 例如，https://xref.learn.microsoft.com/autocomplete?text=string.format 會擷取 String.Format 多載。 該工具會在 UID 的任何部分中，搜尋所提供的 text 查詢參數。 例如，您可以搜尋成員名稱 (ToString)、部分成員名稱 (ToStri)、類型和成員名稱 (Double.ToString) 等。

如果您在 UID 之後新增 * (或 %2A) ，則連結會代表多載頁面，而不是特定 API。 例如，當您想要連結至清單 < T > 時，可以使用該連結。BinarySearch 方法頁面的一般方式，而不是清單T > 之類的 < 特定多載。BinarySearch (T、IComparer < T >) 。 當成員未多載時，您也可以使用 * 連結至成員頁面;這可讓您不必在 UID 中包含參數清單。

要連結到特定方法多載，必須包含每個方法參數的完整類型名稱。 例如， < xref：System.DateTime.ToString > 連結至無參數的 DateTime.ToString方法，而 < xref：System.DateTime.ToString (System.String，System.IFormatProvider) DateTime.ToString (String，IFormatProvider) 方法的連結。 >

若要連結至泛型型別，例如System.Collections.Generic.List < T >，您可以使用 ' (%60) 字元，後面接著泛型型別參數的數目。 例如， <xref:System.Nullable%601> 連結到System.Nullable < T >類型，而 <xref:System.Func%602> 連結到System.Func < T，TResult >委派。

程式碼

包含程式碼的最佳方法，是包含工作範例中的程式碼片段。 遵循參與 .NET 文章中的指令來建立範例。 包含完整程式的程式碼片段，可確保所有程式碼都透過我們的持續整合 (CI) 系統執行。 但是，如果需要顯示導致編譯時間或執行階段錯誤的內容，則可以使用內嵌程式碼區塊。

如需有關用於在文件中顯示程式碼之 Markdown 語法的詳細資訊，請參閱如何在文件中包含程式碼。

影像

靜態影像或動畫 GIF

![this is the alt text](../images/Logo_DotNet.png)

連結的影像

[![alt text for linked image](../images/Logo_DotNet.png)](https://dot.net)

影片

您可以在 Markdown 檔案中內嵌 YouTube 影片。 若要取得影片的正確網址，請以右鍵按一下影片，選取 [複製內嵌程式碼]，然後從 <iframe> 項目複製網址。

> [!VIDEO <youtube_video_link>]

例如：

> [!VIDEO https://www.youtube.com/embed/Q2mMbjw6cLA]

learn.microsoft 延伸模組

learn.microsoft 提供一些 GitHub Flavored Markdown 的額外擴充功能。

檢查清單

自訂樣式適用於清單。 您可以轉譯具有綠色核取記號的清單。

> [!div class="checklist"]
> * How to create a .NET Core app
> * How to add a reference to the Microsoft.XmlSerializer.Generator package
> * How to edit your MyApp.csproj to add dependencies
> * How to add a class and an XmlSerializer
> * How to build and run the application

這會呈現為：

  • 如何建立 .NET Core 應用程式
  • 如何將參考新增至 Microsoft.XmlSerializer.Generator 套件
  • 如何編輯您的 MyApp.csproj 以新增相依性
  • 如何新增類別和 XmlSerializer
  • 如何建置並執行應用程式

您可以在 .NET Core 文件中查看檢查清單的範例。

按鈕

按鈕連結：

> [!div class="button"]
> [button links](dotnet-contribute.md)

這會呈現為：

按鈕連結

您可以在 Visual Studio 文件中查看按鈕的範例。

逐步

>[!div class="step-by-step"]
> [Pre](../docs/csharp/expression-trees-interpreting.md)
> [Next](../docs/csharp/expression-trees-translating.md)

您可以在 C# 指南中查看動作中的逐步範例。