GitLab 风格的 Markdown (GLFM)

GitLab 风格的 Markdown (GLFM) 是一种强大的标记语言，用于在 GitLab 用户界面中设置文本格式。 GLFM 具有以下特点：

• 支持代码、图表、数学公式和多媒体，可创建丰富内容。
• 通过交叉引用链接议题、合并请求和其他 GitLab 内容。
• 使用任务列表、表格和可折叠部分组织信息。
• 支持超过 100 种编程语言的语法高亮显示。
• 通过语义化标题结构和图像描述确保可访问性。

在 GitLab 界面中输入文本时，GitLab 会默认该文本采用 GitLab 风格的 Markdown 格式。

您可以在以下位置使用 GitLab 风格的 Markdown：

• 评论
• 议题
• 史诗
• 合并请求
• 里程碑
• 代码片段（片段必须以 .md 扩展名命名）
• 维基页面
• 仓库内的 Markdown 文档
• 发布

您也可以在 GitLab 中使用其他富文本文件。不过可能需要安装依赖项才能实现。有关更多信息，请参见 gitlab-markup gem 项目。

要查看 GitLab 对这些示例的具体渲染效果：

1. 复制相关的原始 Markdown 示例（而非示例的渲染版本）。
2. 将 Markdown 粘贴到 GitLab 中支持 Markdown 预览的位置，例如 议题或合并请求的评论或描述，或新的 Markdown 文件中。
3. 选择 预览 以查看 GitLab 渲染的 Markdown。

与标准 Markdown 的差异

GitLab 风格的 Markdown 包含以下内容：

• 基于 CommonMark 规范 的核心 Markdown 功能。
• 来自 GitHub 风格的 Markdown 的扩展。
• 专为 GitLab 打造的扩展。

所有标准 Markdown 格式在 GitLab 中都应能正常工作。部分标准功能通过附加功能进行了扩展，但不会影响标准用法。

以下功能是标准 Markdown 中没有的：

• 警告
• 以 HEX、RGB 或 HSL 表示的颜色块
• 描述列表
• 图表和流程图
• 表情符号
• 脚注
• 前置内容
• GitLab 特定引用
• 包含
• 占位符
• 内嵌差异
• 用 LaTeX 编写的数学公式和符号
• 删除线
• 目录
• 表格
• 任务列表
• 维基特定的 Markdown

以下功能是对标准 Markdown 的扩展：

Markdown 与可访问性

使用 GitLab 风格的 Markdown 时，您正在创建数字内容。 这些内容应尽可能便于所有受众访问。 以下列表并非详尽无遗，但它为 GitLab 风格的 Markdown 中一些需要特别注意的样式提供了指导：

可访问的标题

使用标题格式创建合理的标题结构。 页面上的标题结构应清晰易懂，就像一个好的目录一样。 确保页面上只有一个 h1 元素，不跳过标题级别，并且标题嵌套正确。

可访问的表格

为了使表格具有可访问性和可扫描性，表格不应有任何空单元格。 如果某个单元格没有有意义的值，可以考虑输入 不适用 或 无。

可访问的图像和视频

在 [替代文本] 中描述图像或视频。描述应准确、简洁且独特。 不要在描述中使用“图像为”或“视频为”。有关更多信息，请参见 WebAim 替代文本。

标题

使用 # 创建 1 到 6 级标题。

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

或者，对于一级和二级标题，可以使用下划线样式：

替代一级标题
======

替代二级标题
------

标题 ID 和链接

所有经 Markdown 渲染的标题都会自动获得可链接的 ID，但评论中的标题除外。

鼠标悬停时，指向这些 ID 的链接会显示出来，便于复制标题链接并在其他地方使用。

ID 是根据标题内容按照以下规则生成的：

1. 所有文本转换为小写。
2. 移除所有非单词文本（如标点符号或 HTML）。
3. 所有空格转换为连字符。
4. 连续两个或多个连字符转换为一个。
5. 如果已生成相同 ID 的标题，则会附加一个唯一的递增数字，从 1 开始。

示例：

# 这个标题中有空格
## 这个标题中有一个 :thumbsup:
# 这个标题中有 Unicode：한글
## 这个标题中有空格
### 这个标题中有空格
## 这个标题中有 3.5（和括号）
## 这个标题中有  多个空格和 --- 连字符

会生成以下链接 ID：

1. this-heading-has-spaces-in-it
2. this-heading-has-a-thumbsup-in-it
3. this-heading-has-unicode-in-it-한글
4. this-heading-has-spaces-in-it-1
5. this-heading-has-spaces-in-it-2
6. this-heading-has-35-in-it-and-parentheses
7. this-heading-has--multiple-spaces-and-----hyphens

换行

如果前一段文本以两个换行符结束，则会插入一个换行符（开始一个新段落）。例如，连续按两次 Enter 键。如果只使用一个换行符（按一次 Enter 键），下一句仍属于同一段落。如果您想避免长行换行并保持可编辑性，可以使用这种方法：

这是我们开始的一行。

这行较长，与上面一行之间有两个换行符，所以它是一个*单独的段落*。

这行也是一个单独的段落，但是……
这些行之间只有一个换行符，
所以它们*不会换行*，而是紧跟在同一段落的前一行之后。

渲染后，示例看起来类似：

这是我们开始的一行。

这行较长，与上面一行之间有两个换行符，所以它是一个单独的段落。

这行也是一个单独的段落，但是…… 这些行之间只有一个换行符， 所以它们不会换行，而是紧跟在同一段落的前一行之后。

新行

GitLab 风格的 Markdown 遵循 Markdown 规范来处理段落和换行。

段落是一行或多行连续的文本，由一个或多个空行（第一段末尾有两个换行符）分隔，如 换行 中所述。

需要更好地控制换行或软回车？在一行的末尾添加一个反斜杠或两个及以上空格，即可添加一个单行换行。连续两个换行符会创建一个新段落，段落之间有一个空行：

第一段。
同一段落中的另一行。
同一段落中的第三行，但这次以两个空格结束。<space><space>
直接位于第一段下方的新行。

第二段。
另一行，这次以反斜杠结束。\
由于前一个反斜杠，这里是新行。

渲染后，示例看起来类似：

第一段。 同一段落中的另一行。 同一段落中的第三行，但这次以两个空格结束。
直接位于第一段下方的新行。

第二段。 另一行，这次以反斜杠结束。
由于前一个反斜杠，这里是新行。

强调

您可以通过多种方式强调文本。使用斜体、粗体、删除线，或者将这些强调样式组合使用。

示例：

强调（即斜体），使用 *星号* 或 _下划线_。

强强调（即粗体），使用两个 **星号** 或 __下划线__。

组合强调，使用 **星号和 _下划线_**。

使用两个波浪线表示删除线。~~删除这段文字。~~

渲染后，示例看起来类似：

强调（即斜体），使用 星号 或 下划线。

强强调（即粗体），使用两个 星号 或 下划线。

组合强调，使用 星号和 下划线。

使用两个波浪线表示删除线。删除这段文字。

词中强调

避免对单词的一部分进行斜体处理，尤其是在处理经常出现多个下划线的代码和名称时。

GitLab 风格的 Markdown 会忽略单词中的多个下划线，以便更好地呈现讨论代码的 Markdown 文档：

perform_complicated_task

do_this_and_do_that_and_another_thing

but_emphasis is_desired _here_

渲染后，示例看起来类似：

perform_complicated_task

do_this_and_do_that_and_another_thing

but_emphasis is_desired here

如果您希望仅强调单词的一部分，仍然可以使用星号：

perform*complicated*task

do*this*and*do*that*and*another thing

渲染后，示例看起来类似：

performcomplicatedtask

dothisanddothatandanother thing

内嵌差异

使用内嵌差异标签，您可以显示 {+ 新增内容 +} 或 [- 删除内容 -]。

包裹标签可以是花括号或方括号：

- {+ 新增内容 1 +}
- [+ 新增内容 2 +]
- {- 删除内容 3 -}
- [- 删除内容 4 -]

但是，不能混合使用包裹标签：

- {+ 新增内容 +]
- [+ 新增内容 +}
- {- 删除内容 -]
- [- 删除内容 -}

差异高亮不能与 `内嵌代码` 一起使用。如果文本包含反引号（`），请转义每个反引号，在前面加上反斜杠 \：

- {+ 普通文本 +}
- {+ 包含 `反引号` 的文本 +}
- {+ 包含转义的 \`反引号\` 的文本 +}

水平分隔线

使用三个或更多连字符、星号或下划线创建水平分隔线：

---

***

___

渲染后，所有水平分隔线看起来都类似：

列表

您可以创建有序列表和无序列表。

对于有序列表，在每行的开头添加您希望列表开始的数字，如 1.，后跟一个空格。 在第一个数字之后，使用什么数字并不重要。有序列表会按垂直顺序自动编号，因此在同一个列表中所有项都重复使用 1. 是很常见的。如果您从非 1. 的数字开始，列表会以该数字作为第一个数字，并从那里开始递增计数。

示例：

1. 第一个有序列表项
2. 另一个项
   - 无序子列表。
1. 实际数字无关紧要，只要是数字即可
   1. 有序子列表
   1. 下一个有序子列表项
4. 还有一个项。

渲染后，示例看起来类似：

1. 第一个有序列表项
2. 另一个项
   • 无序子列表。
3. 实际数字无关紧要，只要是数字即可
   1. 有序子列表
   2. 下一个有序子列表项
4. 还有一个项。

对于无序列表，在每行的开头添加 -、* 或 +，后跟一个空格。不要在同一个列表中混合使用这些字符。

无序列表可以：

- 使用
- 连字符

它们也可以：

* 使用
* 星号

它们甚至可以：

+ 使用
+ 加号

渲染后，示例看起来类似：

无序列表可以：

• 使用
• 连字符

它们也可以：

• 使用
• 星号

它们甚至可以：

• 使用
• 加号

如果列表项包含多个段落，每个后续段落都应缩进至与列表项文本的起始位置相同的级别。

示例：

1. 第一个有序列表项

   第一项的第二段。

1. 另一个项

渲染后，示例看起来类似：

1. 第一个有序列表项

   第一项的第二段。

2. 另一个项

如果第一项的段落没有缩进适当数量的空格，该段落会显示在列表外部。 请使用正确数量的空格，以在列表项下方正确缩进。 例如：

1. 第一个有序列表项

  （第一项的段落缩进不正确。）

1. 另一个项

渲染后，示例看起来类似：

1. 第一个有序列表项

（第一项的段落缩进不正确。）

1. 另一个项

如果无序列表项的第一个子项是有序列表，且该有序列表不是从 1. 开始，则其前面必须有一个空行。

例如，带有空行：

- 无序列表项

  5. 第一个有序列表项

渲染后，示例看起来类似：

• 无序列表项

  5. 第一个有序列表项

如果缺少空行，第二个列表项会被视为第一个列表项的一部分：

- 无序列表项
  5. 第一个有序列表项

渲染后，示例看起来类似：

• 无序列表项 5. 第一个有序列表项

CommonMark 会忽略有序列表项和无序列表项之间的空行，并将它们视为单个列表的一部分。这些项会被渲染为 松散 列表。每个列表项都被包裹在段落标签中，因此具有段落间距和边距。 这会使列表看起来每个项之间有额外的间距。

例如：

- 第一个列表项
- 第二个列表项

- 另一个不同的列表

渲染后，示例看起来类似：

• 第一个列表项

• 第二个列表项

• 另一个不同的列表

CommonMark 会忽略空行，并将其渲染为一个带有段落间距的列表。

描述列表

描述列表是带有相应描述的术语列表。 每个术语可以有多个描述。 在 HTML 中，这由 <dl>、<dt> 和 <dd> 标签表示。

要创建描述列表，请将术语放在一行上，描述放在下一行并以冒号开头。

水果
: 苹果
: 橙子

蔬菜
: 西兰花
: 羽衣甘蓝
: 菠菜

您也可以在术语和描述之间留一个空行。

水果

: 苹果

: 橙子

任务列表

您可以在任何支持 Markdown 的地方添加任务列表。

• 在议题、合并请求、史诗和评论中，您可以选中这些框。
• 在其他所有地方，您不能选中这些框。必须通过在括号中添加或删除 x 来手动编辑 Markdown。

除了已完成和未完成状态外，任务还可以是不适用的。在议题、合并请求、史诗或评论中选中不适用的复选框没有任何效果。

要创建任务列表，请遵循有序或无序列表的格式：

- [x] 已完成的任务
- [~] 不适用的任务
- [ ] 未完成的任务
  - [x] 子任务 1
  - [~] 子任务 2
  - [ ] 子任务 3

1. [x] 已完成的任务
1. [~] 不适用的任务
1. [ ] 未完成的任务
   1. [x] 子任务 1
   1. [~] 子任务 2
   1. [ ] 子任务 3

要在表格中包含任务列表，请使用 HTML 列表标签或 HTML 表格。

链接

您可以通过多种方式创建链接：

- 这行显示一个 [内联样式链接](https://www.google.com)
- 这行显示一个 [指向同一目录中仓库文件的链接](permissions.md)
- 这行显示一个 [指向高一级目录中文件的相对链接](../_index.md)
- 这行显示一个 [带有标题文本的链接](https://www.google.com "这个链接会带您前往 Google！")

渲染后，示例看起来类似：

• 这行显示一个 内联样式链接
• 这行显示一个 指向同一目录中仓库文件的链接
• 这行显示一个 指向高一级目录中文件的相对链接
• 这行显示一个 带有标题文本的链接

使用标题 ID 锚点链接到页面中的特定部分：

- 这行链接到 [另一个 Markdown 页面上的某个部分，使用“#”和标题 ID](permissions.md#project-members-permissions)
- 这行链接到 [同一页面上的另一个部分，使用“#”和标题 ID](#heading-ids-and-links)

渲染后，示例看起来类似：

• 这行链接到 另一个 Markdown 页面上的某个部分，使用“#”和标题 ID
• 这行链接到 同一页面上的另一个部分，使用“#”和标题 ID

使用链接引用：

- 这行显示一个 [引用样式的链接，见下文][任意大小写的引用文本]
- 您可以 [使用数字作为引用样式的链接定义，见下文][1]
- 或者留空并使用 [链接文本本身][]，见下文。

一些文本表明引用链接可以在后面出现。

[任意大小写的引用文本]: https://www.mozilla.org/en-US/
[1]: https://slashdot.org
[链接文本本身]: https://about.gitlab.com/

渲染后，示例看起来类似：

• 这行是一个 引用样式的链接，见下文
• 您可以 使用数字作为引用样式的链接定义，见下文
• 或者留空并使用 链接文本本身，见下文。

一些文本表明引用链接可以在后面出现。

URL 自动链接

您输入文本中的几乎所有 URL 都会被自动链接：

- https://www.google.com
- https://www.google.com
- ftp://ftp.us.debian.org/debian/
- smb://foo/bar/baz
- irc://irc.freenode.net/
- http://localhost:3000

渲染后，示例看起来类似：

• https://www.google.com
• https://www.google.com
• ftp://ftp.us.debian.org/debian/
• smb://foo/bar/baz
• irc://irc.freenode.net
• http://localhost:3000

GitLab 特定引用

GitLab 风格的 Markdown 会渲染 GitLab 特定的引用。例如，您可以引用一个议题、一次提交、一个团队成员，甚至整个项目团队。GitLab 风格的 Markdown 会将该引用转换为链接，以便您在它们之间导航。所有对项目的引用都应使用项目 slug 而非项目名称。

此外，GitLab 风格的 Markdown 能识别某些跨项目引用，并且对于引用同一命名空间中的其他项目有简写形式。

GitLab 风格的 Markdown 能识别以下内容：

脚注：

1. 在 GitLab 16.9 中引入。 迭代周期引用的渲染格式始终为 [cadence:<ID>]。 例如，如果引用的迭代周期的 ID 为 1，则文本引用 [cadence:"计划"] 会渲染为 [cadence:1]。
2. 对于标签或里程碑，在 命名空间/项目 前添加一个 / 以指定确切的标签或里程碑，消除任何可能的歧义。

例如，使用 #123 引用一个议题时，输出会格式化为指向编号为 123 的议题的链接，文本为 #123。同样，指向编号为 123 的议题的链接会被识别并格式化为文本 #123。如果您不希望 #123 链接到议题，请在前面添加反斜杠 \#123。

此外，某些对象的链接也会被识别并格式化。 例如：

• 议题上的评论："https://gitlab.com/gitlab-org/gitlab/-/issues/1234#note_101075757"，渲染为 #1234 (comment 101075757)
• 议题的设计标签页："https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs"，渲染为 #1234 (designs)。
• 单个设计的链接："https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs/layout.png"，渲染为 #1234[layout.png]。

显示项目标题

要在议题、任务、目标、关键结果、合并请求或史诗的渲染链接中包含标题：

• 在引用的末尾添加一个加号 (+)。

例如，#123+ 这样的引用会渲染为 议题标题 (#123)。

像 https://gitlab.com/gitlab-org/gitlab/-/issues/1234+ 这样的 URL 引用也会被展开。

显示项目摘要

要在史诗、议题、任务、目标、关键结果或合并请求的渲染链接中包含扩展摘要：

• 在引用的末尾添加 +s。

摘要包含所引用项目的经办人、里程碑和健康状态（根据工作项类型适用）等信息。

例如，#123+s 这样的引用会渲染为 议题标题 (#123) • 第一个经办人、第二个经办人+ • v15.10 • 需要关注。

像 https://gitlab.com/gitlab-org/gitlab/-/issues/1234+s 这样的 URL 引用也会被展开。

如果经办人、里程碑或健康状态发生变化，要更新渲染的引用：

• 刷新页面。

悬停时预览评论

将鼠标悬停在评论链接上会显示评论的作者和第一行内容。

嵌入可观测性仪表板

您可以在描述和评论中嵌入 GitLab 可观测性 UI 仪表板，例如在史诗、议题和合并请求中。

要嵌入可观测性仪表板 URL：

1. 在 GitLab 可观测性 UI 中，复制地址栏中的 URL。
2. 将链接粘贴到评论或描述中。GitLab 风格的 Markdown 会识别该 URL 并显示来源。

表格

创建表格时：

• 第一行包含标题，用竖线字符 (|) 分隔。
• 第二行分隔标题和单元格。
  • 单元格中只能包含空格、连字符，以及（可选）用于水平对齐的冒号。
  • 每个单元格必须至少包含一个连字符，但向单元格添加更多连字符不会改变单元格的渲染效果。
  • 不允许包含除连字符、空格或冒号以外的任何内容
• 第三行及以后的行包含单元格值。
  • 单元格内容不能在 Markdown 中跨多行分隔，必须保持在单行，但可以很长。如果需要，您也可以包含 HTML <br> 标签来强制换行。
  • 单元格大小不必彼此匹配。它们是灵活的，但必须用竖线 (|) 分隔。
  • 您可以有空白单元格。
• 列宽是根据单元格内容动态计算的。
• 要在文本中使用竖线字符 (|) 而不是作为表格分隔符，必须转义它，在前面加上反斜杠 (\|)。

示例：

| 标题 1 | 标题 2 | 标题 3 |
| ---      | ---      | ---      |
| 单元格 1   | 单元格 2   | 单元格 3   |
| 单元格 4 | 单元格 5 较长 | 单元格 6 比其他单元格长得多，但没关系。当单元格对于显示尺寸来说太大时，文本最终会自动换行。 |
| 单元格 7   |          | 单元格 9   |

渲染后，示例看起来类似：

标题 1	标题 2	标题 3
单元格 1	单元格 2	单元格 3
单元格 4	单元格 5 较长	单元格 6 比其他单元格长得多，但没关系。当单元格对于显示尺寸来说太大时，文本最终会自动换行。
单元格 7		单元格 9

对齐方式

此外，您可以通过在第二行的“破折号”线的两侧添加冒号 (:) 来选择列中文本的对齐方式。这会影响列中的每个单元格：

| 左对齐 | 居中对齐 | 右对齐 |
| :---         | :---:    | ---:          |
| 单元格 1       | 单元格 2   | 单元格 3        |
| 单元格 4       | 单元格 5   | 单元格 6        |

渲染后，示例看起来类似：

左对齐	居中对齐	右对齐
单元格 1	单元格 2	单元格 3
单元格 4	单元格 5	单元格 6

在 GitLab 本身 中， 在 Chrome 和 Firefox 中标题始终左对齐，在 Safari 中居中对齐。

包含多行的单元格