Markdown 最佳实践

本文提供了在我们的文档中使用 Markdown 的具体指南。这不是 Markdown 教程，而是在 PowerShell 文档中列出了 Markdown 的具体规则和最佳实践。如果您需要 Markdown 教程，请参阅此 Markdown 备忘单。

构建我们文档的 Microsoft 开放发布系统 (OPS) 使用 markdig 来处理 Markdown 文档。 Markdig 根据最新 CommonMark 规范的规则解析文档。 OPS 遵循 CommonMark 规范，并添加了一些针对平台特定功能的扩展，例如表格和警报。

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

我们使用 VS Code 中的 markdownlint 扩展来强制执行我们的样式和格式规则。此扩展作为学习创作包的一部分安装。

空行、空格和制表符

空行也表示 Markdown 中块的结束。

• 不同类型的 Markdown 块之间应该有一个空格——例如，段落和列表或标题之间。
• 不要使用多个空行。多个空行在 HTML 中呈现为单个空行，因此不需要额外的空行。
• 在代码块内，连续的空行会破坏代码块。

间距在 Markdown 中很重要。

• 删除行尾多余的空格。尾随空格可以改变 Markdown 的渲染方式。
• 始终使用空格而不是制表符（硬制表符）。

标题和标题

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

• 使用句子大小写 - 仅专有名词和标题或标题的第一个字母应大写
• # 和标题的第一个字母之间必须有一个空格
• 标题应由一个空行包围
• 每个文件只有一份H1
• 标头级别应增加一——不要跳过级别
• 将深度限制为 H3 或 H4
• 避免在标题中使用粗体或其他标记

将行长度限制为 100 个字符

这适用于概念性文章和 cmdlet 参考。对于 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/ 文件夹中。

  • 在 media 文件夹下创建一个与您的文章文件名匹配的文件夹。将该文章的图像复制到该新文件夹。

支持以下图像文件类型：*.png、*.gif、*.jpeg、*.jpg >, *.svg

Markdown 扩展 - 警报框

学习创作包包含支持我们发布系统独有功能的工具。警报是一个 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 语法[友好名称](url-or-path)。

• 发布系统支持三种类型的链接：

  • 网址链接
• 文件链接
• 交叉引用链接

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.

URL类型链接

• learn.microsoft.com 上其他文章的 URL 链接必须使用站点相对路径。创建站点相对链接的最简单方法是从浏览器复制 URL，然后从粘贴到 Markdown 的值中删除 https://learn.microsoft.com/en-us。
• 不要在 Microsoft 属性的 URL 或 Wikipedia 链接中包含区域设置（从 URL 中删除 /en-us）。

• 从 URL 中删除任何不必要的查询参数。应删除的示例：

  • ?view=powershell-5.1 - 用于链接到特定版本的 PowerShell
• ?redirectedfrom=MSDN - 当您从旧文章重定向到新位置时添加到 URL

文件类型链接

• 文件链接用于从一篇参考文章链接到另一篇参考文章，或者从一篇概念性文章链接到同一文档集中的另一篇概念性文章。

  • 如果您需要从概念性文章链接到参考文章，则必须使用 URL 链接。
• 如果您需要链接到另一个文档集中或跨存储库中的文章，则必须使用 URL 链接。

交叉引用链接

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

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

• cmdlet 参考的链接具有以下格式：xref:.