Yusong

Appearance

GitLab 风格的 Markdown ​

文档用途

介绍 GitLab Flavored Markdown 的常用扩展语法.
GitHub Flavored Markdown 扩展语法与 GitLab 基本相同.

适用范围 ​

可以在以下场景使用 GitLab 风格的 Markdown:

  • Issues 的描述与评论
  • 代码仓库内的 .md 文件
  • Merge requests
  • Milestones
  • Wiki pages

文档目录 ​

根据 Markdown 标题自动生成文档目录.
当文档较长时, 建议在文档开头添加目录.

txt
[[_TOC_]]
VSCode 中的编辑技巧

建议使用 Code Snippets, 并对 markdown.json 做如下配置:

json
"gitlab table of contents": {
    "prefix": "toc",
    "description": "gitlab table of contents",
    "body": [
        "[[_TOC_]]",
    ]
},

任务清单 ​

txt
- [x] Completed task
- [~] Inapplicable task
- [ ] Incomplete task
  - [x] Sub-task 1
  - [~] Sub-task 2
  - [ ] Sub-task 3

图片尺寸 ​

除了可以使用通用的 HTML 标签方案 外, 还可以使用 GitLab 专属的语法:

md
<!-- 图片等比缩放, 宽度显示为页面的 75% -->
![alt text](img/markdown_logo.png){width=75%}
<!-- 图片非等比缩放, 宽高都是 100 像素 -->
![alt text](img/markdown_logo.png){width=100 height=100px}

TIP

在 Issue 中插入图片时, 推荐使用此语法.
把本地图片拖拽至输入框, 即可自动上传并生成 Markdown 标准语法的链接.
此时在链接右侧加上例如 {width=30%} 即可方便地调整图片尺寸.

Mermaid ​

文本制图语法 Mermaid.

mermaid
flowchart LR
    A --> B

数学表达式 ​

GitLab 借助 KaTeX 实现了数学表达式的渲染.

md
<!-- 使用 `$` 围绕数学表达式即可在行内显示. -->
This math is inline: $a^2+b^2=c^2$.
<!-- 使用 `$$` 围绕数学表达式, 会换行居中显示 -->
This math is on a separate line: $$a^2+b^2=c^2$$
<!-- 也可以使用 $$ 包围数学表达式块 -->
$$
a^2+b^2=c^2
$$

渲染结果如下:

内部链接 ​

Issue 引用 Wiki 某个页面:

md
<!-- url 结构 -->
[page-name](../../wikis/{page-name})
<!-- 举例 -->
[Wiki 主页](../../wikis/home)

Issue 中引用某个 CI/CD Pipeline:

md
<!-- url 结构 -->
[cicd pipeline](../../pipelines/{number})
<!-- 举例 -->
[cicd pipeline #65](../../pipelines/65)

引用 issue 或 merge request 也有特殊语法.
详见 引用 Issue 以及 引用 Merge Request.

特殊链接 ​

链接类型语法举例
user@{user-name}@yusong
group@{group-name}@all
issue#{issue-id}#123
merge request!{mr-id}!123
label~{label-name}~bug
milestone%{milestone-id}%2
git commit{commit hash}9ba12248

INFO

引用 issue 时, 在末尾加上 + 符号, 即可预览所引用 issue 的标题.
例如 #123+ 可能会显示成 The issue tile (#123).

如果在末尾加上 +s, 会预览更多信息.
例如 #123+s 会显示成 The issue title (#123) • Assignee • v15.10.

多行引述 ​

有些时候我们从别的地方复制了一段文字, 希望让其显示为 "引述" 的格式.
此时使用 >>> 来包裹引述内容, 是个方便的做法.

md
>>>
If you paste a message from somewhere else

that spans multiple lines,

you can quote that without having to manually prepend `>` to every line!
>>>
md
> If you paste a message from somewhere else
>
> that spans multiple lines,
>
> you can quote that without having to manually prepend `>` to every line!

在 GitLab 中的渲染效果:

If you paste a message from somewhere else

that spans multiple lines,

you can quote that without having to manually prepend > to every line!