通过

Markdown 最佳做法

本文提供有关在文档中使用 Markdown 的具体指导。 这不是 Markdown 的教程。 如果需要 Markdown 教程，请参阅此 Markdown 速查表。

生成文档的生成管道使用 markdig 来处理 Markdown 文档。 Markdig 根据最新 CommonMark 规范的规则分析文档。 OPS 遵循 CommonMark 规范，并为特定于平台的功能（如表和警报）添加一些扩展。

CommonMark 规范对某些 Markdown 元素的构造更加严格。 请密切关注本文档中提供的详细信息。

我们在 VS Code 中使用 markdownlint 扩展来强制实施样式和格式规则。 此扩展作为 Learn Authoring Pack 的一部分安装。

空白行、空格和制表符

空白行还表示 Markdown 中块的末尾。

  • 在不同类型的 Markdown 块之间放置单个空白;例如，段落和列表或标题之间。
  • 不要使用多个空白行。 多个空白行以 HTML 形式呈现为单个空白行，因此不需要额外的空白行。
  • 不要使用将多个连续空白行放在代码块中，连续的空白行会中断代码块。

在 Markdown 中，间距非常重要。

  • 删除行尾的额外空格。 尾随空格可以更改 Markdown 的呈现方式。
  • 始终使用空格而不是制表符（硬制表符）。

标题

仅使用 ATX 标题（#样式，而不是=-样式标题）。

  • 使用句首大写形式 - 只对专有名词和标题的首字母使用大写形式
  • 在 # 和标题的第一个字母之间包括一个空格
  • 在标题的上下添加一个空行
  • 在每个文档中不要使用多个 H1
    • 它应该是第一个标题
    • 它应与文章的标题匹配
  • 将标头级别递增一级 - 不要跳过级别
  • 将深度限制为 H3 或 H4
  • 避免在标头中使用粗体或其他标记

将行长度限制为 100 个字符

对于概念文章和 cmdlet 参考，请将行限制为 100 个字符。 对于 about_ 文章，将行长度限制为 79 个字符。 限制行长度可以改进 git 差异和历史记录的可读性。 它还使其他作家更容易做出贡献。

使用 VS Code 中的 “重排 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 创作包包含支持发布系统特有的功能的工具。 警报是一种 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，除非该 URL 对目标网站无效。

  • 链接必须具有友好名称，通常是链接文章的标题

  • 避免在超链接的方括号内使用反引号、粗体或其他标记。

  • 记录特定 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
  • 在 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）
  • 文件链接用于从一个引用文章链接到另一个引用项目，或从一个概念文章链接到同一文档集中的另一篇文章。
    • 如果需要从概念文章链接到参考文章，则必须使用 URL 链接。
    • 如果需要链接到另一个文档集中或跨存储库的文章，则必须使用 URL 链接。
  • 使用相对文件路径（例如： ../folder/file.md
  • 所有文件路径都使用正斜杠（/） 字符
  • 包括文件扩展名（例如 .md）

交叉引用链接是发布系统支持的一项特殊功能。 可以使用概念文章中的交叉引用链接链接到 .NET API 或 cmdlet 参考。

  • 有关 .NET API 参考的链接，请参阅中央《贡献者指南》中的文档链接的使用方法。

  • 指向 cmdlet 引用的链接具有以下格式：xref:<module-name>.<cmdlet-name>。 例如，要在 Get-Content 模块中链接到 cmdlet。

    [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 样式指南