基本 Markdown 用法的语法指南
Azure DevOps Services | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018
重要
若要查看可用于你的平台的内容，请确保从目录上方的版本选择器中选择本文的正确版本。 功能支持会有所不同，具体取决于你使用的是 Azure DevOps Services 还是本地版本的 Azure DevOps Server（之前称为 Team Foundation Server (TFS)）。
若要了解正在使用哪个本地版本，请查看我使用的是哪个平台/版本？
可在此处找到一些基本 Markdown 语法指南和有关在 Azure DevOps 功能中使用 Markdown 的具体指南。 可以使用常见的 Markdown 约定 和 GitHub 风格扩展。
在正确的时间获得正确的指导对于成功至关重要。 使用 Markdown 向项目页面、自述文件、仪表板和拉取请求注释添加丰富的格式、表格和图像。
有关 Wiki 页面支持的更多语法，请参阅 Wiki Markdown 指南。
可以使用 Markdown 在以下方面提供指导：
注意
TFS 2018.2 及更高版本中支持代码存储库中的丰富 Markdown 呈现。 可以在代码存储库中创建丰富的 README.md 文件。 代码存储库中 MD 文件的 Markdown 呈现支持 HTML 标记、块引号、表情符号、图像大小调整和数学公式。 在 Wiki 中呈现 Markdown 和代码中的 MD 文件中存在奇偶校验。
重要
并非所有 Markdown 语法在所有功能中都受支持。 本文中的每个部分都标识了在行 中 支持语法的功能。
标头
支持：完成|的定义Markdown 小组件|拉取请求|自述文件|Wikis
使用标头构造注释。 标头可分割较长注释，使它们更易于阅读。
以哈希字符 # 作为行的开头来设置标题。 例如 ####，通过启动包含更多哈希字符的行，使用子标题组织备注。 支持最多六个级别的标题。
示例：
# This is a H1 header
## This is a H2 header
### This is a H3 header
#### This is a H4 header
##### This is a H5 header
结果：
段落和换行符
支持：完成|的定义Markdown 小组件|拉取请求|自述文件|Wikis
通过将文本分解为段落或换行符，使文本更易于阅读。
拉取请求
在拉取请求注释中，选择 Enter 以插入换行符，并在新行上开始文本。
示例 - 拉取请求注释：
Add lines between your text with the **Enter** key. Your text gets better spaced and makes it easier to read.
结果：
使用 Enter 键在文本之间添加行。
文本空间越好，更易于阅读。
Markdown 文件或小组件
在 Markdown 文件或小组件中，在换行符前输入两个空格，然后选择 Enter 以开始新段落。
示例 - Markdown 文件或小组件：
Add two spaces before the end of the line, and then select **Enter**.(space, space, Enter) A space gets added in between paragraphs.
结果：
在行末尾添加两个空格，然后选择 Enter。
在段落之间添加空格。
块引用
支持：完成|的定义Markdown 小组件|拉取请求|自述文件|Wikis
为批注或文本设置上下文的上一批批注或文本引用。
用文本 > 前面的单行引用文本。 使用许多 > 字符嵌套带引号的文本。
使用跨多行的相同级别的 > 文本行的引号块。
示例：
> Single line quote >> Nested quote >> multiple line >> quote
结果：
水平规则
支持：完成|的定义Markdown 小组件|拉取请求|自述文件|Wikis
若要添加水平规则，请添加一系列短划线 ---的线条。 包含该 --- 行的行上方的行必须为空。
示例：
above ---- below
结果：
以上
下面
强调（粗体、斜体、删除线）
支持：完成|的定义Markdown 小组件|拉取请求|自述文件|Wikis
可以通过对字符应用粗体、斜体或删除线来强调文本：
- 要应用斜体：将文本括在星号
*或下划线_中 - 要应用粗体：将文本括在双星号
**中。 - 要应用删除线：将文本括在双波浪号
~~中。
合并这些元素以将强调应用于文本。
注意
没有支持下划线文本的 Markdown 语法。 在 Wiki 页面中，可以使用 HTML <u> 标记生成带下划线的文本。 例如， <u>underlined text</u> 生成 带下划线的文本。
备注
没有支持下划线文本的 Markdown 语法。 在 TFS 2018.2 及更高版本中的 Wiki 页面中，可以使用 HTML <u> 标记生成带下划线的文本。 例如， <u>underlined text</u> 生成 带下划线的文本。
示例：
Use _emphasis_ in comments to express **strong** opinions and point out ~~corrections~~ **_Bold, italicized text_** **~~Bold, strike-through text~~**
结果：
Use emphasis in comments to express strong opinions and point out corrections
粗体、斜体文本粗体、删除线文本
代码突出显示
支持：拉取请求|自述文件|Wikis
使用代码突出显示块突出显示建议的代码段。
若要指示代码范围，请在块的开头和末尾用三个反杆引号 (```) 换行。 若要指示代码内联，请用一个反杆引号包装它， ` () 。
注意
Markdown 小组件中输入的代码突出显示会将代码呈现为纯预格式化文本。
示例：
``` sudo npm install vsoagent-installer -g ```
结果：
sudo npm install vsoagent-installer -g
示例：
To install the Microsoft Cross Platform Build & Release Agent, run the following: `$ sudo npm install vsoagent-installer -g`.
结果：
若要安装 Microsoft 跨平台生成&发布代理，请运行以下命令： $ sudo npm install vsoagent-installer -g
在 Markdown 文件中，行开头有四个空格的文本会自动转换为代码块。
为代码块设置语言标识符，以在 highlightjs 版本 v9.10.0 中为任何受支持的语言启用语法突出显示。
``` language code ```
更多示例：
``` js const count = records.length; ```
const count = records.length;
``` csharp
Console.WriteLine("Hello, World!");
```
Console.WriteLine("Hello, World!");
表
受支持：Markdown 小组件|拉取请求|自述文件|Wikis
使用表组织结构化的数据。 表对于描述函数参数、对象方法和其他具有明确名称的说明映射的数据特别有用。 可以在拉取请求、wiki 和 Markdown 文件（如 README 文件和 Markdown 小组件）中设置表的格式。
- 将每个表行放在其自己的行上
- 使用竖线
|分隔表单元格 - 表的前两行在表中设置列标头和元素的对齐方式
- 在划分表的标头和正文时，使用冒号 (
:) 来指定列的对齐方式（左对齐、居中、右对齐） - 若要开始新行，使用 HTML 换行符标记 (
<br/>)（在 Wiki 中有效，在其他位置无效） - 请确保以 CR 或 LF 结束每一行。
- 工作项或拉取请求之前和之后需要空格， (PR) 表单元格中提及。
示例：
| Heading 1 | Heading 2 | Heading 3 |
|-----------|:-----------:|-----------:|
| Cell A1 | Cell A2 | Cell A3 |
| Cell B1 | Cell B2 | Cell B3<br/>second line of text |
结果：
| 标题 1 | Heading 2 | Heading 3 |
|---|---|---|
| Cell A1 | Cell A2 | Cell A3 |
| Cell B1 | Cell B2 | Cell B3 second line of text |
列表
支持：完成|的定义Markdown 小组件|拉取请求|自述文件|Wikis
使用列表组织相关项。 可以为排序列表添加编号，或者为未排序的列表仅添加项目符号。
排序列表以数字开头，后跟每个列表项和句号。 未排序的列表以 - 开头。 在新行上开始每个列表项。 在 Markdown 文件或小组件中，在换行符开始新段落之前输入两个空格，或连续输入两个换行符以开始新段落。
排序或编号列表
示例：
1. First item.
1. Second item.
1. Third item.
结果：
- First item.
- Second item.
- Third item.
项目符号列表
示例：
- Item 1
- Item 2
- Item 3
结果：
- 第 1 项
- 第 2 项
- 第 3 项
嵌套列表
示例：
1. First item.
- Item 1
- Item 2
- Item 3
1. Second item.
- Nested item 1
- Further nested item 1
- Further nested item 2
- Further nested item 3
- Nested item 2
- Nested item 3
结果：
- First item.
- 第 1 项
- 第 2 项
- 第 3 项
- Second item.
- Nested item 1
- 进一步嵌套的项目 1
- 进一步嵌套的项目 2
- 进一步嵌套的项 3
- Nested item 2
- Nested item 3
- Nested item 1
链接
支持：完成|的定义Markdown 小组件|拉取请求|自述文件|Wikis
在拉取请求注释和 Wiki 中，HTTP 和 HTTPS URL 会自动格式化为链接。 可以通过输入 # 键和工作项 ID，然后从列表中选择工作项，链接到工作项。
通过在反斜杠 () \ 前缀来#避免工作项的自动建议。 如果要用于 # 颜色十六进制代码，此操作可能很有用。
在 Markdown 文件和小组件中，可以使用标准 Markdown 链接语法为 URL 设置文本超链接：
[Link Text](Link URL)
链接到同一 Git 或 TFVC 存储库中的另一个 Markdown 页面时，链接目标可以是存储库中的相对路径或绝对路径。
欢迎页面支持的链接：
- 相对路径：
[text to display](target.md) - Git 中的绝对路径：
[text to display](/folder/target.md) - TFVC 中的绝对路径：
[text to display]($/project/folder/target.md) - URL：
[text to display](http://address.com)
Markdown 小组件支持的链接：
- URL：
[text to display](http://address.com)
Wiki 支持的链接：
- Wiki 页面的绝对路径：
[text to display](/parent-page/child-page) - URL：
[text to display](http://address.com)
注意
2017.1 及更高版本不支持指向文件共享 file:// 上文档的链接。 出于安全目的，已实施此限制。
有关如何从欢迎页面或 Markdown 小组件指定相对链接的信息，请参阅 源代码管理相对链接。
示例：
[C# language reference](/dotnet/csharp/language-reference/)
结果：
源代码管理相对链接
源代码管理文件的链接根据是在欢迎页面还是 Markdown 小组件中指定它们，以不同的方式解释。 系统按如下所示解释相对链接：
- 欢迎页： 相对于存在欢迎页的源代码管理存储库的根目录
- Markdown 小组件： 相对于团队项目集合 URL 基
例如：
| 欢迎页面 | Markdown 小组件等效 |
|---|---|
| /BuildTemplates/AzureContinuousDeploy.11.xaml | /DefaultCollection/Fabrikam Fiber/_versionControl#path=$/Tfvc Welcome/BuildTemplates/AzureContinuousDeploy.11.xaml |
| ./page-2.md | /DefaultCollection/Fabrikam Fiber/_versionControl#path=$/Tfvc Welcome/page-2.md |
定位标记链接
在 Markdown 文件中，定位点 ID 在呈现为 HTML 时分配给所有标题。 该 ID 为标题文本，空格替换为短划线 (-) 且字母全小写。 一般情况下，以下约定适用：
- 将忽略文件名中的标点符号和前导空格
- 大写字母转换为下写字母
- 字母之间的空格转换为短划线 () 。
示例：
###Link to a heading in the page
结果：
到某部分的定位标记链接的语法...
[Link to a heading in the page](#link-to-a-heading-in-the-page)
ID 都是小写的，并且链接区分大小写，因此请务必使用小写，即使标题本身使用大写。
还可以引用另一个 Markdown 文件中的标题：
[text to display](./target.md#heading-id)
在 Wiki 中，还可以引用另一页中的标题：
[text to display](/page-name#section-name)
映像
受支持：Markdown 小组件|拉取请求|自述文件|Wikis
若要突出显示问题或使事情更有趣，可以向拉取请求中的以下方面添加图像和动画 GIF：
- 注释
- Markdown 文件
- Wiki 页面
使用以下语法添加图像：
示例：
结果：
图像文件的路径可以是 Git 或 TFVC 中的相对路径或绝对路径，就像链接中另一个 Markdown 文件的路径一样。
- 相对路径：
 - Git 中的绝对路径：
 - TFVC 中的绝对路径：
 - 调整图像大小：
IMAGE_URL =WIDTHxHEIGHT备注
请务必在等号前包含空格。
- 示例：
 - 还可以通过退出 HEIGHT 值来仅指定 WIDTH：
IMAGE_URL =WIDTHx
- 示例：
清单或任务列表
支持：拉取请求|Wikis
轻型任务列表是作为拉取请求创建者或审阅者在 PR 说明或 Wiki 页面中跟踪操作进度的好方法。 选择 Markdown 工具栏以开始或将格式应用于所选文本。
可以使用 [ ] 或 [x] 支持清单。 清单前面有任一 -<space> 数字或 1.<space> (任何数字) 。
示例 - 将任务列表 Markdown 应用于突出显示的列表
添加任务列表后，可以选中复选框以将项目标记为已完成。 这些操作以 [] 和 [x] 表示并存储在 Markdown 中的注释中。
示例 - 将列表格式化为任务列表
- [ ] A - [ ] B - [ ] C - [x] A - [x] B - [x] C
结果：
备注
不支持表单元格中的清单。
表情
支持：拉取请求|Wikis
在拉取请求注释和 Wiki 页面中，可以使用表情符号添加字符并响应请求中的注释。 输入你感觉被 : 字符包围的内容，以在文本中获取匹配的表情符号。 支持 完整的表情符号集 。
示例：
:smile: :angry:
结果：
若要转义表情符号，请使用 “字符将其括起来。
示例：
`:smile:` `:)` `:angry:`
结果：
:smile: :) :angry:
忽略或转义 Markdown 语法以输入特定字符或文本字符
支持：完成|的定义Markdown 小组件|拉取请求|自述文件|Wikis
语法
示例/说明
若要插入以下字符之一，请使用 \ (反斜杠) 前缀。
\反斜線
`、反杆
_强调
{}，大括号
[]、方括号
()括弧
#，哈希标记
+、加号 -、减号 (连字符) .，句点
!，感叹号 *，星号
有关插入特殊字符的一些示例：
输入 \\ 以获取 \
输入 \_ 获取 _
输入 \# 以获取#
输入 \( 以获取 (
输入 \. 以获取 。
输入 \! 以获取！
输入 \* 以获取 *
Attachments
支持：拉取请求|自述文件|Wikis
在拉取请求注释和 Wiki 页面中，可以附加文件来说明你的观点，或者提供更详细的建议背后的推理。 若要附加文件，请将其拖放到批注字段或 Wiki 页面编辑体验中。 还可以选择批注框右上角的 剪纸或 Wiki 页面中的格式窗格。
如果剪贴板中有图像，则可以将其从剪贴板粘贴到批注框或 Wiki 页面中，并直接呈现到批注或 Wiki 页面中。
附加非图像文件会在批注中创建指向该文件的链接。 更新括号之间的说明文本以更改链接中显示的文本。 附加的图像文件直接呈现到批注或 Wiki 页面中。 保存或更新带有附件的注释或 Wiki 页面后，可以看到附加的图像并选择用于下载附加文件的链接。
附件支持以下文件格式。
| 类型 | 文件格式 |
|---|---|
| 代码 | CS (.cs) 、可扩展标记语言 (.xml) 、JavaScript 对象表示法 (.json) ， 超文本标记语言 (.html、.htm) 、Layer (.lyr) 、Windows PowerShell 脚本 (.ps1) 、Roshal Archive (.rar) 、远程桌面连接 (.rdp) 、结构化查询语言 (.sql) - 注意：PR 注释中不允许使用代码附件 |
| 压缩文件 | ZIP (.zip) 和 GZIP (.gz) |
| 文档 | Markdown (.md) 、Microsoft Office Message (.msg) 、Microsoft Project (.mpp) 、Word (.doc 和 .docx) 、Excel (.xls、.xlsx 和 .csv) 、Powerpoint (.ppt 和 .pptx) 、文本文件 (.txt) 和 PDF (.pdf) |
| 映像 | PNG (.png) 、GIF (.gif) 、JPEG (.jpeg和.jpg) 图标 (.ico) |
| Visio | VSD (.vsd 和 .vsdx) |
| 视频 | MOV (.mov) 、MP4 (.mp4) |
备注
拉取请求中不支持所有文件格式，例如 Microsoft Office 消息 (.msg) 文件。
数学表示法和字符
支持：拉取请求|Wikis
Wiki 页面和拉取请求都支持内联和块 KaTeX 表示法。 包含以下受支持的元素：
- 符号
- 希腊文字母
- 数学运算符
- 权力和索引
- 分数和二项式
- 其他 KaTeX 支持的元素
若要包括数学表示法，请将数学表示法与符号 $ 、内联表示法和 $$ 块括起来，如以下示例所示：
注意
Wiki 页面中支持此功能，并请求 TFS 2018.2 或更高版本。
示例：希腊文字符
$
\alpha, \beta, \gamma, \delta, \epsilon, \zeta, \eta, \theta, \kappa, \lambda, \mu, \nu, \omicron, \pi, \rho, \sigma, \tau, \upsilon, \phi, ...
$
$\Gamma, \Delta, \Theta, \Lambda, \Xi, \Pi, \Sigma, \Upsilon, \Phi, \Psi, \Omega$
结果：
示例：代数表示法
Area of a circle is $\pi r^2$
And, the area of a triangle is:
$$
A_{triangle}=\frac{1}{2}({b}\cdot{h})
$$
结果：
示例：求和和整型
$$
\sum_{i=1}^{10} t_i
$$
$$
\int_0^\infty \mathrm{e}^{-x}\,\mathrm{d}x
$$
结果：
