Markdown 指南

维护者:

Markdown 风格指南
标题
段落、换行和水平线
- Wrapping Text
  - 常规段落和自动连接
- 额外的换行
- 水平线（分隔线）
强调：粗体和斜体
链接
- 内联链接
- 相对链接
- 邮件链接
- 标识符
列表
- 有序列表
- 无序列表
- 拆分列表
图片
图表
- Mermaid
- PlantUML
视频
- BiliBili
- YouTube
- 本地视频 (HTML5)
- 其他视频
- 展示多个视频
目录 (ToC)
表格
折叠
代码块
- In-line
- Fenced
- 缩进
- 嵌套
- 在列表中
块引用
笔记
评论
锚点
Font Awesome
- Puzzle Icon
- Purple GitLab Tanuki
- Orange GitLab Tanuki
Classes, IDs, and attributes
- 特殊 classes
  - 阴影
  - 笔记
  - 颜色
  - 文字对齐
混合使用 HTML + Markdown
Colorful sections
- 附加信息
- Warnings
- Danger
- Do's and Don'ts
- 自定义警报面板和警报框
- GitLab Webcast 警报框
样式
嵌入文档
- Google 产品
- 分享幻灯片
嵌入 GitLab 代码片段
Markdown 编辑器
补充说明
更多

Markdown 风格指南

本网站由 Middleman 生成，这是一个被 Web 开发人员广泛使用的博客和静态站点生成器 ( SSG )。 Markdown 语言是所有 SSG 结构的一部分。Markdown 是一种轻量级的标记语言，可用于在纯文本文档中添加格式化元素，旨在可以在任何文本编辑器中轻松编写。

对于 GitLab.cn，我们使用 kramdown，这是一个高级 Markdown 引擎，具有许多其他引擎所没有的有趣功能，例如内联属性列表(IAL)，它可以实现超越标准 Markdown 的简单样式选项。

如果您从未使用过 Markdown，请不要担心，它很容易学习，甚至更易于使用。一旦您习惯了它，就会惊讶于它是多么的方便。并且当你使用的技术不支持 markdown 时，你会怀念它的。

GitLab 中大多数文本区域中都支持 Markdown 语法，但并不是所有的文本区都支持 kramdown。对于 GitLab.com、Jihulab.com、GitLab CE、GitLab EE、GitLab JH 的文本区域，目前的 Markdown 引擎是 CommonMarker。在这里你可以找到它们的 markdown 风格指南。

本指南旨在让每个人都可以更轻松地使用 kramdown 功能并节省大量时间为 GitLab.cn 编写内容，包括 Handbook 页面、网站页面、博客文章以及 handbook 项目中的所有其他内容。

标题

## Heading h2

### Heading h3

#### Heading h4

Output

Heading h2

Heading h3

Heading h4

注意:

我们不使用 h1 标题，因为它们已经作为页面标题显示在每个页面开头位置，而且每个页面不应出现一个以上的 h1。

当你使用一个顶级标题，或 <h1> 时，你在该标题和页面上的其余内容之间建立了语义关系，描述了它是关于什么的。如果你在同一个页面上使用第二个 <h1>，就会造成一些潜在的混乱，因为有人或搜索引擎可能会把这看作是第一个 <h1> 之后的内容与这个新的 <h1> 的开始之间的语义关系的结束。 SEO Guide
从 h2(##) 开始内容的编写，并遵循 h2 → h3 → h4的顺序，请勿跳过标题元素，如 h2 → h4。

六个标题元素，H1 到 H6，表示章节标题。尽管标题的顺序和出现不受 HTML DTD 的限制，但文档不应跳级（例如，从 H1 到 H3），因为将这类文档转换为其他表现形式时往往会有问题。 W3C -# 始终与其旁边的文本之间保留一个空格，否则将无法正确展示。
为了保持文本清晰和 Markdown 一致，请在任何标题及其后续段落之间跳一行。

段落、换行和水平线

只需编写文本行即可获得常规段落。如果您在两行之间按回车键，则这两行将合并为一个段落，称为 wrapping text]。但如果在它们之间留一个空行，它们将被分成两段。

在某些 Git 工具中，在 MR 时通过额外的换行符使得 diffs 内容更容易理解，但是 GitLab 的 Web 界面以及许多桌面 Git 工具具有在行内突出显示子字符串更改以及并排或类似版本比较的功能，因此没有必要用于人工换行。

Wrapping Text

拆分长行（最好最多 100 个字符）可以更轻松地提供对小块文本的反馈。不要在段落中断行的最后一个单词后留下空格，除非您希望使用 <br> 来进行换行。

常规段落和自动连接

This text is a paragraph.
This won't be another paragraph, it will join the line above it.

This will be another paragraph, as it has a blank line above it.

Output

This text is a paragraph. This won't be another paragraph, it will join the line above it.

This will be another paragraph, as it has a blank line above it.

额外的换行

如果您需要额外的换行（或行之间的一些额外空间），您可以简单地使用 HTML 换行标签 <br>，这样会在其上方和下方留空行：

Text A
<!-- blank line -->
<br>
<!-- blank line -->
Text B

Output

Text A

Text B

水平线（分隔线）

3 个或更多破折号的序列将产生一条水平线，我们使用 4 作为标准，达到这个数量就会生成水平线，在它前后会留出空行：

Text
<!-- blank line -->
----
<!-- blank line -->
Text

Output

Text

强调：粗体和斜体

要显示粗体或斜体文本：

粗体：用 2 个星号 ** 或下划线 __ 括起来
斜体：用 1 个星号 * 或下划线 _ 括起来
粗体且斜体：使用 3 个星号 *** 或下划线 ___ 括起来

This is **bold** and this is _italic_.

This is ***bold and italic***.

Output

This is bold and this is italic.

This is bold and italic.

Markdown 本身不支持带下划线的文本。如有必要，您可以使用 HTML 标签 ins( <ins>underlined text</ins>) 对其进行硬编码，但不建议这样做。

链接

有很多不同的方式可以用来显示带有 Markdown 标记的链接，但为了保持一些标准，让我们尝试仅使用以下选项。

重要说明：

不要把它当作限制性规则，但要避免使用无意义的文本作为链接
检查死链：http://www.deadlinkchecker.com/

内联链接

我们推荐使用内联链接，例如 [Text to display](link)，因为它们更易于维护。要在新标签页中打开内联链接，您可以在末尾添加 {:target="_blank"},，例如：[Text to display](link){:target="_blank"}

相对链接

引用 gitlab.cn 上的链接时使用相对链接。例如，指向我们博客 handbook 的链接应该是这样的：/handbook/marketing/blog/ 而不是这样的https://gitlab.cn/handbook/marketing/blog/。

但对于指向 JihuLab.com 或其他站外链接，必须使用完整链接，包括http:。

邮件链接

如果您要向页面添加电子邮件地址，请务必使用 mailto 以避免创建无效的链接。例如：example@gitlab.com

[example@gitlab.com](mailto:example@gitlab.com)

标识符

当单个页面上有重复的链接时，您可以选择使用标识符。

请将标识符放在段落（或部分）的末尾，按首字母顺序排列。

[Text to display][identifier] will display a link.

[Another text][another-identifier] will do the same. Hover the mouse over it to see the title.

[This link] will do the same as well. It works as the identifier itself.

[This link][] (same as above), has a second pair of empty brackets to indicate that the following parenthesis does not contain a link.

<https://example.com> works too. Must be used for explicit links.

<!-- Identifiers, in alphabetical order -->

[another-identifier]: https://example.com "This example has a title"
[identifier]: http://example1.com
[this link]: http://example2.com

Output

Text to display will display a link.

Another text will do the same. Hover the mouse over it to see the title.

This link will do the same as well. It works as the identifier itself.

This link (same as above), has a second pair of empty brackets to indicate that the following parenthesis does not contain a link.

https://example.com works too. Must be used for explicit links.

注意:

标识符不区分大小写。它们可以是单个单词或短语，如 [link] 和 [multiple words too]。

列表

有序和无序列表的生成都都非常容易，有很多方法可以达到相同的效果，但是为了标准的统一，我们使用以下方法。

始终使用 3 个空格来缩进嵌套列表（以创建子项）。

小技巧：不要在项目之间留空行，除非你有理由这样做。

重要提示：始终在段落或标题与后续列表之间保留空行！否则列表将无法展示。

有序列表

创建有序列表非常容易：

Paragraph:

1. Item one
   1. Sub item one
   2. Sub item two
   3. Sub item three
2. Item two

Output

Paragraph:

Item one
1. Sub item one
2. Sub item two
3. Sub item three
Item two

还有一个小技巧实用且可以避免数字错误，就是对所有项目使用 “1”。Markdown 引擎会按照正确的顺序输出它们。

Paragraph:

1. Item one
   1. Sub item one
   1. Sub item two
1. Item two
1. Item three

Output

Paragraph:

Item one
1. Sub item one
2. Sub item two
Item two
Item three

无序列表

无序列表也很容易创建：

Paragraph:

- Item 1
- Item 2
- Item 3
   - Sub item 1
   - Sub item 2
- Item 4

Output

Paragraph:

Item 1
Item 2
Item 3
- Sub item 1
- Sub item 2
Item 4

拆分列表

假设出于某种原因，您想将列表拆分为不同的部分。可以使用 ^ 符号来指示列表的结尾和下一个列表的开头：

- list one - item 1
- list one - item 2
   - sub item 1
   - sub item 2
- list one - item 3
^
- list two - item A
- list two - item B
^
- list three - item _i_
- list three - item _ii_

Output

list one - item 1
list one - item 2
- sub item 1
- sub item 2
list one - item 3

list two - item A
list two - item B

list three - item i
list three - item ii

图片

要将图像插入到 Markdown 文件中，请使用 ![ALT](/path/image.ext). 该路径可以是网站的相对路径，也可以是外部图像的完整 URL。支持的格式为 .png、.jpg、.gif，也支持部分 .svg 文件，具体取决于其结构。

![Semantic description of image](/images/path/to/folder/image.png "Image Title")

还可以使用标识符，就像链接那样 [links](#links)：

![Semantic description of image][identifier]

通过以下方式，为图片添加标题：

![Semantic description of image](/images/path/to/folder/image.png)*My caption*

对于可点击的图像，只需将图像标记包装成链接即可：

[![Semantic description of image](/images/path/to/folder/image.png "Hello World")*My caption*][gitlab.cn]

Output

My caption

重要提示

为您的图片设置阴影！
所有图像必须放在 /source/images/ 下的适当目录中，只允许截图和公共领域的图像，请勿使用有版权的图片。
方括号内的文本是图像属性 ALT，它代表_替代文本_。包含描述性的替代文本有助于增强每个访问者的可访问性，并且应始终包含在图像中。添加替代文字时，请务必描述图像的内容和功能。除了可访问性的好处之外，ALT 对 SEO 也很有用，并且在由于某种原因浏览器未加载该图像时显示。
同样的，图像必须使用与其相关的名称。示例：如果它是一张橘猫的照片，请将其命名为 orange-cat.jpg 而不是 image-01.jpg。
还建议为图片添加标题，如上面示例中的 “Hello World”。

图表

通过 Markdown 插入图表有两种方法：

Mermaid
PlantUML

Mermaid

请参阅 GitLab 文档中有关如何使用 Mermaid 的示例。

PlantUML

您可以在 Markdown 块中使用 PlantUML。例如：

```plantuml
!define ICONURL https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/v2.1.0
skinparam defaultTextAlignment center
!include ICONURL/common.puml
!include ICONURL/font-awesome-5/gitlab.puml
!include ICONURL/font-awesome-5/java.puml
!include ICONURL/font-awesome-5/rocket.puml
!include ICONURL/font-awesome/newspaper_o.puml
FA_NEWSPAPER_O(news,good news!,node) #White {
FA5_GITLAB(gitlab,GitLab.com,node) #White
FA5_JAVA(java,PlantUML,node) #White
FA5_ROCKET(rocket,Integrated,node) #White
}
gitlab ..> java
java ..> rocket
```

Output

视频

有两种显示视频的方式：在 HTML5 <video> 标签内和在 <iframe> 标签内。

BiliBili

打开视频页面
鼠标移动到分享按钮
复制 “嵌入代码”
提取复制代码 <iframe> 中 src 的 URL，并在其前面加上 https:（注意没有//），将组合的内容替换下面的 src 内容：

<!-- blank line -->
<figure class="video_container">
  <iframe src="https://player.bilibili.com/player.html?aid=973234051&bvid=BV1844y1r76m&cid=341483466&page=1" frameborder="0" allowfullscreen="true"> </iframe>
</figure>
<!-- blank line -->

Output

YouTube

这种方法适用于 YouTube 和其他 <iframe> 标签内的嵌入视频。

复制下面的代码并将其粘贴到您的 Markdown 文件中。在其上方和下方留一个空行。不要编辑代码块（例如，删除空格 - 则视频 iframe 可能无法正确展示）
打开要展示的视频 URL
点击“分享”，然后点击“嵌入”
只复制 <iframe> 中 src 的 URL，并将其替换下面的 src 内容：

<!-- blank line -->
<figure class="video_container">
  <iframe src="https://www.youtube.com/embed/enMumwvLAug" frameborder="0" allowfullscreen="true"> </iframe>
</figure>
<!-- blank line -->

Output

本地视频 (HTML5)

此方法适用于上传到可从公网通过 URL 或相对路径检索到的某个位置的任何视频文件 path/to/video.mp4。

阅读 w3schools HTML5 video guide, 或 MDN <video> guide
以这三种格式录制或导出的视频：.mp4、.ogg 和 .webm
获取视频的 URL
选择要用作展示海报的图片
复制下面的代码并将其粘贴到您的文件中
使用视频 URL 替换 src URL

<!-- blank line -->
<figure class="video_container">
  <video controls="true" allowfullscreen="true" poster="path/to/poster_image.png">
    <source src="path/to/video.mp4" type="video/mp4">
    <source src="path/to/video.ogg" type="video/ogg">
    <source src="path/to/video.webm" type="video/webm">
  </video>
</figure>
<!-- blank line -->

Output

注意：如果您没有 w3schools 推荐的视频格式，您可以选择一种其他的，但很可能并非所有设备和浏览器都支持您的视频。上面的视频（仅 .mp4）适用于适用于 macOS、Android 和 Windows 的 Mozilla Firefox，以及适用于 Android 和 Windows 的 Chrome。但它可能不适用于其他设备/浏览器，例如适用于 macOS 和 iOS 的 Chrome 或 Safari。事实上，最好的选择是使用 YouTube 或 Vimeo 在 <iframe> 标签中嵌入视频。

其他视频

对于任何其他视频，例如来自 Vimeo 或 Google Drive 的视频，仅抓取视频 iframe，然后像我们对 YouTube 视频所做的那样，将其包裹在 <iframe> 中以 <figure class="video_container"> 提高响应速度。复制并粘贴以下代码，仅将 iframe URL替换为您自己的 URL：

<!-- blank line -->
<figure class="video_container">
  <iframe src="https://drive.google.com/file/d/0B6m34D8cFdpMZndKTlBRU0tmczg/preview" frameborder="0" allowfullscreen="true"> </iframe>
</figure>
<!-- blank line -->

Output

展示多个视频

要在同一页面上显示多个视频，只需 figure 在您希望它们显示的位置重复代码块，将视频 ID 替换为与您的视频对应的相应 ID。

要在一个序列中显示多个视频，只需复制 figure 代码块并根据需要多次粘贴。在块之间留空行，请不要删除空格，否则您的视频可能无法正常渲染。

<!-- blank line -->
<figure class="video_container">
  <iframe src="https://drive.google.com/file/d/0B6m34D8cFdpMZndKTlBRU0tmczg/preview" frameborder="0" allowfullscreen="true"> </iframe>
</figure>

<figure class="video_container">
  <iframe src="https://drive.google.com/file/d/0B6m34D8cFdpMZndKTlBRU0tmczg/preview" frameborder="0" allowfullscreen="true"> </iframe>
</figure>

<figure class="video_container">
  <iframe src="https://drive.google.com/file/d/0B6m34D8cFdpMZndKTlBRU0tmczg/preview" frameborder="0" allowfullscreen="true"> </iframe>
</figure>
<!-- blank line -->

目录 (ToC)

使用 kramdown 创建目录非常简单！ToC 将自动包含文档中的每个标题，除非您不希望包含它。您无需为每个标题单独添加锚点，这是完全是自动的。

----

## On this page
{:.no_toc}

- TOC
{:toc}

----

与往常一样，请在标记前后各留一个空行。但由四个破折号开始和结束不是必需的，但建议在整个 GitLab.cn 中保持相同的标准。

当不想在 ToC 中包含标题可以使用 {:.no_toc}。只需在标题下方添加它，它就不会包含在 ToC 中。实际上 no_toc 是一个自定义类，如本指南后面所述。

在本页面的最开始，可以找到输出的 ToC。

同时也可以使用有序 ToC，在列表的开头显示数字。只需使用有序列表的标记，kramdown 就会展示您想要的内容：

1. TOC
{:toc}

表格

表格对于 Markdown 极具挑战性。因此，我们有两种可能的方法：尽可能使用 Markdown，但如果您需要非常高级的表格布局，您可以自由地将它们添加到 HTML 标签中。

Markdown is not a replacement for HTML, or even close to it. (John Gruber)

正如 Markdown 的创建者 John Gruber 所解释的那样，它不是为了取代 HTML 而创建的，因此有些情况我们无法避免使用 HTML。对于复杂的表格，就是这种情况。

下表有一个标题（第一行），然后是定义所需对齐方式的标记（破折号和冒号），然后是表格主体。您可以继续添加分隔符以创建后续表格主体。

无论您如何准备表格，其设计都将取决于为它们定义的 CSS 样式。

如果您想将自定义类和/或自定义 ID 归因于元素，{: .custom-class #custom-id} 则可以使用最后一个标记。<table>

最后一个标记 {: .custom-class #custom-id} 可以用于将一个自定义类和/或自定义ID 指向 <table> 元素的情况。

| Default aligned | Left aligned | Center aligned  | Right aligned  |
|-----------------|:-------------|:---------------:|---------------:|
| First body part | Second cell  | Third cell      | fourth cell    |
| Second line     | foo          | **strong**      | baz            |
| Third line      | quux         | baz             | bar            |
|-----------------+--------------+-----------------+----------------|
| Second body     |              |                 |                |
| 2nd line        |              |                 |                |
|-----------------+--------------+-----------------+----------------|
| Third body      |              |                 | Foo            |
{: .custom-class #custom-id}

Output

Default aligned	Left aligned	Center aligned	Right aligned
First body part	Second cell	Third cell	fourth cell
Second line	foo	strong	baz
Third line	quux	baz	bar
Second body
2nd line		Hello World
Third body			Foo

前面的示例中对称使用了

、空格和破折号，以帮助未来的页面开发人员，对称性不是必需的。

如果您需要合并行或列，或者需要更复杂的布局，一些开发工具可以帮助您创建自己的复杂表格。这个 table generator 或许可以帮助你做到这一点。

要在表格单元格中添加编号列表，请在标题和表格之间添加一个空行才能正确展示表格。否则，文本和格式将不会出现。

有关表格的更多信息，请参阅 kramdown 语法指南。

折叠

折叠部分内容用于隐藏信息，直到用户通过点击摘要文本来显示它。隐藏的内容内联显示。例如，这段代码：

<details>
  <summary markdown="span">This is the summary text, click me to expand</summary>

  This is the detailed text.

  We can still use markdown, but we need to take the additional step of using the `parse_block_html` option as described in the [Mix HTML + Markdown Markup section](#mix-html--markdown-markup).

  You can learn more about expected usage of this approach in the [GitLab UI docs](https://gitlab-org.gitlab.io/gitlab-ui/?path=/story/base-collapse--default) though the solution we use above is specific to usage in markdown.
</details>

结果是：

This is the summary text, click me to expand

This is the detailed text.

We can still use markdown, but we need to take the additional step of using the parse_block_html option as described in the Mix HTML + Markdown Markup section.

You can learn more about expected usage of this approach in the GitLab UI docs though the solution we use above is specific to usage in markdown.

GitLab Handbook 还支持详细信息的嵌套。

<details>
<summary markdown="span">First level collapsible item</summary>
**Lorem ipsum dolor sit amet...**
<details>
<summary markdown="span">Second level collapsible item</summary>
*Sed ut perspiciatis unde omnis iste natus...*
</details>
</details>

结果是：

First level collapsible item

Lorem ipsum dolor sit amet…

Second level collapsible item

Sed ut perspiciatis unde omnis iste natus…

要在折叠标题中添加表格，请务必添加：

<details markdown="1">

代码块

使用 kramdown 显示代码块有几个选择，大多数情况会使用反引号 `。

In-line

这是一个 `in-line` 代码块。

Output

In-line

This is an in-line code block.

Fenced

```
def hello
   puts "Hello world!"
end
```

高亮显示语法 Fenced Highlighted

```ruby
def hello
   puts "Hello world!"
end
```

```
def hello
   puts "Hello world!"
end
```
{: .language-ruby}

Output

Fenced

def hello
   puts "Hello world!"
end

Fenced Highlighted

def hello
   puts "Hello world!"
end

def hello
   puts "Hello world!"
end

缩进

在每行之前添加 4 个空格：

    def hello
       puts "Hello world!"
    end

Indented Highlighted

    def hello
       puts "Hello world!"
    end
{: .language-ruby}

Output

Indented

def hello
   puts "Hello world!"
end

Indented Highlighted

def hello
   puts "Hello world!"
end

嵌套

在每行之前添加 4 个空格，当在代码块中显示代码块时使用。

    ```
    def hello
       puts "Hello world!"
    end
    ```

Output

Nested

```
def hello
   puts "Hello world!"
end
```

在列表中

将每个项目的文本缩进 3 个空格，在代码块和列表项之间留空行，缩进 5 个空格会识别代码块：

1.   Item 1
1.   Item 2

     ```ruby
     def hello
        puts "Hello world!"
     end
     ```

1.   Item 3

Output

Item 1
Item 2
```
def hello
   puts "Hello world!"
end
```
Item 3

块引用

块引用是提及他人引用的好资源，就像我们在上面所做的那样。此外，可用于强调一个句子或一个小段落。

> This is a blockquote.
>     On multiple lines.
That may be lazy.
>
> This is the second paragraph.

----

> This is a paragraph.
>
> > A nested blockquote.
>
> ### Headers work
>
> * lists too
>
> and all other block-level **elements**.
>
> Even code blocks:
>
>      def hello
>        puts "Hello world!"
>      end
> {: .language-ruby}

Output

This is a blockquote. On multiple lines. That may be lazy.

This is the second paragraph.

This is a paragraph.

A nested blockquote.

Headers work

lists too

and all other block-level elements.

Even a code block:
 def hello
   puts "Hello world!"
 end

笔记

This is a regular paragraph.

**Note:** a note is something that needs to be mentioned but is apart from the context.
{: .note}

Output

This is a regular paragraph.

Note: a note is something that needs to be mentioned but is apart from the context.

作用类似于注释，内容不会被渲染。Markdown markup

This is a paragraph
{::comment}
This is a comment which is
completely ignored.
{:/comment}
... paragraph continues here.

Regular HTML markup

<!-- This is accepted as a comment too -->

Output

This is a paragraph … paragraph continues here.

锚点

可以在任意位置添加锚点：

[](){: name="hello-world"}

Some text

或使用简单的 ID：

Some text
{: #hello-world}

Font Awesome

可以使用 Font Awesome 图标。

Regular

### <i class="fas fa-puzzle-piece" aria-hidden="true"></i> Puzzle Icon
{: #puzzle}

And you can go further, such as the following.

Styled

### <i class="fab fa-gitlab fa-fw" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i> Purple GitLab Tanuki
{: #tanuki-purple}

### <i class="fab fa-gitlab fa-fw" style="color:rgb(252,109,38); font-size:.85em" aria-hidden="true"></i> Orange GitLab Tanuki
{: #tanuki-orange}

Output

Regular

Puzzle Icon

Styled

Purple GitLab Tanuki

Orange GitLab Tanuki

当在标题上这样做时，需要给它一个自定义 ID（例如，{: #puzzle}），否则由 kramdown 自动创建的 ID 看起来会很尴尬。

当您希望将图标显示为列表时使用 fa-fw 类，它们将与旁边的文本对齐。

Classes, IDs, and attributes

使用 Markdown 定义 CSS 类、元素 ID 和属性的方式非常独特。

但当您知道如何使用时，会爱上它的！看看使用 kramdown 做到这一点有多容易：

Paragraph
{: .class .class-1 .class-2}

Paragraph
{: #custom-id}

Paragraph
{: .class .class-1 #custom-id-1}

## Heading
{: .class .class-1 #custom-id-2}

Paragraph
{: .class #custom-id-3 style="padding-top:0" key="value"}

## Heading {#hello}

List:

- {: .class} List item with custom class
- {:#id} List item with custom id

To a [link]{: #link}, in-line.

This is a [link][google-es]{:hreflang="es"} in Spanish.

[link]: https://google.com
[google-es]: https://google.es

Output

Paragraph

Heading

Paragraph

Heading

List:

List item with custom class
List item with custom id

To a link, in-line.

This is a link in Spanish.

特殊 classes

阴影

当您的图片边缘没有明显边框时，应使用 shadow CSS 类。当使用具有白色背景或带有文本的截图（例如，我们用户界面的屏幕截图）时，就会发生这种情况，这张图片可能会被误认为是文本的一部分：

text screenshot

现在如果将 shadow 类应用于该图片，它会从文本中突出显示：

text screenshot with box shadow

要做到这一点，在图片标记之后添加 {: .shadow} 标记即可：

![image alternative text](/path/to/image.png){: .shadow}

笔记

正如前文所述，你可以添加 note 类段落：

Note: this is something I don't want to call attention to.

Markup:

**Note:** this is something I don't want to call attention to.
{: .note}

颜色

使用以下特殊类为标题或段落添加一个自定义类。

GitLab Orange

GitLab Orange Heading

Markup:

### GitLab Orange Heading
{: .gitlab-orange}

GitLab Purple

GitLab Purple Heading

Markup:

### GitLab Purple Heading
{: .gitlab-purple}

文字对齐

默认情况下，文本将始终向左对齐，以下几个选项可以使用自定义类改变文字对齐方向：

Center: .text-center
Right: .text-right
Justify: .text-justify

出于演示目的，它们在警告框中对齐，但这也可应用于常规段落和标题。

Align to the center

Center-aligned

Alert box markup:

Center-aligned
{: .alert .alert-info .text-center}

Paragraph markup:

Center-aligned
{: .text-center}

Heading markup:

### Center-aligned
{: .text-center}

Align to the right

Right-aligned

Right-aligned
{: .alert .alert-info .text-right}

Justify

Justified

Justified
{: .alert .alert-info .text-justify}

混合使用 HTML + Markdown

对于习惯使用常规 Markdown 的人来说，将 HTML 标签与 Markdown 混合使用几乎是“不可想象的”。而这一切都在这份文件中！

在文档开头使用以下标记：

{::options parse_block_html="true" /}

就可混合使用所有内容：

Something in **markdown**.

<p>Then an HTML tag with crazy **markup** _all over_ the place!</p>

Output

Something in markdown.

Then an HTML tag with crazy markup all over the place!

You can close the markup parser tag at any point, if you want to:

{::options parse_block_html="false" /}

Colorful sections

为了将注释和警告块添加到彩色框中，我们使用 Bootstrap 的 panel blocks 和 alert boxes。

彩色部分用于非常特定的目的，不得过度使用。

当您的描述包含多个段落或一个长段落时，请使用面板。对于单个和短段落，请改用警告框。

使用面板时，请确保将 HTML 解析器标记添加到文档正文的开头：{::options parse_block_html="true" /}。

根据您想要呈现给用户的内容复制粘贴以下代码并仅替换描述。可用的颜色有：蓝色 (info)、绿色 (success)、琥珀色 (warning) 和红色 (danger)，如下所示。

附加信息

使用以下代码，以获得重要的说明和其他信息：

<div class="panel panel-info">
**Note**
{: .panel-heading}
<div class="panel-body">

NOTE DESCRIPTION

</div>
</div>

对于单个段落，请使用警告框：

My important paragraph.
{: .alert .alert-info}

蓝色面板渲染如下：

Note

NOTE DESCRIPTION

蓝色警报框渲染如下：

My important paragraph.

如果您希望警报框内的文本也为蓝色，就需要将自定义样式应用于 markdown 文档。它们将覆盖现有样式，将以下 style 样式添加到文件末尾。

<style>
.alert-info {
  color: rgb(49,112,143) !important;
}
</style>

Warnings

对警告可以使用以下代码，例如使用不当可能会产生不同结果的信息：

<div class="panel panel-warning">
**Warning**
{: .panel-heading}
<div class="panel-body">

WARNING DESCRIPTION

</div>
</div>

应用于单个段落，请使用警告框：

My warning paragraph.
{: .alert .alert-warning}

琥珀色面板渲染如下：

Warning

WARNING DESCRIPTION

琥珀色警报框渲染如下：

My warning paragraph.

如果您希望警报框内的文本也为琥珀色，就需要将自定义样式应用于 markdown 文档。它们将覆盖现有样式，将以下 style 样式添加到文件末尾。

<style>
.alert-warning {
  color: rgb(138,109,59) !important;
}
</style>

Danger

将以下代码用于关键警告，例如会导致数据丢失的命令：

<div class="panel panel-danger">
**Danger**
{: .panel-heading}
<div class="panel-body">

DANGER DESCRIPTION

</div>
</div>

应用于单个段落，请使用警告框：

My danger paragraph.
{: .alert .alert-danger}

红色面板渲染如下：

Danger

DANGER DESCRIPTION

红色警报框渲染如下：

My danger paragraph.

如果您希望警报框内的文本也为红色，就需要将自定义样式应用于 markdown 文档。它们将覆盖现有样式，将以下 style 样式添加到文件末尾。

<style>
.alert-danger {
  color: rgb(169,68,66) !important;
}
</style>

Do's and Don'ts

您可以将绿色和红色面板或警告框组合用于“注意事项”：

<div class="panel panel-success">
**Do's**
{: .panel-heading}
<div class="panel-body">

THINGS TO DO

</div>
</div>

或者，使用警告框：

TO DO.
{: .alert .alert-success}

Not to do:

<div class="panel panel-danger">
**Don'ts**
{: .panel-heading}
<div class="panel-body">

THINGS NOT TO DO

</div>
</div>

或者，使用警告框：

NOT TO DO.
{: .alert .alert-danger}

通过这样做，“DO'S” 的绿色面板将如下所示：

Do's

THINGS TO DO

或者，如果您选择了警报框：

TO DO.

如果您希望警报框内的文本也为绿色，就需要将自定义样式应用于 markdown 文档。它们将覆盖现有样式，将以下 style 样式添加到文件末尾。

<style>
.alert-green {
  color: rgb(60,118,61) !important;
}
</style>

对于您在红色面板中的 "DON'TS" 将如下所示：

Don'ts

THINGS NOT TO DO

或者，如果您选择了红色警报框：

NOT TO DO.

自定义警报面板和警报框

默认情况下，Bootstrap 可以使用所有前面提到的警告框和面板。如果我们想要不同的颜色，我们需要自定义样式。在[ GitLab.cn] 我们可以使用橙色和紫色的，如下所示。

使用面板时，不要忘记将 HTML 解析器标记添加到文件的开头，以便能够混合 HMTL + Markdown: {::options parse_block_html="true" /}。

GitLab 橙色警报面板

Heading

Text in markdown.

面板块标记：

<div class="panel panel-gitlab-orange">
**Heading**
{: .panel-heading}
<div class="panel-body">

Text in markdown.

</div>
</div>

GitLab 橙色警报框

My text in an orange box.

Box block markup:

My text in an orange box.
{: .alert .alert-gitlab-orange}

GitLab 紫色警报面板

Heading

Text in markdown.

Panel block markup:

<div class="panel panel-gitlab-purple">
**Heading**
{: .panel-heading}
<div class="panel-body">

Text in markdown.

</div>
</div>

GitLab 紫色警报框

My text in an purple box.

Box block markup:

My text in an purple box.
{: .alert .alert-gitlab-purple}

GitLab Webcast 警报框

在 CTA 中用于博客文章中的 Webcast 公告。您也可以将其与 HMTL 解析器一起用于其他目的：

The webcast I want to announce - Register here!

{::options parse_block_html="true" /}

<i class="fab fa-gitlab" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i>&nbsp;&nbsp;
The webcast I want to announce - [Register here][webcast-link]!
&nbsp;&nbsp;<i class="fab fa-gitlab" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i>
{: .alert .alert-webcast}

样式

在 Markdown 中:

<style>
  .purple {
    color:inherit;
  }
  .purple:hover {
    color:rgb(107,79,187);
  }
</style>

加:

Hey! Hover the cursor over me and guess what?! :)
{: .purple}

Equals to:

Output

Hey! Hover the cursor over me and guess what?! :)

<style> 标签直接写在 Markdown 文件中！

嵌入文档

嵌入 Google Docs、Sheets、Slides 以及几乎所有提供 iframe 的内容都很容易。您唯一需要做的就是在 Markdown 文件中使用以下代码，并从要嵌入的文档中替换 iframe：

<figure class="video_container">
<iframe IFRAME CONTENT></iframe>
</figure>

Google 产品

对于 Google 产品，打开您的文档后，点击 File -> Publish to the web 即可，例如：

Google Sheets - File - Publish to the web

选择 Embed 检查设施，单击 Publish 并负责 <iframe>，然后转到您的 markdown 文件并将 iframe 包装到 <figure> 带有响应 video_container 类的标签中，如开头所示。

Google Sheets

让我们以这个 simple spreadsheet 为例，按照上面的信息找到 iframe：

Google Sheets - Embed iframe

复制下面的代码并粘贴到您的 Markdown 文件中（在其上下各留一个空行），然后用你自己的 <iframe> 替换：

<figure class="video_container">
<iframe src="https://docs.google.com/spreadsheets/d/1jAnvYpRmNu8BISIrkYGTLolOTmlCoKLbuHVWzCXJSY4/pubhtml?widget=true&amp;headers=false"></iframe>
</figure>

Output:

Google Slides

让我们用这个 GitLab slide deck.来举例说明，按照以下步骤上面找到的 iframe：

Google Slides - Embed iframe

复制下面的代码并粘贴到您的 Markdown 文件中（在其上下各留一个空行），然后用你自己的 <iframe> 替换：

<figure class="video_container">
<iframe src="https://docs.google.com/presentation/d/e/2PACX-1vS_iuMXnp61wlo4amm5nvHr4Ir8VUzisJSBsr7YEL7fKWAiT-9bmehyngtb9TYaFEsFnRokCyIXwsvY/embed?start=false&loop=false&delayms=3000" frameborder="0" width="960" height="569" allowfullscreen="true" mozallowfullscreen="true" webkitallowfullscreen="true"></iframe>
</figure>

Output:

Google Docs

不推荐嵌入 Google Docs，推荐将您的文档内容转换为 Markdown。如果您无论如何都需要嵌入它，请按照我们为 Google Sheets 和 Slides 提供的相同说明和相同逻辑，<iframe> 用 <figure> 标签包裹：

<figure class="video_container">
<iframe src="https://docs.google.com/document/d/1mHhOhvvrz7xgUPyn5VWCNuKgew5MRRGZp761B9prPqs/pub?embedded=true"></iframe>
</figure>

分享幻灯片

要从 SlideShare 嵌入，请转到要嵌入的文档并点击幻灯片下方的 Share 按钮，复制 Embed 下的代码并将其放在 figure 标签内。

请注意仅包含 iframe 内容并删除其他内容。SlideShare 还会在嵌入代码中添加一些其他信息，您必须删除这些信息，否则 markdown 页面将被破坏。

例如，我们想在 GitLab 页面上加入 Ivan 演讲的幻灯片，复制嵌入代码并删除除 iframe 外的所有其他内容，结果是这样的：

<figure>
<iframe src="//www.slideshare.net/slideshow/embed_code/key/EixD8OUMBX65Jy" width="595" height="485" frameborder="0" marginwidth="0" marginheight="0" scrolling="no" style="border:1px solid #CCC; border-width:1px; margin-bottom:5px; max-width: 100%;" allowfullscreen> </iframe>
</figure>

您可以放心地省略该 <figure> 标签，因为 SlideShare widget 已经是响应式的，但我们以这种方式显示是为了与手册的其余部分保持一致。

Output:

嵌入 GitLab 代码片段

要将 GitLab 代码片段嵌入到 Markdown 文件中，请从公开的代码段中复制嵌入代码并将其粘贴到文件中。

Markup:

<!-- leave a blank line here -->
<script src="https://gitlab.com/gitlab-org/gitlab-ce/snippets/1717978.js"></script>
<!-- leave a blank line here -->

Renders:

Markdown 编辑器

请使用 JihuLab.com 上提供的编辑器、以下代码编辑器之一或您习惯的代码编辑器来编写 Markdown 文档。

不建议使用普通的文本编辑器如 Google Docs、Microsoft Word 或 macOS 的 Pages 来编写，然后复制粘贴到 Markdown，因为它很可能会带来一些不同编码（非 UTF-8）的字符，这将导致 Markdown 无法正确展示。

如果你需要导入一个已经在文本编辑器中写好的文本，在 Mac 上使用 command+shift+V，或者在 Windows 或 Linux 上使用 control+shift+V 将其粘贴到你的markdown 文件中，通过不带格式的粘贴来减少麻烦。但也不能保证一定会成功，所以要仔细检查你的 HTML 输出。

GitLab.cn 提供的编辑器

Web IDE
Static Site Editor
GitLab's raw code editor

常见的代码编辑器

Markdown 编辑器（同时输入和预览）

Mac 版 Markdown 编辑器： Mou, iA Writer
浏览器内的 Markdown 编辑器: StackEdit

如果您不习惯编写 Markdown，这些编辑器可能会有所帮助。下图是在 Mou 上编辑的文件的截图。左侧是正在编写的 Markdown 文档，右侧是输出的预览。预览不会与最终结果完全相同，但它是一个非常好的参考，可以让您在输入时对正在执行的操作有一个很好的了解。

Mou for Mac - screenshot of markdown doc write and preview

StackEdit is awesome too, you can work on a markdown file even if you're away from your computer, or out of resources. It works from every major browser and automatically saves your work to Google Drive. StackEdit 也好用，可以在计算机资源不足时或在手机和平板上处理 Markdown 文件，适用于所有主流浏览器，并自动保存到 Google Drive。

补充说明

单词之间必须只用一个空格隔开，不要有多余的空格，可能导致其他问题。
句末不要留空格。

始终在块级标记元素之间留空行，列表项之间除外。示例：

  ---- (markup for horizontal line)
  <!-- blank line -->
  Paragraph.
  <!-- blank line -->
  Do not leave blank lines within list items:
  <!-- blank line -->
  - Item 1
  - Item 2
  - Item 3

正如前文所述，请勿跳过标题，保持 h1 → h2→ h3 → h4，而不是从不 h2 → h4。
保持标题简洁，不要在标题上加标点（除非需要问号或感叹号）。
尽量不要在列表上加标点，但如果这样做，请在整个列表中保持一致。
如果您必须提及不可点击的 URL，请使用反引号：http://an-example.com。
要将 Emoji 表情符号添加到您的文件中，请在你的使用组合键 control+cmd+space 唤出 Emoji 菜单或使用像Emoji Finder这样的网站。请不要过度使用它们！
要将花哨的表情符号添加到您的文件中，请单击control+cmd+space您的 Mac 并检查 ⭐️魔法⭐ 或使用像 Emoji Finder 这样的网站，但请不要过度使用！
如果您对在此文件中找到的任何标记感到困惑，您可以检查 raw file 以供参考，您将准确了解所有内容是如何编写以产生您在此页面上看到的结果的。

还有什么您知道但这里没有描述的内容吗？欢迎贡献！

Markdown 指南

维护者:

Markdown 风格指南

标题

Heading h2

Heading h3

Heading h4

段落、换行和水平线

Wrapping Text

常规段落和自动连接

额外的换行

水平线（分隔线）

强调：粗体和斜体

链接

内联链接

相对链接

邮件链接

标识符

列表

有序列表

无序列表

拆分列表

图片

图表

Mermaid

PlantUML

视频

BiliBili

YouTube

本地视频 (HTML5)

其他视频

展示多个视频

目录 (ToC)

表格

折叠

代码块

In-line

Fenced

缩进

嵌套

在列表中

块引用

Headers work

笔记

评论

锚点

Font Awesome

Puzzle Icon

Purple GitLab Tanuki

Orange GitLab Tanuki

Classes, IDs, and attributes

Heading

Heading

特殊 classes

阴影

笔记

颜色

GitLab Orange Heading

GitLab Purple Heading

文字对齐

混合使用 HTML + Markdown

Colorful sections

附加信息

Warnings

Danger

Do's and Don'ts

自定义警报面板和警报框

GitLab 橙色警报面板

GitLab 橙色警报框

GitLab 紫色警报面板

GitLab 紫色警报框

GitLab Webcast 警报框

样式

嵌入文档

Google 产品

Google Sheets

Output:

Google Slides

Output:

Google Docs