Markdown 最佳做法

本文提供在檔中使用 Markdown 的特定指引。 這不是 Markdown 的教學課程。 如果您需要 Markdown 的教學課程，請參閱此 Markdown 速查表。

建置流程會使用 markdig 來處理 Markdown 文件。 Markdig 會根據最新 CommonMark 規格的規則來剖析檔。 OPS 遵循 CommonMark 規格，併為平臺特定功能新增一些延伸模組，例如數據表和警示。

CommonMark 規格對於某些 Markdown 元素的建構更嚴格。 請密切關注本檔中提供的詳細數據。

我們使用 VS Code 中的 Markdownlint 延伸模組來強制執行我們的樣式和格式規則。 此延伸模組會安裝為 Learn Authoring Pack 的一部分。

空白行、空格和索引標籤

空白行也會向 Markdown 中的區塊結尾發出訊號。

• 在不同類型的 Markdown 區塊之間放置單一空白;例如，在段落與清單或標頭之間。
• 請勿使用一個以上的空白行。 多個空白行會在 HTML 中轉譯為單一空白行，因此不需要額外的空白行。
• 請勿在程式代碼區塊中使用放置多個連續空白行，連續空白行會中斷程式代碼區塊。

Markdown 中的間距相當重要。

• 拿掉行尾的額外空格。 尾端空格可以變更 Markdown 轉譯的方式。
• 一律使用空格，而不是 Tab 鍵（硬式 Tab 鍵）。

標題與小標題

僅使用 ATX 標題 （# 樣式，而不是 = 或 - 樣式標頭）。

• 使用句子式大小寫 - 只有專有名詞和標題的第一個字母應該大寫
• 請在 # 和標題的第一個字母之間包含單一空格。
• 以單一空白行括住標題
• 不要在每個文件中使用多於一個的 H1。
  • 它應該是第一個標題
  • 它應該符合文章的標題
• 將標頭層級遞增一個 - 不要略過層級
• 將深度限制為 H3 或 H4
• 避免在標頭中使用粗體或其他標記

將行長度限制為100個字元

對於概念文章和 Cmdlet 參考，請將行限製為 100 個字元。 針對 about_ 發行項，請將行長度限制為 79 個字元。 限制行長度可改善git差異和歷程記錄的可讀性。 它也使其他作家更容易做出貢獻。

使用 VS Code 中的 Reflow Markdown 延伸模組來重排段落，以符合指定的行長度。

某些內容類型無法輕易地重排。 例如，程式代碼區塊內的程式代碼也可能很難重排，視內容和程式代碼語言而定。 您無法重排資料表。 在這些情況下，請使用您最好的判斷，盡可能讓內容保持接近 100 個字元的限制。

強調

為了強調，Markdown 支援粗體和斜體。 Markdown 可讓您使用 * 或 _ 來標記強調。 不過，若要保持一致並顯示意圖：

• 使用 ** 粗體
• 使用_來表示斜體字

遵循此模式可讓其他人在文件中有粗體和斜體混合時，更輕鬆地了解標記的意圖。

列表 / 清單

如果您的清單有多個句子或段落，請考慮使用子層級標頭而不是清單。

以單一空白行括住清單。

未排序的清單

• 清單專案除非包含多個句子，否則請勿使用句號結束。
• 使用連字符（-）作為清單項目符號，以避免與使用星號（*）的強調標記混淆。
• 若要在項目符號下包含段落或其他元素，請插入換行，並確保縮排與項目符號後的第一個字元對齊。

例如：

This is a list that contains child elements under a bullet item.

- First bullet item

  Sentence explaining the first bullet.

  - Child bullet item

    Sentence explaining the child bullet.

- Second bullet item
- Third bullet item

這是包含項目符號下子元素的清單。

• 第一個項目符號

  說明第一個項目符號的句子。

  • 子項目符號

    說明子項目符號的句子。

• 第二項

• 第三個項目符號點

已排序的清單

• 編號清單中的所有項目都應該使用數字 1.，而不是遞增每個項目。
  • Markdown 轉譯會自動遞增其數值。
  • 這可讓重新排序專案變得更容易，並標準化次級內容的縮排。
• 若要在編號項目底下包含段落或其他元素，請將縮排與項目編號後面的第一個字元對齊。

例如：

1. For the first element, insert a single space after the `1`. Long sentences should be wrapped to
   the next line and must line up with the first character after the numbered list marker.

   To include a second element, insert a line break after the first and align indentations. The
   indentation of the second element must line up with the first character after the numbered list
   marker.

1. The next numbered item starts here.

產生的 Markdown 會顯示如下：

1. 針對第一個元素，在1之後插入單一空格。 長句子應該包裝至下一行，而且必須與編號清單標記之後的第一個字元對齊。

   若要包含第二個專案，請在第一個元素後面插入換行符，並對齊縮排。 第二個元素的縮排必須與編號清單標記之後的第一個字元對齊。

2. 下一個編號的專案會從這裡開始。

圖片

包含影像的語法如下：

![[alt text]](<folderPath>)

Example:
![Introduction](./media/overview/Introduction.png)

其中 alt text 是影像的簡短描述，而 <folderPath> 是影像的相對路徑。

• 需要替代文字，才能支持視障人士的螢幕助讀程式。
• 影像應該儲存在 media/<article-name> 包含發行項的資料夾內。
  • 在media資料夾內建立一個資料夾，該資料夾名稱要與您的文章檔名相符。 將該文章的映像複製到該新資料夾。
• 請勿在文章之間共用映像。
  • 如果多個發行項使用影像，每個資料夾都必須有該映像的複本。
  • 這可防止變更某個文章中的影像，而不會影響另一篇文章。

支援下圖檔案類型：*.png、、*.gif、*.jpeg、 *.jpg*.svg

Markdown 擴充功能 - 警示方塊

Learn Authoring Pack 包含支援發佈系統專屬功能的工具。 警示是 Markdown 延伸模組，可建立區塊符號，以色彩和圖示反白顯示內容的重要性。 支援下列警示類型：

> [!NOTE]
> Information the user should notice even if skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Essential information required for user success.

> [!CAUTION]
> Negative potential consequences of an action.

> [!WARNING]
> Dangerous certain consequences of an action.

Microsoft Learn 上，這些警示看起來會像這樣：

附注區塊

備註

用戶應該注意的資訊，即使略過。

提示區塊

小提示

選擇性資訊，可協助使用者更成功。

重要區塊

這很重要

使用者成功所需的基本資訊。

注意區塊

謹慎

動作的負面潛在後果。

警告區塊

警告

某些行動的後果是危險的。

Markdown 延伸模組 - 數據表

資料表是由行和列組成的資料排列方式：

• 單一標題行
• 用于分隔標頭與數據的分隔符列
• 零個或多個數據列

每個數據列都包含包含以管道分隔的任意文字的儲存格（|）。 為了清楚起見，也建議使用前置和尾端管道。 管道與儲存格內容之間的空格會修剪。 區塊層級項目無法插入數據表中。 數據列的所有內容都必須在單行上。

分隔符資料列由只包含連字元的儲存格組成，並且可以選擇性地在前面或後面加上冒號（-），或同時加上兩者，以分別表示左、右或置中對齊。

對於小型數據表，請考慮改用清單。 清單包括：

• 更容易維護和閱讀
• 可重排以符合 100 個字元的行限制
• 更方便使用螢幕助讀程式進行視覺協助的使用者存取

如需詳細資訊，請參閱 Microsoft Learn 的 Markdown 參考的數據表一節。

超連結

• 超鏈接必須使用 Markdown 語法 [friendlyname](url-or-path)。

• 發佈系統支援三種類型的連結：

  • URL 連結
  • 檔案連結
  • 交叉參考連結

• 除非對目標網站無效，否則外部網站的所有 URL 都應該使用 HTTPS。

• 鏈接必須具有易記名稱，通常是連結文章的標題

• 避免在超連結的括弧內使用反引號、粗體或其他標記。

• 當您記錄特定 URI 時，可以使用裸露的 URL，但必須以反引號括住。 例如：

  By default, if you don't specify this parameter, the DMTF standard resource URI
  `http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/` is used and the class name is appended to it.
  

• 使用連結參考，但僅在允許的情況下。 段落中的鏈接參考可讓段落更容易閱讀。

  連結參考會將 Markdown 連結分成兩個部分：

  • 連結參考 - [friendlyname][id]
  • 連結定義 - [id]: url-or-path

URL 類型連結

• 其他文章中的 learn.microsoft.com URL 鏈接必須使用網站相對路徑。 建立網站相對連結最簡單的方式是從瀏覽器複製 URL，然後從貼到 Markdown 的值中移除 https://learn.microsoft.com/en-us 。
• 請勿在 Microsoft 相關資源的 URL 中包含地區設定（從 URL 移除 /en-us）或維基百科連結。
• 從 URL 移除任何不必要的查詢參數。 應移除的範例：
  • ?view=powershell-5.1 - 用來連結至特定版本的PowerShell
  • ?redirectedfrom=MSDN - 當您從舊文章重新導向至其新位置時，已新增至URL
• 如果您需要連結至特定版本的檔，您必須將 參數新增 &preserve-view=true 至查詢字串。 例如：?view=powershell-5.1&preserve-view=true
• 在Microsoft網站上，URL 連結不包含擴展名（例如，否 .md）

檔案類型連結

• 檔案連結可用來將某個參考文章連結至另一個參考文章，或從某個概念性文章連結至相同 docset 中的另一篇文章。
  • 如果您需要從概念性文章連結至參考文章，則必須使用URL連結。
  • 如果您需要連結至另一個檔集中的文章，或跨存放庫，您必須使用URL連結。
• 使用相對的檔案路徑（例如：../folder/file.md）
• 所有檔案路徑都使用正斜線 （/） 字元
• 包含延伸名 （例如， .md）

交叉參考連結

交叉參考連結是發佈系統支援的一項特殊功能。 您可以在概念性文章中使用交叉參考連結，以連結至 .NET API 或 Cmdlet 參考。

• 如需 .NET API 參考連結，請參閱中央貢獻者指南中的 使用檔案中的連結。

• Cmdlet 參考的鏈結具有下列格式：xref:<module-name>.<cmdlet-name>。 例如，要將 Get-Content cmdlet 連接到 Microsoft.PowerShell.Management 模組。

  [Get-Content](xref:Microsoft.PowerShell.Management.Get-Content)

深層連結

URL 和檔案連結都允許深層連結。

• 錨點文字必須是小寫
• 將錨點新增至目標路徑的結尾。 例如：
  • [about_Splatting](about_Splatting.md#splatting-with-arrays)
  • [custom key bindings](https://code.visualstudio.com/docs/getstarted/keybindings#_custom-keybindings-for-refactorings)

如需詳細資訊，請參閱 使用檔中的連結。

程式代碼範圍

程式代碼範圍用於段落內的內嵌代碼段。 使用單一反引號來表示程式碼範圍。 例如：

PowerShell cmdlet names use the `Verb-Noun` naming convention.

此範例顯示為：

PowerShell Cmdlet 名稱使用Verb-Noun命名慣例。

程式碼區塊

程式代碼區塊用於命令範例、多行程式代碼範例、查詢語言和輸出。 有兩種方式可以指出文章檔案中的文字區段是一個程式代碼區塊：用三個反引號將它框起來（```），或將它縮排。

請勿使用縮排，因為這樣很容易出現錯誤，且當另一位作者需要編輯您的文章時，可能難以理解您的意圖。

隔離的程式代碼區塊可以包含選擇性標記，指出區塊中包含的語言語法。 發佈平臺支援 語言標籤清單。 語言標記用於在網頁上顯示文章時進行語法高亮顯示。 語言標籤不區分大小寫，但您應該使用小寫，除非有幾個特殊情況。

• 沒有標記的程式代碼柵欄可用於語法區塊或不需要語法醒目提示的其他內容類型。
• 顯示命令輸出時，請使用帶有語言標籤 Output 的程式碼框。 轉譯的方塊會標示為 [輸出 ]，而且沒有語法醒目提示。
• 如果輸出是特定支持的語言，請使用適當的語言標記。 例如，許多命令都會輸出 JSON，因此請使用 json 標記。
• 如果您使用不支援的語言標記，程式代碼區塊將會顯示，但不會有語法高亮。 語言標籤會成為網頁上轉譯程式代碼方塊的標籤。 請將標籤大寫，讓標籤在網頁上以大寫顯示。

後續步驟

PowerShell 樣式指南