markdown.md 37.3 KB
Newer Older
Lab机器人's avatar
Lab机器人 已提交
1
# Markdown[](#Markdown "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
2

Lab机器人's avatar
Lab机器人 已提交
3
我们建议您使用 Markdown 来书写相关文档或者需求描述。您可以在以下区域使用 Markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
4

Lab机器人's avatar
Lab机器人 已提交
5
*   评论
Lab机器人's avatar
readme  
Lab机器人 已提交
6
*   Issues
Lab机器人's avatar
Lab机器人 已提交
7 8
*   合并请求
*   里程碑
Lab机器人's avatar
readme  
Lab机器人 已提交
9
*   代码段(代码段必须以`.md`扩展名命名)
Lab机器人's avatar
Lab机器人 已提交
10
*   Wiki
Lab机器人's avatar
readme  
Lab机器人 已提交
11 12 13
*   仓库中的 Markdown 文档
*   Epics

Lab机器人's avatar
Lab机器人 已提交
14 15 16
## GitLab Flavored Markdown (GFM)[](#gitlab-flavored-markdown-gfm "Permalink")

我们使用的是 " GitLab Flavored Markdown"(GFM). 它以几种方式扩展了[CommonMark 规范](https://spec.commonmark.org/current/) (基于标准 Markdown),以添加其他有用的功能。它的灵感来自[GitHub Flavored Markdown](https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax) ,以下为 GFM 的[官方介绍文档](https://docs.gitlab.com/ee/user/markdown.html)
Lab机器人's avatar
readme  
Lab机器人 已提交
17

Lab机器人's avatar
Lab机器人 已提交
18
### 从 Redcarpet 过渡到 CommonMark[](#transition-from-redcarpet-to-commonmark "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
19 20 21 22 23

从 11.1 开始,GitLab 使用[CommonMark Ruby 库](https://github.com/gjtorikian/commonmarker)[Markit](https://github.com/gjtorikian/commonmarker)处理 GitLab 系统中的所有新问题,合并请求,注释和其他 Markdown 内容. 从 11.3 开始,存储库中的 Wiki 页面和 Markdown 文件( `*.md` )也将通过 CommonMark 处理. 从 11.8 开始, [Redcarpet Ruby 库](https://github.com/vmg/redcarpet)已被删除,所有问题和注释,包括 11.1 之前的问题和注释,现在都可以使用[CommonMark Ruby Library 处理](https://github.com/gjtorikian/commonmarker) .

该文档网站的[Markdown 引擎](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/108)已于 2018 年 10 月[从 Redcarpet 迁移到 Kramdown](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/108) .

Lab机器人's avatar
Lab机器人 已提交
24
您的代码仓库中可能存在使用较旧的 Markdown 语法编写的 Issue、合并请求或 Markdown 文档。这些文档使用的是 GitLab 的 RedCarpet 版本,由于 CommonMark 使用了稍微严格的语法,因此自我们过渡到 CommonMark 以来,这些文档现在看起来可能会稍微有所不同。
Lab机器人's avatar
readme  
Lab机器人 已提交
25

Lab机器人's avatar
Lab机器人 已提交
26
这个问题通常很容易修复,例如,带嵌套列表的编号列表可能会错误显示:
Lab机器人's avatar
readme  
Lab机器人 已提交
27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45

```
1. Chocolate
 - dark
 - milk 
```

只需在每个嵌套项目中添加一个空格即可使`-`与顶部列表项的第一个字符对齐(本例中为`C` ):

```
1. Chocolate
 - dark
 - milk 
```

1.  Chocolate
    *   dark
    *   milk

Lab机器人's avatar
Lab机器人 已提交
46
**注意:**我们将在本文档中标记 Redcarpet 和 CommonMark Markdown 之间的全部重大差异。
Lab机器人's avatar
readme  
Lab机器人 已提交
47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68

如果您有大量的 Markdown 文件,确定它们是否正确显示可能很繁琐. 您可以使用[diff_redcarpet_cmark](https://gitlab.com/digitalmoksha/diff_redcarpet_cmark)工具(不是官方支持的产品)来生成文件列表以及 RedCarpet 和 CommonMark 呈现文件的方式之间的差异. 它可以指示是否需要更改任何内容-通常不需要更改.

### GFM extends standard Markdown[](#gfm-extends-standard-markdown "Permalink")

GitLab 充分利用了标准(CommonMark)格式,但还包括对 GitLab 用户有用的附加功能.

它利用了[Markdown](#new-GFM-markdown-extensions)[新功能](#new-GFM-markdown-extensions) ,这些[功能](#new-GFM-markdown-extensions)是标准 Markdown 所没有的:

*   [Color “chips” written in HEX, RGB or HSL](#colors)
*   [Diagrams and flowcharts](#diagrams-and-flowcharts)
*   [Emoji](#emoji)
*   [Front matter](#front-matter)
*   [Inline diffs](#inline-diff)
*   [Math equations and symbols written in LaTeX](#math)
*   [Special GitLab references](#special-gitlab-references)
*   [Task Lists](#task-lists)
*   [Table of Contents](#table-of-contents)
*   [Wiki specific Markdown](#wiki-specific-markdown)

它还具有[扩展的 Markdown 功能](#standard-markdown-and-extensions-in-gitlab) ,而无需更改标准 Markdown 的使用方式:

Lab机器人's avatar
Lab机器人 已提交
69
| 标准 Markdown语法 | GitLab 中扩展的 Markdown 语法|
Lab机器人's avatar
readme  
Lab机器人 已提交
70 71 72 73 74 75 76 77 78 79 80 81 82 83 84
| --- | --- |
| [blockquotes](#blockquotes) | [multi-line blockquotes](#multiline-blockquote) |
| [code blocks](#code-spans-and-blocks) | [colored code and syntax highlighting](#colored-code-and-syntax-highlighting) |
| [emphasis](#emphasis) | [multiple underscores in words](#multiple-underscores-in-words-and-mid-word-emphasis) |
| [headers](#headers) | [linkable Header IDs](#header-ids-and-links) |
| [images](#images) | [embedded videos](#videos) and [audio](#audio) |
| [line breaks](#line-breaks) | [more line break control](#newlines) |
| [links](#links) | [automatically linking URLs](#url-auto-linking) |

## New GFM Markdown extensions[](#new-gfm-markdown-extensions "Permalink")

### Colors[](#colors "Permalink")

> 如果未正确呈现,请[在 GitLab 本身中查看它](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#colors) .

Lab机器人's avatar
Lab机器人 已提交
85
可以使用颜色标识呈现以 HEX,RGB 或 HSL 格式书写的颜色。
Lab机器人's avatar
readme  
Lab机器人 已提交
86 87 88 89 90 91 92

支持的格式(不支持命名的颜色):

*   HEX: ``#RGB[A]`` or ``#RRGGBB[AA]``
*   RGB: ``RGB[A](R, G, B[, A])``
*   HSL: ``HSL[A](H, S, L[, A])``

Lab机器人's avatar
Lab机器人 已提交
93
反引号内的颜色后面将带有色值的"色块":
Lab机器人's avatar
readme  
Lab机器人 已提交
94

Lab机器人's avatar
Lab机器人 已提交
95
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116
- `#F00`
- `#F00A`
- `#FF0000`
- `#FF0000AA`
- `RGB(0,255,0)`
- `RGB(0%,100%,0%)`
- `RGBA(0,255,0,0.3)`
- `HSL(540,70%,50%)`
- `HSLA(540,70%,50%,0.3)` 
```

*   `#F00`
*   `#F00A`
*   `#FF0000`
*   `#FF0000AA`
*   `RGB(0,255,0)`
*   `RGB(0%,100%,0%)`
*   `RGBA(0,255,0,0.3)`
*   `HSL(540,70%,50%)`
*   `HSLA(540,70%,50%,0.3)`

Lab机器人's avatar
Lab机器人 已提交
117
### 框架图和流程图[](#diagrams-and-flowcharts "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
118

Lab机器人's avatar
Lab机器人 已提交
119
可以使用[Mermaid](https://mermaid-js.github.io/mermaid/#/)[PlantUML](https://plantuml.com)从 GitLab 中的文本生成图表和流程图。
Lab机器人's avatar
readme  
Lab机器人 已提交
120 121 122

#### Mermaid[](#mermaid "Permalink")

Lab机器人's avatar
Lab机器人 已提交
123
在 GitLab 10.3 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15107)
Lab机器人's avatar
readme  
Lab机器人 已提交
124

Lab机器人's avatar
Lab机器人 已提交
125
访问[官方页面](https://mermaid-js.github.io/mermaid/#/)以获取更多详细信息. 如果您不熟悉使用 Mermaid,或者需要帮助来确定 Mermaid 代码中的问题,则[Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/)是一个有用的工具,可用于在 Mermaid 中创建和解决问题。
Lab机器人's avatar
readme  
Lab机器人 已提交
126 127 128

为了生成图表或流程图,您应该在`mermaid`块内编写文本:

Lab机器人's avatar
Lab机器人 已提交
129
````markdown
Lab机器人's avatar
Lab机器人 已提交
130
```mermaid
Lab机器人's avatar
Lab机器人 已提交
131
graph TD;
Lab机器人's avatar
readme  
Lab机器人 已提交
132 133 134 135
  A-->B;
  A-->C;
  B-->D;
  C-->D;
Lab机器人's avatar
Lab机器人 已提交
136
```
Lab机器人's avatar
Lab机器人 已提交
137
````
Lab机器人's avatar
readme  
Lab机器人 已提交
138

Miykael_xxm's avatar
Miykael_xxm 已提交
139
```mermaid
Lab机器人's avatar
Lab机器人 已提交
140 141 142 143 144 145
graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;
```
Lab机器人's avatar
readme  
Lab机器人 已提交
146

Lab机器人's avatar
Lab机器人 已提交
147
子图也可以使用:
Lab机器人's avatar
readme  
Lab机器人 已提交
148

Lab机器人's avatar
Lab机器人 已提交
149
````markdown
Lab机器人's avatar
Lab机器人 已提交
150
```mermaid
Lab机器人's avatar
Lab机器人 已提交
151 152 153 154 155 156 157 158 159 160 161 162
graph TB
  SubGraph1 --> SubGraph1Flow
  subgraph "SubGraph 1 Flow"
  SubGraph1Flow(SubNode 1)
  SubGraph1Flow -- Choice1 --> DoChoice1
  SubGraph1Flow -- Choice2 --> DoChoice2
  end
  subgraph "Main Graph"
  Node1[Node 1] --> Node2[Node 2]
  Node2 --> SubGraph1[Jump to SubGraph1]
  SubGraph1 --> FinalThing[Final Thing]
end
Lab机器人's avatar
readme  
Lab机器人 已提交
163
```
Lab机器人's avatar
Lab机器人 已提交
164
````
Lab机器人's avatar
readme  
Lab机器人 已提交
165

Miykael_xxm's avatar
Miykael_xxm 已提交
166
```mermaid
Lab机器人's avatar
Lab机器人 已提交
167
graph TB
Lab机器人's avatar
readme  
Lab机器人 已提交
168 169 170 171 172 173 174 175 176 177 178
  SubGraph1 --> SubGraph1Flow
  subgraph "SubGraph 1 Flow"
  SubGraph1Flow(SubNode 1)
  SubGraph1Flow -- Choice1 --> DoChoice1
  SubGraph1Flow -- Choice2 --> DoChoice2
  end
  subgraph "Main Graph"
  Node1[Node 1] --> Node2[Node 2]
  Node2 --> SubGraph1[Jump to SubGraph1]
  SubGraph1 --> FinalThing[Final Thing]
end
Lab机器人's avatar
Lab机器人 已提交
179
```
Lab机器人's avatar
readme  
Lab机器人 已提交
180 181 182 183
### Emoji[](#emoji "Permalink")

> 如果未正确呈现,请[在 GitLab 本身中查看它](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#emoji) .

Lab机器人's avatar
Lab机器人 已提交
184
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
185 186 187 188 189 190 191
Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you:
:zap: You can use emoji anywhere GFM is supported. :v:
You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People will :heart: you for that.
If you're new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up one of the supported codes.
Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup: 
```

Lab机器人's avatar
Lab机器人 已提交
192
> **注意:**以上表情符号示例在本文档中使用了硬编码图像。 在 GitLab 中呈现时,表情符号可能会出现不同,具体取决于所使用的操作系统和浏览器。
Lab机器人's avatar
readme  
Lab机器人 已提交
193

Lab机器人's avatar
Lab机器人 已提交
194
大多数 emoji 表情在 macOS,Windows,iOS,Android 上都是支持的,并且不支持的情况一下也会将退回到基于图像的表情上。
Lab机器人's avatar
readme  
Lab机器人 已提交
195

Lab机器人's avatar
Lab机器人 已提交
196
**注意:**在 Linux 上,您可以下载[Noto Color Emoji](https://www.google.com/get/noto/help/emoji/)以获得完整的本机表情符号支持,Ubuntu 18.04(与许多现代 Linux 发行版一样)默认情况下已安装此字体。
Lab机器人's avatar
readme  
Lab机器人 已提交
197 198 199 200 201

### Front matter[](#front-matter "Permalink")

在 GitLab 11.6 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23331) .

Lab机器人's avatar
Lab机器人 已提交
202
Front matter 是 Markdown 文档开头,内容之前的元数据。 静态站点生成器(例如[Jekyll](https://jekyllrb.com/docs/front-matter/)[Hugo](https://s0gohugo0io.icopy.site/content-management/front-matter/)和许多其他应用程序)可以使用此数据。
Lab机器人's avatar
readme  
Lab机器人 已提交
203

Lab机器人's avatar
Lab机器人 已提交
204
当您查看由 GitLab 渲染的 Markdown 文件时,任何 Front matter 都会按原样显示在文档顶部的框中,位于渲染的 HTML 内容之前。要查看示例,可以在[GitLab 文档文件](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/README.md)的源版本和渲染版本之间切换。
Lab机器人's avatar
readme  
Lab机器人 已提交
205

Lab机器人's avatar
Lab机器人 已提交
206
在 GitLab 中,仅在 Markdown 文件和 Wiki 页面中支持使用 Front matter ,而在其他支持 Markdown 格式的其他地方使用 Front matter 将无法生效。它必须在文档的最顶部,并且必须在定界符之间,如下所述:
Lab机器人's avatar
readme  
Lab机器人 已提交
207 208 209 210 211

支持以下定界符:

*   YAML( `---` ):

Lab机器人's avatar
Lab机器人 已提交
212
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
213 214 215 216 217
    ---
    title: About Front Matter
    example:
    language: yaml
    --- 
Lab机器人's avatar
Lab机器人 已提交
218
```
Lab机器人's avatar
readme  
Lab机器人 已提交
219 220 221

*   TOML( `+++` ):

Lab机器人's avatar
Lab机器人 已提交
222
    ```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
223 224 225 226 227 228 229 230 231
    +++
    title = "About Front Matter"
    [example]
    language = "toml"
    +++ 
    ```

*   JSON( `;;;` ):

Lab机器人's avatar
Lab机器人 已提交
232 233 234 235 236 237 238 239 240
    ```markdown
    ;;;
        { 
        "title":  "About Front Matter"  
        "example":  {
              "language":  "json"  
        }  
        }
    ;;; 
Lab机器人's avatar
readme  
Lab机器人 已提交
241 242
    ```

Lab机器人's avatar
Lab机器人 已提交
243
通过向任何现有定界符添加说明符来支持其他语言, 例如:
Lab机器人's avatar
readme  
Lab机器人 已提交
244

Lab机器人's avatar
Lab机器人 已提交
245
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
246 247 248 249 250 251 252 253
---php
$title = "About Front Matter";
$example = array(
  'language' => "php",
);
--- 
```

Lab机器人's avatar
Lab机器人 已提交
254
### 行内 diff[](#inline-diff "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
255

Lab机器人's avatar
Lab机器人 已提交
256
> 如果未正确呈现,请[在 GitLab 本身中查看它](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#inline-diff) 。
Lab机器人's avatar
readme  
Lab机器人 已提交
257

Lab机器人's avatar
Lab机器人 已提交
258
使用内联 diff 标签,您可以显示`{+ additions +}``[- deletions -]`
Lab机器人's avatar
readme  
Lab机器人 已提交
259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296

包装标签可以是大括号或方括号:

```
- {+ addition 1 +}
- [+ addition 2 +]
- {- deletion 3 -}
- [- deletion 4 -] 
```

*   {+加法 1 +}
*   [+加法 2 +]
*   {-删除 3-}
*   [-删除 4-]

* * *

但是,包装标签不能混合使用:

```
- {+ addition +]
- [+ addition +}
- {- deletion -]
- [- deletion -} 
```

如果您的差异包含``code``字体的单词,请确保使用反斜杠`\`来转义每个反引号``` ,否则差异突出显示将无法正确呈现:

```
- {+ Just regular text +}
- {+ Text with `backticks` inside +}
- {+ Text with escaped \`backticks\` inside +} 
```

*   {+普通文字+}
*   {+带有`backticks`文字+}
*   {+内含转义的`反引号'的文字+}

Lab机器人's avatar
Lab机器人 已提交
297
### 数学公式[](#math "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
298

Lab机器人's avatar
Lab机器人 已提交
299
> 如果未正确呈现,请[在 GitLab 本身中查看它](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#math) 。
Lab机器人's avatar
readme  
Lab机器人 已提交
300

Lab机器人's avatar
Lab机器人 已提交
301
可以使用[KaTeX](https://github.com/KaTeX/KaTeX)渲染用 LaTeX 语法编写的数学运算。
Lab机器人's avatar
readme  
Lab机器人 已提交
302

Lab机器人's avatar
Lab机器人 已提交
303
在`$`符号之间写的数学将与文本内嵌,用声明为`math`的语言在[代码块中](#code-spans-and-blocks)编写的`math`将在单独的一行显示:
Lab机器人's avatar
readme  
Lab机器人 已提交
304

Lab机器人's avatar
Lab机器人 已提交
305
````markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
306 307
This math is inline $`a^2+b^2=c^2`$.
This is on a separate line
Lab机器人's avatar
Lab机器人 已提交
308 309
​```math a^2+b^2=c^2
```
Lab机器人's avatar
Lab机器人 已提交
310
````
Lab机器人's avatar
readme  
Lab机器人 已提交
311

Lab机器人's avatar
Lab机器人 已提交
312
此数学`a^2+b^2=c^2`为内联$`a^2+b^2=c^2`$。
Lab机器人's avatar
readme  
Lab机器人 已提交
313

Lab机器人's avatar
Lab机器人 已提交
314
这是单独的一行:
Lab机器人's avatar
readme  
Lab机器人 已提交
315

Lab机器人's avatar
Lab机器人 已提交
316
​```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
317 318 319 320 321 322 323 324 325
a^2+b^2=c^2
```

*请注意,KaTeX 仅支持 LaTeX 的[子集](https://katex.org/docs/supported.html) .*

**注意:**这也适用于 Asciidoctor `:stem: latexmath` . 有关详细信息,请参见[Asciidoctor 用户手册](https://asciidoctor.org/docs/user-manual/#activating-stem-support) .

### Special GitLab references[](#special-gitlab-references "Permalink")

Lab机器人's avatar
Lab机器人 已提交
326
GFM 可以识别与 GitLab 相关的特殊参考. 例如,您可以轻松地引用项目中的问题,提交,团队成员甚至整个团队。GFM 会将引用转换为链接,以便您可以轻松地在它们之间导航.
Lab机器人's avatar
readme  
Lab机器人 已提交
327

Lab机器人's avatar
Lab机器人 已提交
328
此外,GFM 可以识别某些跨项目引用,并且还具有一个速记版本,可以引用同一命名空间中的其他项目。
Lab机器人's avatar
readme  
Lab机器人 已提交
329 330 331

GFM 将识别以下内容:

Lab机器人's avatar
Lab机器人 已提交
332
| references | input | 跨项目参考 | 同一命名空间下的快捷方式 |
Lab机器人's avatar
readme  
Lab机器人 已提交
333
| --- | --- | --- | --- |
Lab机器人's avatar
Lab机器人 已提交
334 335
| @用户 | `@user_name` |   |   |
| @组织 | `@group_name` |   |   |
Lab机器人's avatar
readme  
Lab机器人 已提交
336
| 整个团队 | `@all` |   |   |
Lab机器人's avatar
Lab机器人 已提交
337
| 项目 | `namespace/project>` |   |   |
Lab机器人's avatar
readme  
Lab机器人 已提交
338
| issue | `#123` | `namespace/project#123` | `project#123` |
Lab机器人's avatar
Lab机器人 已提交
339 340
| 合并请求 | `!123` | `namespace/project!123` | `project!123` |
| 代码片 | `$123` | `namespace/project$123` | `project$123` |
Lab机器人's avatar
readme  
Lab机器人 已提交
341
| epic | `&123` | `group1/subgroup&123` |   |
Lab机器人's avatar
Lab机器人 已提交
342 343 344
| 项目 id | `~123` | `namespace/project~123` | `project~123` |
| 单个词的标签名称 | `~bug` | `namespace/project~bug` | `project~bug` |
| 多词的标签名称 | `~"feature request"` | `namespace/project~"feature request"` | `project~"feature request"` |
Lab机器人's avatar
readme  
Lab机器人 已提交
345
| 范围标签按名称 | `~"priority::high"` | `namespace/project~"priority::high"` | `project~"priority::high"` |
Lab机器人's avatar
Lab机器人 已提交
346 347 348 349 350 351 352
| 项目里程碑 id | `%123` | `namespace/project%123` | `project%123` |
| 单个词的里程碑 | `%v1.23` | `namespace/project%v1.23` | `project%v1.23` |
| 多词的里程碑 | `%"release candidate"` | `namespace/project%"release candidate"` | `project%"release candidate"` |
| 特定提交 | `9ba12248` | `namespace/project@9ba12248` | `project@9ba12248` |
| 对比指定提交 | `9ba12248...b19a04f5` | `namespace/project@9ba12248...b19a04f5` | `project@9ba12248...b19a04f5` |
| 文件引用 | `[README](doc/README)` |   |   |
| 文件行引用 | `[README](doc/README#L13)` |    |    |
Lab机器人's avatar
readme  
Lab机器人 已提交
353

Lab机器人's avatar
Lab机器人 已提交
354
除此之外,还可以识别和格式化指向某些对象的链接, 这些示例包括:
Lab机器人's avatar
readme  
Lab机器人 已提交
355 356 357 358 359

*   对问题的评论: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234#note_101075757"` ,它将呈现为`#1234 (note1)`
*   问题设计标签: `"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]` .

Lab机器人's avatar
Lab机器人 已提交
360
### 任务列表[](#task-lists "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
361

Lab机器人's avatar
Lab机器人 已提交
362
> 如果未正确呈现,请[在 GitLab 本身中查看它](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#task-lists)。
Lab机器人's avatar
readme  
Lab机器人 已提交
363

Lab机器人's avatar
Lab机器人 已提交
364
您可以在支持 Markdown 的任何位置添加任务列表,如果它们处于 Issue、合并请求或评论中,可以通过"单击"切换状态。但在其他地方,您必须手动编辑 Markdown 以通过在方括号内添加或删除`x`来更改状态。
Lab机器人's avatar
readme  
Lab机器人 已提交
365

Lab机器人's avatar
Lab机器人 已提交
366
要创建任务列表,请添加特殊格式的 Markdown 列表, 您可以使用无序列表或有序列表:
Lab机器人's avatar
readme  
Lab机器人 已提交
367

Lab机器人's avatar
Lab机器人 已提交
368
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
369 370
- [x] Completed task
- [ ] Incomplete task
Lab机器人's avatar
Lab机器人 已提交
371 372 373 374
  - [ ] Sub-task 1
  - [x] Sub-task 2
  - [ ] Sub-task 3
1. [x] Completed task
Lab机器人's avatar
readme  
Lab机器人 已提交
375
1. [ ] Incomplete task
Lab机器人's avatar
Lab机器人 已提交
376 377
   1. [ ] Sub-task 1
   1. [x] Sub-task 2
Lab机器人's avatar
readme  
Lab机器人 已提交
378 379 380 381 382 383 384 385 386 387 388 389
```

*   [x]完成的任务
*   []未完成的任务
    *   []子任务 1
    *   [x]子任务 2
    *   []子任务 3
1.  [x] Completed task
2.  []未完成的任务
    1.  []子任务 1
    2.  [x]子任务 2

Lab机器人's avatar
Lab机器人 已提交
390
### 目录[](#table-of-contents "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
391

Lab机器人's avatar
Lab机器人 已提交
392
通过在标记行上添加`[[_TOC_]]`标记,您可以将目录添加到 Markdown 文件,Wiki 页面或发布/合并请求描述中。 它将显示为链接到各种标题的无序列表。
Lab机器人's avatar
readme  
Lab机器人 已提交
393

Lab机器人's avatar
Lab机器人 已提交
394
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
395 396 397 398 399
This is an intro sentence to my Wiki page.
[[_TOC_]]
## My first heading
First section content.
## My second heading
Lab机器人's avatar
Lab机器人 已提交
400
Second section content.
Lab机器人's avatar
readme  
Lab机器人 已提交
401 402
```

Lab机器人's avatar
Lab机器人 已提交
403
### Wiki 内链 Markdown[](#wiki-specific-markdown "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
404

Lab机器人's avatar
Lab机器人 已提交
405
以下示例显示了如何使用 Wiki 的内部链接:
Lab机器人's avatar
readme  
Lab机器人 已提交
406

Lab机器人's avatar
Lab机器人 已提交
407
#### Wiki - 链接到页面[](#wiki---direct-page-link "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
408

Lab机器人's avatar
Lab机器人 已提交
409
仅包含页面的子弹的链接将指向该页面, *位于 Wiki 的基本级别* 
Lab机器人's avatar
readme  
Lab机器人 已提交
410 411 412

该代码段将链接到 Wiki 根目录下的`documentation`页面:

Lab机器人's avatar
Lab机器人 已提交
413
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
414 415 416
[Link to Documentation](documentation) 
```

Lab机器人's avatar
Lab机器人 已提交
417
#### Wiki - 链接到文件[](#wiki---direct-file-link "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
418

Lab机器人's avatar
Lab机器人 已提交
419
*相对于当前页面* ,带有文件扩展名的链接指向该文件。
Lab机器人's avatar
readme  
Lab机器人 已提交
420 421 422

如果下面的代码段放在`<your_wiki>/documentation/related`的页面上,它将链接到`<your_wiki>/documentation/file.md` :

Lab机器人's avatar
Lab机器人 已提交
423
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
424 425 426 427 428 429 430 431 432
[Link to File](file.md) 
```

#### Wiki - hierarchical link[](#wiki---hierarchical-link "Permalink")

可以使用`./<page>` , `../<page>`来相对于当前 Wiki 页面构建链接.

如果此代码段放在`<your_wiki>/documentation/main`的页面上,它将链接到`<your_wiki>/documentation/related` :

Lab机器人's avatar
Lab机器人 已提交
433
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
434 435 436 437 438
[Link to Related Page](./related) 
```

如果此代码段放在`<your_wiki>/documentation/related/content`的页面上,它将链接到`<your_wiki>/documentation/main` :

Lab机器人's avatar
Lab机器人 已提交
439
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
440 441 442 443 444
[Link to Related Page](../main) 
```

如果此代码段放在`<your_wiki>/documentation/main`的页面上,它将链接到`<your_wiki>/documentation/related.md` :

Lab机器人's avatar
Lab机器人 已提交
445
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
446 447 448 449 450
[Link to Related Page](./related.md) 
```

如果此代码段放在`<your_wiki>/documentation/related/content`的页面上,它将链接到`<your_wiki>/documentation/main.md` :

Lab机器人's avatar
Lab机器人 已提交
451
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
452 453 454 455 456 457 458 459 460
[Link to Related Page](../main.md) 
```

#### Wiki - root link[](#wiki---root-link "Permalink")

以`/`开头的链接是相对于 Wiki 根目录的.

该代码段链接到`<wiki_root>/documentation` :

Lab机器人's avatar
Lab机器人 已提交
461
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
462 463 464 465 466
[Link to Related Page](/documentation) 
```

该代码段链接到`<wiki_root>/miscellaneous.md` :

Lab机器人's avatar
Lab机器人 已提交
467
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
468 469 470 471 472
[Link to Related Page](/miscellaneous.md) 
```

### Embedding metrics in GitLab Flavored Markdown[](#embedding-metrics-in-gitlab-flavored-markdown "Permalink")

Lab机器人's avatar
Lab机器人 已提交
473
公制图表可以嵌入到 GitLab 风味 Markdown 中。 有关更多详细信息,请参见在 GitLab 风格的 Markdown 中嵌入度量标准 。
Lab机器人's avatar
readme  
Lab机器人 已提交
474 475 476

## Standard Markdown and extensions in GitLab[](#standard-markdown-and-extensions-in-gitlab "Permalink")

Lab机器人's avatar
Lab机器人 已提交
477
所有标准 Markdown 格式均应在 GitLab 中按预期工作, 一些标准功能通过附加功能进行了扩展,而不会影响标准用法。 如果扩展了功能,则新选项将作为子节列出:
Lab机器人's avatar
readme  
Lab机器人 已提交
478 479 480 481 482

### Blockquotes[](#blockquotes "Permalink")

块引号是突出显示信息(如边注)的简便方法. 它是通过以`>`开头的 blockquote 行来生成的:

Lab机器人's avatar
Lab机器人 已提交
483
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
484 485 486 487 488 489
> Blockquotes are very handy to emulate reply text.
> This line is part of the same quote.
Quote break.
 > This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. 
```

Lab机器人's avatar
Lab机器人 已提交
490
#### 多个引用块[](#multiline-blockquote "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
491

Lab机器人's avatar
Lab机器人 已提交
492
> 如果未正确呈现,请[在 GitLab 本身中查看它](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#multiline-blockquote) 。
Lab机器人's avatar
readme  
Lab机器人 已提交
493 494 495

GFM 还支持`>>>`围起来的多行块引用,从而扩展了标准的 Markdown 标准:

Lab机器人's avatar
Lab机器人 已提交
496
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
497 498 499 500 501 502 503 504 505 506
>>>
If you paste a message from somewhere else
that spans multiple lines,
you can quote that without having to manually prepend `>` to every line!
>>> 
```


### Code spans and blocks[](#code-spans-and-blocks "Permalink")

Lab机器人's avatar
Lab机器人 已提交
507
您可以轻松突出显示应视为代码而非简单文本的任何内容,简单的内联代码很容易用单个反引号`\``突出显示:
Lab机器人's avatar
readme  
Lab机器人 已提交
508

Lab机器人's avatar
Lab机器人 已提交
509
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
510 511 512 513 514
Inline `code` has `back-ticks around` it. 
```

* * *

Lab机器人's avatar
Lab机器人 已提交
515
同样,整个代码块可以用三个反引号( ````` ),三个波浪号( `~~~` )或缩进 4 个或更多的空格来围起来,以实现较大代码体的相似效果。
Lab机器人's avatar
readme  
Lab机器人 已提交
516

Lab机器人's avatar
Lab机器人 已提交
517
```markdown
Lab机器人's avatar
Lab机器人 已提交
518
```python def function():
Lab机器人's avatar
readme  
Lab机器人 已提交
519 520 521
    #indenting works just fine in the fenced code block
    s = "Python code"
    print s
Lab机器人's avatar
Lab机器人 已提交
522
​``` Using 4 spaces
Lab机器人's avatar
readme  
Lab机器人 已提交
523 524 525 526
    is like using
    3-backtick fences. 
```

Lab机器人's avatar
Lab机器人 已提交
527
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
528 529 530 531 532 533 534
~~~
Tildes are OK too.
~~~ 
```

上面的三个示例呈现为:

Lab机器人's avatar
Lab机器人 已提交
535
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
536 537 538 539 540 541
def function():
    #indenting works just fine in the fenced code block
    s = "Python code"
    print s 
```

Lab机器人's avatar
Lab机器人 已提交
542
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
543 544 545 546 547
Using 4 spaces
is like using
3-backtick fences. 
```

Lab机器人's avatar
Lab机器人 已提交
548
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
549 550 551
Tildes are OK too. 
```

Lab机器人's avatar
Lab机器人 已提交
552
#### 代码块颜色及语法高亮[](#colored-code-and-syntax-highlighting "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
553

Lab机器人's avatar
Lab机器人 已提交
554
> 如果未正确呈现,请[在 GitLab 本身中查看它](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#colored-code-and-syntax-highlighting) 。
Lab机器人's avatar
readme  
Lab机器人 已提交
555 556 557 558 559

GitLab 使用[Rouge Ruby 库](http://rouge.jneen.net/)在代码块中突出显示了更加丰富多彩的语法. 有关支持的语言的列表,请访问[Rouge 项目 Wiki](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers) . 语法突出显示仅在代码块中受支持,因此在内联时无法突出显示代码.

代码块由带有三个反引号( ````` )或三个波浪号( `~~~` )的行围起来,并在第一个围栏的末尾标识了语言:

Lab机器人's avatar
Lab机器人 已提交
560
````markdown
Lab机器人's avatar
Lab机器人 已提交
561
​```javascript var s = "JavaScript syntax highlighting";
Lab机器人's avatar
readme  
Lab机器人 已提交
562 563 564 565 566 567 568 569 570 571 572 573 574 575
alert(s);
```
```python def function():
    #indenting works just fine in the fenced code block
    s = "Python syntax highlighting"
    print s
```
```ruby require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html
```
```  No language indicated, so no syntax highlighting.
s = "There is no highlighting for this."
But let's throw in a <b>tag</b>.
Lab机器人's avatar
Lab机器人 已提交
576
```
Lab机器人's avatar
Lab机器人 已提交
577
````
Lab机器人's avatar
readme  
Lab机器人 已提交
578 579 580

上面的四个示例呈现为:

Miykael_xxm's avatar
Miykael_xxm 已提交
581
​```
Lab机器人's avatar
readme  
Lab机器人 已提交
582 583 584 585
var s = "JavaScript syntax highlighting";
alert(s); 
```

Miykael_xxm's avatar
Miykael_xxm 已提交
586
```
Lab机器人's avatar
readme  
Lab机器人 已提交
587 588 589 590 591 592
def function():
    #indenting works just fine in the fenced code block
    s = "Python syntax highlighting"
    print s 
```

Miykael_xxm's avatar
Miykael_xxm 已提交
593
```
Lab机器人's avatar
readme  
Lab机器人 已提交
594 595 596 597 598
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html 
```

Miykael_xxm's avatar
Miykael_xxm 已提交
599
```
Lab机器人's avatar
readme  
Lab机器人 已提交
600 601 602 603 604
No language indicated, so no syntax highlighting.
s = "There is no highlighting for this."
But let's throw in a <b>tag</b>. 
```

Lab机器人's avatar
Lab机器人 已提交
605
### 强调[](#emphasis "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
606

Lab机器人's avatar
Lab机器人 已提交
607
在 Markdown 中有多种强调文本的方法,包括斜体,粗体,删除线,以及将这些强调样式结合在一起。
Lab机器人's avatar
readme  
Lab机器人 已提交
608

Lab机器人's avatar
Lab机器人 已提交
609
例如:
Lab机器人's avatar
readme  
Lab机器人 已提交
610

Miykael_xxm's avatar
Miykael_xxm 已提交
611
```
Lab机器人's avatar
Lab机器人 已提交
612
Emphasis, aka italics, with *asterisks* or _underscores_
Lab机器人's avatar
readme  
Lab机器人 已提交
613 614 615 616 617
Strong emphasis, aka bold, with double **asterisks** or __underscores__.
Combined emphasis with **asterisks and _underscores_**.
Strikethrough uses two tildes. ~~Scratch this.~~ 
```

Lab机器人's avatar
Lab机器人 已提交
618
**注意:**删除线不是 Markdown 核心标准的一部分,而是 GFM 的一部分。
Lab机器人's avatar
readme  
Lab机器人 已提交
619 620 621

#### Multiple underscores in words and mid-word emphasis[](#multiple-underscores-in-words-and-mid-word-emphasis "Permalink")

Lab机器人's avatar
Lab机器人 已提交
622
> 如果未正确呈现,请[在 GitLab 本身中查看它](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#multiple-underscores-in-words)。
Lab机器人's avatar
readme  
Lab机器人 已提交
623

Lab机器人's avatar
Lab机器人 已提交
624
仅将单词的*一部分*斜体化通常是没有用的,尤其是当您要处理经常带有多个下划线的代码和名称时。 结果,GFM 通过忽略单词中的多个下划线来扩展了标准的 Markdown 标准,以更好地呈现讨论代码的 Markdown 文档:
Lab机器人's avatar
readme  
Lab机器人 已提交
625

Lab机器人's avatar
Lab机器人 已提交
626
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
627 628 629 630 631 632 633 634 635
perform_complicated_task
do_this_and_do_that_and_another_thing
but_emphasis is_desired _here_ 
```

* * *

如果您只想强调单词的一部分,仍然可以使用星号来完成:

Lab机器人's avatar
Lab机器人 已提交
636
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
637 638 639 640
perform*complicated*task
do*this*and*do*that*and*another thing 
```

Lab机器人's avatar
Lab机器人 已提交
641
### 脚注[](#footnotes "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
642

Lab机器人's avatar
Lab机器人 已提交
643
脚注会添加指向注释的链接,该链接将在 Markdown 文件的末尾呈现。
Lab机器人's avatar
readme  
Lab机器人 已提交
644

Lab机器人's avatar
Lab机器人 已提交
645
要创建脚注,您既需要参考标记,又需要带有注释内容的单独行(文件中的任何地方)。
Lab机器人's avatar
readme  
Lab机器人 已提交
646

Lab机器人's avatar
Lab机器人 已提交
647
无论标签名称如何,参考标签的相对顺序都决定了呈现的编号。
Lab机器人's avatar
readme  
Lab机器人 已提交
648 649 650

参考标记可以使用字母和其他字符. 在解决[此错误](https://gitlab.com/gitlab-org/gitlab/-/issues/24423)之前,请避免在脚注标签名称中使用小写`w`或下划线( `_` ).

Miykael_xxm's avatar
Miykael_xxm 已提交
651
```
Lab机器人's avatar
readme  
Lab机器人 已提交
652 653 654 655 656 657
A footnote reference tag looks like this: [^1]
This reference tag is a mix of letters and numbers. [^footnote-42]
[^1]: This is the text inside a footnote.
[^footnote-42]: This is another footnote. 
```

Lab机器人's avatar
Lab机器人 已提交
658
### 标题[](#headers "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
659 660 661 662 663 664 665 666 667

```
# H1
## H2
### H3
#### H4
##### H5
###### H6

Lab机器人's avatar
Lab机器人 已提交
668
此外, 对于 H1 and H2, 还可以通过下划线方式来实现:
Lab机器人's avatar
readme  
Lab机器人 已提交
669 670 671 672 673 674 675

Alt-H1
====== 
Alt-H2
------ 
```

Lab机器人's avatar
Lab机器人 已提交
676
#### 标题 ID 及连接[](#header-ids-and-links "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
677

Lab机器人's avatar
Lab机器人 已提交
678
GFM 扩展了标准 Markdown 标准,以便所有 Markdown 呈现的标头都自动获取 ID,可以将 ID 链接到该 ID(评论中除外)。
Lab机器人's avatar
readme  
Lab机器人 已提交
679

Lab机器人's avatar
Lab机器人 已提交
680
悬停时,将显示到这些 ID 的链接,从而可以更轻松地将链接复制到标头以在其他地方使用。
Lab机器人's avatar
readme  
Lab机器人 已提交
681 682 683

根据以下规则从标头的内容生成 ID:

Lab机器人's avatar
Lab机器人 已提交
684 685 686 687 688
1.  所有文本都将转换为小写
2.  删除所有非单词文本(例如标点符号或 HTML)
3.  所有空格都将转换为连字符
4.  连续的两个或多个连字符转换为1个
5.  如果标题已经存在,则会自动追加一个自增的数字来区别,通常从1开始
Lab机器人's avatar
readme  
Lab机器人 已提交
689

Lab机器人's avatar
Lab机器人 已提交
690
例如:
Lab机器人's avatar
readme  
Lab机器人 已提交
691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709

```
# This header has spaces in it
## This header has a :thumbsup: in it
# This header has Unicode in it: 한글
## This header has spaces in it
### This header has spaces in it
## This header has 3.5 in it (and parentheses) 
```

将生成以下链接 ID:

1.  `this-header-has-spaces-in-it`
2.  `this-header-has-a-in-it`
3.  `this-header-has-unicode-in-it-한글`
4.  `this-header-has-spaces-in-it-1`
5.  `this-header-has-spaces-in-it-2`
6.  `this-header-has-3-5-in-it-and-parentheses`

Lab机器人's avatar
Lab机器人 已提交
710
请注意,表情符号处理是在生成标题 ID 之前进行的,因此表情符号将转换为图像,然后从 ID 中删除。
Lab机器人's avatar
readme  
Lab机器人 已提交
711

Lab机器人's avatar
Lab机器人 已提交
712
### 水平线[](#horizontal-rule "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
713 714 715

使用三个或多个连字符,星号或下划线来创建水平尺非常简单:

Miykael_xxm's avatar
Miykael_xxm 已提交
716
```
Lab机器人's avatar
readme  
Lab机器人 已提交
717 718 719
Three or more hyphens,
 --- 
asterisks,
Lab机器人's avatar
Lab机器人 已提交
720
***
Lab机器人's avatar
readme  
Lab机器人 已提交
721
or underscores
Lab机器人's avatar
Lab机器人 已提交
722
___
Lab机器人's avatar
readme  
Lab机器人 已提交
723 724
```

Lab机器人's avatar
Lab机器人 已提交
725
### 图片[](#images "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
726

Lab机器人's avatar
Lab机器人 已提交
727
例如:
Lab机器人's avatar
readme  
Lab机器人 已提交
728

Miykael_xxm's avatar
Miykael_xxm 已提交
729
```
Lab机器人's avatar
readme  
Lab机器人 已提交
730 731 732 733
Inline-style (hover to see title text):
![alt text](img/markdown_logo.png "Title Text")
Reference-style (hover to see title text):
![alt text1][logo]
Lab机器人's avatar
Lab机器人 已提交
734
[logo]: img/markdown_logo.png "Title Text"
Lab机器人's avatar
readme  
Lab机器人 已提交
735 736
```

Lab机器人's avatar
Lab机器人 已提交
737
#### 视频[](#videos "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
738

Lab机器人's avatar
Lab机器人 已提交
739
> 如果未正确呈现,请[在 GitLab 本身中查看它](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#videos) 。
Lab机器人's avatar
readme  
Lab机器人 已提交
740 741 742

链接到带有视频扩展名的文件的图像标签会自动转换为视频播放器. 有效的视频扩展名是`.mp4` , `.m4v` , `.mov` , `.webm`和`.ogv` :

Lab机器人's avatar
Lab机器人 已提交
743
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
744 745 746 747
Here's a sample video:
![Sample Video](img/markdown_video.mp4) 
```

Lab机器人's avatar
Lab机器人 已提交
748
#### 音频[](#audio "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
749

Lab机器人's avatar
Lab机器人 已提交
750
> 如果未正确呈现,请[在 GitLab 本身中查看它](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#audio) 。
Lab机器人's avatar
readme  
Lab机器人 已提交
751

Lab机器人's avatar
Lab机器人 已提交
752
与视频类似,带有音频扩展名的文件的链接标签会自动转换为音频播放器,有效的音频扩展名是`.mp3` , `.oga` , `.ogg` , `.spx`和`.wav` :
Lab机器人's avatar
readme  
Lab机器人 已提交
753

Lab机器人's avatar
Lab机器人 已提交
754
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
755 756 757 758
Here's a sample audio clip:
![Sample Audio](img/markdown_audio.mp3) 
```

Lab机器人's avatar
Lab机器人 已提交
759
### 行内 HTML[](#inline-html "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
760

Lab机器人's avatar
Lab机器人 已提交
761
> 要在第二个示例中[查看](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#inline-html)在 HTML 中呈现的 Markdown,请[在 GitLab 本身中查看它](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#inline-html) 。
Lab机器人's avatar
readme  
Lab机器人 已提交
762

Lab机器人's avatar
Lab机器人 已提交
763
您还可以在 Markdown 中使用原始 HTML,通常效果都很好。
Lab机器人's avatar
readme  
Lab机器人 已提交
764

Lab机器人's avatar
Lab机器人 已提交
765
有关允许的 HTML 标记和属性的列表,请参见 HTML :: Pipeline 的[SanitizationFilter](https://github.com/jch/html-pipeline/blob/v2.12.3/lib/html/pipeline/sanitization_filter.rb#L42)类的文档. 除了默认`SanitizationFilter`允许列表,GitLab 允许`span` , `abbr` , `details`和`summary`元素。
Lab机器人's avatar
readme  
Lab机器人 已提交
766

Miykael_xxm's avatar
Miykael_xxm 已提交
767
```
Lab机器人's avatar
readme  
Lab机器人 已提交
768 769 770 771 772 773 774 775
<dl>
  <dt>Definition list</dt>
  <dd>Is something people use sometimes.</dd>
  <dt>Markdown in HTML</dt>
  <dd>Does *not* work **very** well. HTML <em>tags</em> will <b>work</b>, in most cases.</dd>
</dl> 
```

Lab机器人's avatar
Lab机器人 已提交
776
仍然可以在 HTML 标记内使用 Markdown,但前提是包含 Markdown 的行分为各自的行:
Lab机器人's avatar
readme  
Lab机器人 已提交
777

Miykael_xxm's avatar
Miykael_xxm 已提交
778
```
Lab机器人's avatar
readme  
Lab机器人 已提交
779 780 781 782 783 784 785 786 787 788 789 790
<dl>
  <dt>Markdown in HTML</dt>
  <dd>Does *not* work **very** well. HTML tags will work, in most cases.</dd>
  <dt>Markdown in HTML</dt>
  <dd>
  Does *not* work **very** well. HTML tags will work, in most cases.
  </dd>
</dl> 
```

#### Details and summary[](#details-and-summary "Permalink")

Lab机器人's avatar
Lab机器人 已提交
791
> 要在第二个示例中[查看](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#details-and-summary)在 HTML 中呈现的 Markdown,请[在 GitLab 本身中查看它](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#details-and-summary) 。
Lab机器人's avatar
readme  
Lab机器人 已提交
792

Lab机器人's avatar
Lab机器人 已提交
793
可以使用 HTML 的[`<details>`](https://s0developer0mozilla0org.icopy.site/en-US/docs/Web/HTML/Element/details)和[`<summary>`](https://s0developer0mozilla0org.icopy.site/en-US/docs/Web/HTML/Element/summary)标记折叠内容. 这对于折叠长日志特别有用,因为它们占用更少的屏幕空间。
Lab机器人's avatar
readme  
Lab机器人 已提交
794

Miykael_xxm's avatar
Miykael_xxm 已提交
795
```
Lab机器人's avatar
readme  
Lab机器人 已提交
796 797 798 799 800 801 802 803 804 805 806
<p>
<details>
<summary>Click this to collapse/fold.</summary>
These details <em>will</em> remain <strong>hidden</strong> until expanded.
<pre><code>PASTE LOGS HERE</code></pre>
</details>
</p> 
```

* * *

Lab机器人's avatar
Lab机器人 已提交
807
这些标记内的 Markdown 也受支持:
Lab机器人's avatar
readme  
Lab机器人 已提交
808 809 810 811 812

**注意:**如果 Markdown 无法正确呈现,请尝试在页面顶部添加`{::options parse_block_html="true" /}` ,然后将`markdown="span"`添加到开头的摘要标记中,如下所示: `<summary markdown="span">` .

请记住,在`</summary>`标记之后和`</details>`标记之前留空行,如示例所示:

Miykael_xxm's avatar
Miykael_xxm 已提交
813
````
Lab机器人's avatar
readme  
Lab机器人 已提交
814 815 816 817 818 819 820
<details>
<summary>Click this to collapse/fold.</summary>
These details _will_ remain **hidden** until expanded.
```
PASTE LOGS HERE
```
</details> 
Lab机器人's avatar
Lab机器人 已提交
821
````
Lab机器人's avatar
readme  
Lab机器人 已提交
822

Lab机器人's avatar
Lab机器人 已提交
823
### 换行[](#line-breaks "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
824 825 826

如果先前的文本以两个换行符结尾,则会插入一个换行符(将开始一个新的段落),例如当您连续两次按`Enter 键`时. 如果仅使用一个换行符( `按`一次`Enter 键` ),则下一个句子将成为同一段落的一部分. 如果要避免长行换行并使它们易于编辑,这很有用:

Miykael_xxm's avatar
Miykael_xxm 已提交
827
```
Lab机器人's avatar
readme  
Lab机器人 已提交
828 829 830 831 832 833 834 835 836 837
Here's a line for us to start with.

This longer line is separated from the one above by two newlines, so it will be a *separate paragraph*.

This line is also a separate paragraph, but...
These lines are only separated by single newlines,
so they *do not break* and just follow the previous lines
in the *same paragraph*. 
```

Lab机器人's avatar
Lab机器人 已提交
838
#### 新行[](#newlines "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
839

Lab机器人's avatar
Lab机器人 已提交
840
GFM 在[处理段落和换行符方面](https://spec.commonmark.org/current/)遵循 Markdown 规范。
Lab机器人's avatar
readme  
Lab机器人 已提交
841

Lab机器人's avatar
Lab机器人 已提交
842
段落是一个或多个连续的文本行,由一个或多个空行分隔(第一段末尾有两个新行), [如上所述](#line-breaks) 。
Lab机器人's avatar
readme  
Lab机器人 已提交
843

Lab机器人's avatar
Lab机器人 已提交
844
如果您需要对换行符或换行符进行更多控制,则可以通过以反斜杠或两个或多个空格结束一行来添加单个换行符,连续两个换行符将创建一个新的段落,中间有一个空行:
Lab机器人's avatar
readme  
Lab机器人 已提交
845

Miykael_xxm's avatar
Miykael_xxm 已提交
846
```
Lab机器人's avatar
readme  
Lab机器人 已提交
847 848 849 850 851 852 853 854 855 856
First paragraph.
Another line in the same paragraph.
A third line in the same paragraph, but this time ending with two spaces.{space}{space}
A new line directly under the first paragraph.

Second paragraph.
Another line, this time ending with a backslash.\
A new line due to the previous backslash. 
```

Lab机器人's avatar
Lab机器人 已提交
857
### 链接[](#links "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
858 859 860

有两种创建链接的方法,即内联样式和引用样式:

Miykael_xxm's avatar
Miykael_xxm 已提交
861
```
Lab机器人's avatar
readme  
Lab机器人 已提交
862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881
- This is an [inline-style link](https://www.google.com)
- This is a [link to a repository file in the same directory](index.md)
- This is a [relative link to a readme one directory higher](../README.md)
- This is a [link that also has title text](https://www.google.com "This link takes you to Google!")

Using header ID anchors:

- This links to [a section on a different Markdown page, using a "#" and the header ID](index.md#overview)
- This links to [a different section on the same page, using a "#" and the header ID](#header-ids-and-links)

Using references:

- This is a [reference-style link, see below][Arbitrary case-insensitive reference text]
- You can [use numbers for reference-style link definitions, see below][1]
- Or leave it empty and use the [link text itself][], see below.

Some text to show that the reference links can follow later.

[arbitrary case-insensitive reference text]: https://www.mozilla.org/en-US/
[1]: https://slashdot.org
Lab机器人's avatar
Lab机器人 已提交
882
[link text itself]: https://www.reddit.com
Lab机器人's avatar
readme  
Lab机器人 已提交
883 884
```

Lab机器人's avatar
Lab机器人 已提交
885
**注意:**相对链接不允许引用 Wiki 页面或项目文件中的 Wiki 页面中的项目文件, 这样做的原因是,Wiki 始终位于 GitLab 中的单独 Git 存储库中。例如,仅当链接位于 Wiki Markdown 文件内部时, `[I'm a reference-style link](style)`才会将链接指向`wikis/style` 。
Lab机器人's avatar
readme  
Lab机器人 已提交
886

Lab机器人's avatar
Lab机器人 已提交
887
#### URL 自动添加链接 [](#url-auto-linking "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
888

Lab机器人's avatar
Lab机器人 已提交
889
GFM 将自动为您添加到文档中的 URL 设置链接:
Lab机器人's avatar
readme  
Lab机器人 已提交
890

Miykael_xxm's avatar
Miykael_xxm 已提交
891
```
Lab机器人's avatar
readme  
Lab机器人 已提交
892 893 894 895 896 897 898 899 900 901 902 903 904 905 906
- 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)
*   [https://www.google.com](https://www.google.com)
*   [ftp://ftp.us.debian.org/debian/](ftp://ftp.us.debian.org/debian/)
*   <smb://foo/bar/baz>
*   <irc://irc.freenode.net/>
*   [http://localhost:3000](http://localhost:3000)

Lab机器人's avatar
Lab机器人 已提交
907
### 有序/无序列表列表[](#lists "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
908

Lab机器人's avatar
Lab机器人 已提交
909
可以轻松创建有序列表和无序列表。
Lab机器人's avatar
readme  
Lab机器人 已提交
910

Lab机器人's avatar
Lab机器人 已提交
911
对于有序列表,请在有序列表的每一行的开头添加希望列表以其开头的数字,例如`1.` ,后跟一个空格. 在第一个数字之后,使用什么数字都没有关系,有序列表将按垂直顺序自动编号,因此对同一列表中的所有项目重复`1.` .. 如果你开始以外的其他数字`1.` ,它会用它作为第一个数字,并从那里计数。
Lab机器人's avatar
readme  
Lab机器人 已提交
912

Lab机器人's avatar
Lab机器人 已提交
913
例如:
Lab机器人's avatar
readme  
Lab机器人 已提交
914

Miykael_xxm's avatar
Miykael_xxm 已提交
915
```
Lab机器人's avatar
readme  
Lab机器人 已提交
916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932
1. First ordered list item
2. Another item
 - Unordered sub-list.
1. Actual numbers don't matter, just that it's a number
 1. Ordered sub-list
 1. Next ordered sub-list item
4. And another item. 
```

1.  首先订购的清单项目
2.  另一个项目
    *   无序子列表.
3.  实际数字并不重要,只是一个数字
    1.  订购子清单
    2.  下一个订购的子清单项目
4.  还有另一个项目.

Lab机器人's avatar
Lab机器人 已提交
933
对于无序列表,请在无序列表的每一行的开头添加`-` , `*`或`+` ,然后加上一个空格,但是您不能混合使用它们。
Lab机器人's avatar
readme  
Lab机器人 已提交
934

Miykael_xxm's avatar
Miykael_xxm 已提交
935
```
Lab机器人's avatar
readme  
Lab机器人 已提交
936
Unordered lists can:
Lab机器人's avatar
Lab机器人 已提交
937
- use
Lab机器人's avatar
readme  
Lab机器人 已提交
938 939 940
- minuses

They can also:
Lab机器人's avatar
Lab机器人 已提交
941
* use
Lab机器人's avatar
readme  
Lab机器人 已提交
942 943 944
* asterisks

They can even:
Lab机器人's avatar
Lab机器人 已提交
945
+ use
Lab机器人's avatar
readme  
Lab机器人 已提交
946 947 948 949 950
+ pluses 
```

* * *

Lab机器人's avatar
Lab机器人 已提交
951
如果列表项包含多个段落,则每个后续段落都应缩进到与列表项文本开头相同的级别。
Lab机器人's avatar
readme  
Lab机器人 已提交
952

Lab机器人's avatar
Lab机器人 已提交
953
例如:
Lab机器人's avatar
readme  
Lab机器人 已提交
954

Miykael_xxm's avatar
Miykael_xxm 已提交
955
```
Lab机器人's avatar
readme  
Lab机器人 已提交
956 957 958
1. First ordered list item

   Second paragraph of first item.
Lab机器人's avatar
Lab机器人 已提交
959
1. Another item 
Lab机器人's avatar
readme  
Lab机器人 已提交
960 961 962 963
```

* * *

Lab机器人's avatar
Lab机器人 已提交
964
如果第一项的段落没有缩进适当的空格数,则该段落将出现在列表外部,而不是在列表项下方正确缩进。
Lab机器人's avatar
readme  
Lab机器人 已提交
965

Lab机器人's avatar
Lab机器人 已提交
966
例如:
Lab机器人's avatar
readme  
Lab机器人 已提交
967 968 969 970 971 972 973 974 975

```
1. First ordered list item

  Paragraph of first item.
 1. Another item 
```


Lab机器人's avatar
Lab机器人 已提交
976
### 上标/下标[](#superscripts--subscripts "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
977 978 979

当前,CommonMark 和 GFM 不支持 Redcarpet 支持的上标语法( `x^2` ). 您可以对上标和下标使用标准的 HTML 语法:

Lab机器人's avatar
Lab机器人 已提交
980
```markdown
Lab机器人's avatar
readme  
Lab机器人 已提交
981 982 983 984
The formula for water is H<sub>2</sub>O
while the equation for the theory of relativity is E = mc<sup>2</sup>. 
```

Lab机器人's avatar
Lab机器人 已提交
985
### 表格[](#tables "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
986

Lab机器人's avatar
Lab机器人 已提交
987
表格不是 Markdown 核心规范的一部分,但它们是 GFM 的一部分。
Lab机器人's avatar
readme  
Lab机器人 已提交
988

Lab机器人's avatar
Lab机器人 已提交
989 990 991 992 993 994
1.  第一行包含表头,并用"竖线"( `|` )分隔
2.  第二行将标题与单元格分开,并且必须包含三个或更多破折号
3.  第三行以及随后的任何行均包含单元格值
    *   您**不能**在 Markdown 中将单元格分隔成多行,它们必须保持为单行,但它们可能会很长。如果需要,还可以包含 HTML `<br>`标记以强制换行
    *   像元大小**不必**彼此匹配,它们很灵活,但必须用管道( `|` )分隔
    *   您**可以**有空白单元格
Lab机器人's avatar
readme  
Lab机器人 已提交
995

Lab机器人's avatar
Lab机器人 已提交
996
例如:
Lab机器人's avatar
readme  
Lab机器人 已提交
997

Miykael_xxm's avatar
Miykael_xxm 已提交
998
```
Lab机器人's avatar
readme  
Lab机器人 已提交
999 1000 1001 1002
| header 1 | header 2 | header 3 |
| ---      |  ------  |---------:|
| cell 1   | cell 2   | cell 3   |
| cell 4 | cell 5 is longer | cell 6 is much longer than the others, but that's ok. It will eventually wrap the text when the cell is too large for the display size. |
Lab机器人's avatar
Lab机器人 已提交
1003
| cell 7   |          | cell <br> 9 |
Lab机器人's avatar
readme  
Lab机器人 已提交
1004 1005
```

Lab机器人's avatar
Lab机器人 已提交
1006
(另外,你可以通过添加冒号选择文本列中的对齐`:`第二行中的"破折号"线条的两侧), 这将影响列中的每个单元格。
Lab机器人's avatar
readme  
Lab机器人 已提交
1007

Lab机器人's avatar
Lab机器人 已提交
1008
**注意:** [在 GitLab 本身中](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#tables) ,标题始终在 Chrome 和 Firefox 中左对齐,并在 Safari 中居中。
Lab机器人's avatar
readme  
Lab机器人 已提交
1009

Miykael_xxm's avatar
Miykael_xxm 已提交
1010
```
Lab机器人's avatar
readme  
Lab机器人 已提交
1011 1012 1013
| Left Aligned | Centered | Right Aligned | Left Aligned | Centered | Right Aligned |
| :---         | :---:    | ---:          | :----------- | :------: | ------------: |
| Cell 1       | Cell 2   | Cell 3        | Cell 4       | Cell 5   | Cell 6        |
Lab机器人's avatar
Lab机器人 已提交
1014
| Cell 7       | Cell 8   | Cell 9        | Cell 10      | Cell 11  | Cell 12       |
Lab机器人's avatar
readme  
Lab机器人 已提交
1015 1016
```

Lab机器人's avatar
Lab机器人 已提交
1017
#### 从电子表格中复制并粘贴到 Markdown[](#copy-from-spreadsheet-and-paste-in-markdown "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
1018

Lab机器人's avatar
Lab机器人 已提交
1019
如果您使用电子表格软件(例如 Microsoft Excel,Google 表格或 Apple Numbers),则可以从电子表格中进行复制,GitLab 会将其粘贴为 Markdown 表格。例如,假设您具有以下电子表格:
Lab机器人's avatar
readme  
Lab机器人 已提交
1020

Lab机器人's avatar
Lab机器人 已提交
1021
[![Copy from spreadsheet](/docs/img/markdown_copy_from_spreadsheet_v12_7.png)](/docs/img/markdown_copy_from_spreadsheet_v12_7.png)
Lab机器人's avatar
readme  
Lab机器人 已提交
1022

Lab机器人's avatar
Lab机器人 已提交
1023
选择单元格并将其复制到剪贴板,打开一个 Markdown 并粘贴电子表格:
Lab机器人's avatar
readme  
Lab机器人 已提交
1024

Lab机器人's avatar
Lab机器人 已提交
1025
[![Paste to Markdown table](/docs/img/markdown_paste_table_v12_7.png)](/docs/img/markdown_paste_table_v12_7.png)
Lab机器人's avatar
readme  
Lab机器人 已提交
1026

Lab机器人's avatar
Lab机器人 已提交
1027
## 引用[](#references "Permalink")
Lab机器人's avatar
readme  
Lab机器人 已提交
1028

Lab机器人's avatar
Lab机器人 已提交
1029 1030 1031 1032
*   该文档从[Markdown-Cheatsheet 中](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)大量引用
*   Daring Fireball 上的原始[Markdown 语法指南](https://daringfireball.net/projects/markdown/syntax)是详细解释标准 Markdown 的绝佳资源
*   有关 CommonMark 的详细规范,请参见[CommonMark 规范](https://spec.commonmark.org/current/)
*   [CommonMark Dingus](http://try.commonmark.org)是用于测试 CommonMark 语法的便捷工具