在 Azure DevOps 中使用 Markdown

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

在本文中，查找有关在 Azure DevOps 功能和 wiki Markdown 中使用 Markdown 的基本语法指南。 可以使用常见的 Markdown 约定 和 GitHub 风格的扩展。

使用 Markdown 向项目页面、自述文件、仪表板、拉取请求、 wiki 等添加格式、表格、图像等。

并非所有 Markdown 语法在 Azure DevOps 中的所有功能中都受支持。 下表链接到本文中的每个基本语法部分，并重点介绍哪些功能支持它。 例如，Azure DevOps 中的 Markdown 不支持 JavaScript 或 iframe，这意味着无法直接嵌入交互式元素，例如倒计时计时器。

有关详细信息，请参阅 “完成定义”（开发板）、 Markdown 小组件、 拉取请求、 自述文件以及 Wiki。

标头

使用标头结构化你的内容。 标题将较长的内容分段，使其更易于阅读。

若要设置标题，请使用哈希字符 #开始一行。 请通过在行首添加更多井号字符来创建副标题，从而整理您的备注，例如 ####。 最多可以使用六个级别的标题。

示例：

# 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 小组件 |拉取请求 |自述文件 |维基

通过将文本分解为段落或换行符，使文本更易于阅读。

拉取请求

在拉取请求注释中，选择 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。

在段落之间添加一个空格。

块引用

引用以前的批注或文本以设置批注或文本的上下文。 用 > 前缀标记单行文本内容。 使用许多 > 字符嵌套带引号的文本。 使用相同级别的>元素跨多行来引用文本块。

示例：

> Single line quote
>> Nested quote
>> multiple line
>> quote

结果：

水平规则

若要添加水平规则，请添加一系列短划线 ---。 包含该 --- 行的行上方的行必须为空。

示例：

above
 
----
below

结果：

以上

以下

强调（粗体、斜体、删除线）

支持于：完成的定义 |Markdown 小组件 |拉取请求 |自述文件 |维基

可以通过对字符应用粗体、斜体或删除线来强调文本：

• 应用斜体：用星号 * 或下划线包围文本 _
• 要应用粗体：用双星号 **包围文本。
• 若要应用删除线：用双平铺字符 ~~包围文本。

合并这些元素以对文本应用强调。

示例：

Use _emphasis_ in comments to express **strong** opinions and point out ~~corrections~~  
**_Bold, italicized text_**  
**~~Bold, strike-through text~~**

结果：

在评论中使用 重点 表达 强烈的 意见并指出 更正
粗体、斜体文本粗体、删除线文本

代码高亮

使用代码高亮块标记建议的代码段。 若要指示代码范围，请在块开头和末尾的新行上用三个反引号（```）包装它。 若要表示代码内联，请用一个反引号（`）将其包围。

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`.``` 

结果：

To install the Microsoft Cross Platform Build & Release Agent, run the following command: `$ sudo npm install vsoagent-installer -g`.

在 Markdown 文件中，行开头有四个空格的文本会自动转换为代码块。

为代码块设置语言标识符，以在 highlightjs 中为任何受支持的语言启用语法突出显示。

``` language
code
```

更多示例：

``` js
const count = records.length;
```

const count = records.length;

``` csharp
Console.WriteLine("Hello, World!");
```

Console.WriteLine("Hello, World!");

建议更改

在拉取请求中，可以使用注释来建议文件中一行或多行的替换文本。 用户可以通过选择 “应用更改”轻松应用建议的更改。 此操作会将更改提交到拉取请求。

Markdown 小组件中输入的代码会以差异格式显示，其中每行都会以“-”和“+”作为前缀。

示例：

```suggestion
  for i in range(A, B+100, C):
```

有关详细信息，请参阅 “建议批注中的更改”。

表格

使用表组织结构化数据。 表格特别适用于描述函数参数、对象方法和其他名称与描述清晰对应的数据。

• 把每个表格行单独放在一行上。
• 使用管道字符 |分隔表格单元格。
• 在表格中使用管道字符时，需要使用反斜杠进行转义 \|。
• 表的前两行设置列标题和表中元素的对齐方式。
• 使用冒号（:）在表格标题与正文之间进行分隔，并指定列对齐方式（左对齐、居中对齐、右对齐）。
• 若要开始一个新行，请使用 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 |  

结果：

列表

使用列表来组织相关项目。 可以添加数字编号的有序列表或仅用项目符号标记的无序列表。 有序列表的每个项目以数字加句号开头。 无序列表以 - 开始。

每个列表项都要另起一行。 在 Markdown 文件或小组件中，在换行符开始新段落之前输入两个空格，或连续输入两个换行符以开始新段落。

有序列表或编号列表

示例：

1. First item.
1. Second item.
1. Third item.

结果：

1. 第一项。
2. 第二项。
3. 第三项。

项目符号列表

示例：

- 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

结果：

1. 第一项。
   • 项目 1
   • 项目 2
   • 项目 3
2. 第二项。
   • 嵌套项 1
     • 进一步嵌套的项目 1
     • 更深层嵌套项2
     • 进一步嵌套的项目 3
   • 嵌套项 2
   • 嵌套项 3

链接

在拉取请求注释和 Wiki 中，HTTP 和 HTTPS URL 会自动格式化为链接。 可以通过输入 # 键和工作项 ID，然后从列表中选择工作项来链接到工作项。

通过在#前加上反斜杠（\）来避免工作项的自动建议。 当您想要使用 # 颜色的十六进制代码时，此操作非常有用。

在 Markdown 文件和小组件中，可以使用标准的 Markdown 链接语法为 URL 设置文本超链接：

[Link Text](Link URL)

链接到同一 Git 或 Team Foundation 版本控制（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)

示例：

[C# language reference](/dotnet/csharp/language-reference/)

结果：

C# 语言参考

源代码控制中的相对链接

源代码管理文件的链接根据是在欢迎页面还是 Markdown 小组件中指定它们，以不同的方式进行解释。 系统按如下所示解释相对链接：

• 欢迎页： 相对于存在欢迎页的源代码管理存储库的根目录
• Markdown 小部件： 相对于团队项目集合 URL 基础

例如：

锚点链接

在 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)

还可以引用另一个 Markdown 文件中的标题：

[text to display](./target.md#heading-id)  

[text to display](/page-name#section-name)

映像

若要突出显示问题或使事情更有趣，可以将图像和动画 GIF 添加到拉取请求的以下方面。

• 注释
• Markdown 文件
• Wiki 页面

使用以下语法添加图像：

![Text](URL)

示例：

![Illustration to use for new users](https://azurecomcdn.azureedge.net/cvt-779fa2985e70b1ef1c34d319b505f7b4417add09948df4c5b81db2a9bad966e5/images/page/services/devops/hero-images/index-hero.jpg)

结果：

图像文件的路径可以是相对路径或 Git 或 TFVC 中的绝对路径，就像链接中另一个 Markdown 文件的路径一样。

• 相对路径： ![Image alt text](./image.png)
• Git 中的绝对路径： ![Image alt text](/media/markdown-guidance/image.png)
• TFVC 中的绝对路径： ![Image alt text]($/project/folder/media/markdown-guidance/image.png)
• 调整图像大小： IMAGE_URL =WIDTHxHEIGHT

  注释

  请务必在等号之前包含空格。

  • 示例：![Image alt text]($/project/folder/media/markdown-guidance/image.png =500x250)
  • 还可以通过省略 HEIGHT 值来仅指定 WIDTH：IMAGE_URL =WIDTHx

清单或任务列表

轻松任务列表是在 PR 说明或 Wiki 页面中跟踪待办事项进度的好方法，无论是作为拉取请求的创建者还是审阅者。 选择 Markdown 工具栏以开始或将格式应用于所选文本。

使用 [ ] 或 [x] 支持清单。 在清单前加上-<space> 或 1.<space>（可以是任何数字）。

示例 - 将任务列表 Markdown 应用于突出显示的列表

若要通过选中框将项目标记为已完成，需要在添加任务列表后手动编辑 markdown 并修改语法。

示例 - 将列表格式化为任务列表

- [ ] A  
- [ ] B  
- [ ] C  
- [x] A  
- [x] B  
- [x] C  

结果：

表情符号

在拉取请求的评论和 Wiki 页面中，可以使用表情符号增添趣味性或表达情感，并对请求中的评论作出回应。 输入你感觉被 : 字符包围的内容，以在文本中获取匹配的表情符号。 我们支持 大多数 表情符号。

示例：

:smile:
:angry:

结果：

若要转义表情符号，请使用 ` 字符将其括起来。

示例：

`:smile:` `:)` `:angry:`

结果：

:smile: :) :angry:

忽略或转义 Markdown 语法以输入特定字符或文本字符

附件

在拉取请求注释和 Wiki 页面中，可以附加文件来说明你的观点，或者提供建议背后的更详细的推理。 若要附加文件，请将其拖放到批注字段或 Wiki 页面编辑体验中。 还可以从 Wiki 页面中的“格式”窗格中选择批注框右上角的 纸条 。

如果剪贴板上有图像，则可以将其粘贴到批注框或 Wiki 页面中，并直接呈现到批注或 Wiki 页面中。

附加非图像文件会在批注中创建指向该文件的链接。 若要更改链接中显示的文本，请更新括号之间的说明文本。 附加的图像文件会自动嵌入到您的评论或 Wiki 页面中。 使用附件保存或更新批注或 Wiki 页面。 然后，可以看到附加的图像，并选择用于下载附加文件的链接。

附件支持以下文件格式：

数学表示法和字符

我们在 Wiki 页面和拉取请求中支持行内和块级 KaTeX 表示法。 请参阅以下受支持的元素：

• 符号
• 希腊文字母
• 数学运算符
• 权力和索引
• 分数和二项式
• 其他 KaTeX 支持的元素

若要包括数学表示法，请将数学表示法与 $ 内联符号和 $$ 块符号括起来，如以下示例所示：

示例：希腊文字符

$
\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
$$     

结果：

在 Wiki 中使用 Markdown

以下指南显示了用于 Azure DevOps wiki 的 Markdown 语法。

::: mermaid
<mermaid diagram syntax>
:::

::: mermaid
sequenceDiagram
    Christie->>Josh: Hello Josh, how are you?
    Josh-->>Christie: Great!
    Christie->>Josh: See you later!
:::

::: mermaid
gantt
    title A Gantt chart
    dateFormat YYYY-MM-DD
    excludes 2022-03-16,2022-03-18,2022-03-19
    section Section

    A task          :a1, 2022-03-07, 7d
    Another task    :after a1 , 5d
:::

:::mermaid
graph LR;
    A[Hard edge] -->|Link text| B(Round edge) --> C{Decision}
    C -->|One| D[Result one]
    C -->|Two| E[Result two]
:::

:::mermaid
classDiagram
    Creature <|-- Superman
    Creature <|-- Vampire
    Creature <|-- Diavolo
    Creature: +int size
    Creature: +int weight
    Creature: +isBenign()
    Creature: +power()
    class Superman{
        +String currentName
        +fly()
        +heal()
    }
    class Vampire{
        -int age
        -canBite()
    }
    class Diavolo{
        +bool is_serving
        +heat()
    }
:::

:::mermaid
stateDiagram-v2
    [*] --> Active
    state Active {
        [*] --> NumLockOff
        NumLockOff --> NumLockOn : EvNumLockPressed
        NumLockOn --> NumLockOff : EvNumLockPressed
        --
        [*] --> CapsLockOff
        CapsLockOff --> CapsLockOn : EvCapsLockPressed
        CapsLockOn --> CapsLockOff : EvCapsLockPressed
        --
        [*] --> ScrollLockOff
        ScrollLockOff --> ScrollLockOn : EvScrollLockPressed
        ScrollLockOn --> ScrollLockOff : EvScrollLockPressed
    }
:::

:::mermaid
journey
    title Home office day
    section Go to work
      Wake up: 1: Me, Dog
      Take shower: 2: Me
      Go downstairs: 3: Me, Dog
      Make coffee: 4: Me
      Have a breakfast: 5: Me, Dog
      Go upstairs: 3: Me, Dog
      Do work: 1: Me, Dog
    section Go home
      Go downstairs: 3: Me, Dog
      Sit down: 5: Me
:::

:::mermaid
pie title Fishermans in countries
    "Norway" : 684
    "Sweeden" : 234
    "Switzerland" : 10
:::

:::mermaid
requirementDiagram
    requirement development_req {
    id: 1
    text: requirements spec.
    risk: medium
    verifymethod: test
    }
    element test_suite {
    type: manual test
    }
    test_suite - verifies -> development_req
:::

# A collapsible section with markdown
<details>
  <summary>Click to expand!</summary>

  ## Heading
  1. A numbered
  2. list
     * With some
     * Sub bullets
</details>

::: video
<iframe width="640" height="360" src="https://www.youtube.com/embed/OtqFyBA6Dbk" allowfullscreen style="border:none"><iframe>
:::

::: query-table <queryid>
:::

从 Wiki 页面链接到工作项

输入井号 （#），然后输入工作项 ID。

在 Wiki 页面中使用 HTML 标记

在 Wiki 页面中，还可以使用 HTML 标记创建丰富的内容。

<p>
 
 [A Markdown link](https://microsoft.com) 
</p>

示例 - 嵌入视频

<video src="path of the video file" width=400 controls>
</video>

<video src="https://sec.ch9.ms/ch9/7247/7c8ddc1a-348b-4ba9-ab61-51fded6e7247/vstswiki_high.mp4" width=400 controls>
</video>

示例 - 格式文本格式

<p>This text needs to <del>strikethrough</del> <ins>since it is redundant</ins>!</p>
<p><tt>This text is teletype text.</tt></p>
<font color="blue">Colored text</font>
<center>This text is center-aligned.</center>
<p>This text contains <sup>superscript</sup> text.</p>
<p>This text contains <sub>subscript</sub> text.</p>
<p>The project status is <span style="color:green;font-weight:bold">GREEN</span> even though the bug count / developer may be in <span style="color:red;font-weight:bold">red.</span> - Capability of span
<p><small>Disclaimer: Wiki also supports showing small text</small></p>
<p><big>Bigger text</big></p>

结果：

相关文章

• “项目”页或“欢迎”页
• README 文件
• Markdown 小组件
• 仪表板
• 小组件目录
• 添加和编辑 Wiki 页面