Markdown

Table of Contents

标准 Markdown

• 标题
• 强调
• 列表
• 链接
• 图片
• 块引用
• 行内 HTML
• 水平线
• 换行符
• 表格

GitLab Flavored Markdown

• 换行
• 单词中多个下划线
• URL 自动链接
• 代码和语法高亮
• 行内 Diff
• Emoji
• 特定的 GitLab 引用
• 任务列表

Wiki 独有的 Markdown

• Wiki - 直接网页链接
• Wiki - 直接文件链接
• Wiki - 层级链接
• Wiki - 根链接

参考文献

标准 Markdown

标题

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

另外, 对于 H1 和 H2, 可以使用下划线风格 (实际是 = 和 -):

Alt-H1
======

Alt-H2
------

H1

H2

H3

H4

H5

H6

另外, 对于 H1 和 H2, 可以使用下划线风格 (实际是 = 和 -):

Alt-H1

Alt-H2

标题的 ID 和 链接

所有 Markdown 渲染的标题自动获得 ID, 除了注释里面的.

当鼠标悬浮在标题上时, 可以看见这个标题的链接, 方便使用.

ID 由标题内容生成, 规则如下:

1. 所有文本转化为小写
2. 所有非单词文本被移除 (例如标点 / HTML)
3. 所有空格转化为连字符 -
4. 两个以上连续的连字符变为一个
5. 如果已经有相同 ID 的标题, 会在 ID 结尾附加唯一的增量数字, 从1开始.

例如:

# 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

会产生如下的链接 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
5. this-header-has-spaces-in-it-1

注意, Emoji 表情的处理在标题 ID 生成之前, 所以 Emoji 被转化为图片, 并从 ID 中去除.

强调

强调, 即斜体字, 使用 *星号* 或 _下划线_.

重点强调, 即粗体字, 使用 **星号** 或 __下划线__.

可以组合使用 **星号和_下划线_**.

删除线, 使用两个波浪号. ~~删除.~~

强调, 即斜体字, 使用 星号 或 下划线.

重点强调, 即粗体字, 使用 星号 或 下划线.

可以组合使用 星号和下划线.

删除线, 使用两个波浪号. 删除.

列表

1. 第一行
2. 另一行
  * 没有行号的子列表.
1. 实际上数字是多少没有关系, 只要是数字即可
  1. 有行号的子列表
4. 还是另一行.

* 没有行号的列表可以使用星号
- 或者减号
+ 或者加号

1. 第一行
2. 另一行

• 没有行号的子列表.

1. 实际上数字是多少没有关系, 只要是数字即可
2. 有行号的子列表
3. 还是另一行.

• 没有行号的列表可以使用星号

• 或者减号

• 或者加号

如果一个列表包含多个段落, 每个段落需要有4个空格缩进

1.  第一行

   第一行的第二段.
2.  另一行

1. 第一行

   第一行的第二段.

2. 另一行

如果第二段不是缩进4个空格, 则第二行会被错误的标记成 1.

1.  第一行

    第一行的第二段.
2.  另一行

1. 第一行

第一行的第二段.

2. 另一行

链接

有两种方式创建链接: 行内和引用.

[这是一个行内链接](https://www.we.com)

[这是一个引用链接][任意的大小写无关的引用文字]

[这是一个链接到仓库文件的相对引用](LICENSE)

[可以使用数字作为引用格式的链接][1]

或留空第二个括号, 使用 [链接文字本身][]

插入一些文本, 以证明引用链接可以在后面.

[任意的大小写无关的引用文字]: https://www.mozilla.org
[1]: http://slashdot.org
[链接文字本身]: https://www.reddit.com

这是一个行内链接

这是一个引用链接

这是一个链接到仓库文件的相对引用

可以使用数字作为引用格式的链接

或留空第二个括号, 使用 链接文字本身

插入一些文本, 以证明引用链接可以在后面.

注意

相对链接不允许项目文件和 wiki 页面交叉引用. 因为在 GitLab 里面, wiki 是一个独立的 git 仓库. 例如:

[这是一个引用格式的链接](style)

会链接到 wikis/style (因为是在 wiki 的 markdown 文件里).

图片

这是 logo:

行内样式:
[图片上传失败...(image-3e42d1-1590569803675)]

引用样式:
![备用文字1][logo]

[logo]: img/markdown_logo.png

这是 logo:

行内样式:
[图片上传失败...(image-103008-1590569803675)]

引用样式:

块引用

> 块引用在邮件里很方便的模拟回复文本.
> 这一行在同一块内.

这一行引用中断.

> 这段文字非常的长, 超过了一行的长度, 产生了换行. 但它还是会被正确的引用. 现在继续在这一段写文字, 保证每个人看到这一段时它都换行了. 可以在引用中*加入* **Markdown**.

块引用在邮件里很方便的模拟回复文本.
这一行在同一块内.

这一行引用中断.

这段文字非常的长, 超过了一行的长度, 产生了换行. 但它还是会被正确的引用. 现在继续在这一段写文字, 保证每个人看到这一段时它都换行了. 可以在引用中加入 Markdown.

行内 HTML

可以在 Markdown 文件里面写 HTML , 通常情况下会正常显示.

参考文档 HTML::Pipeline's SanitizationFilter 类中, 可以使用的 HTML 标签和属性. 除了默认的 SanitizationFilter 列表, GitLab 允许使用 span 元素.

<dl>
  <dt>定义列表</dt>
  <dd>偶尔会使用.</dd>

  <dt>Markdown 在 HTML 里</dt>
  <dd> *不会* **正常** 显示. 使用 HTML <em>标签</em>.</dd>
</dl>

<dl>
<dt>定义列表</dt>
<dd>偶尔会使用.</dd>

<dt>Markdown 在 HTML 里</dt>
<dd> 不会 正常 显示. 使用 HTML <em>标签</em>.</dd>
</dl>

水平线

三个或以上

---

连字符

***

星号

___

下划线

三个或以上

连字符

星号

下划线

换行符

推荐多尝试 -- 敲 <Enter> 一次, 然后再敲一次, 看有什么结果.

一些例子:

开始的一行.

这一行与上一行之间有两个回车, 所以它是*单独的一段*.

这一行也是单独的一段, 但是...
这一行之前只有一个回车, 所以是*同一段*的另一行.

这一行也是单独的一段, 而且...  
这一行另起一行, 因为之前行末尾有两个空格.

开始的一行.

这一行与上一行之间有两个回车, 所以它是单独的一段.

这一行也是单独的一段, 但是...
这一行之前只有一个回车, 所以是同一段的另一行.

这一行也是单独的一段, 而且...
这一行另起一行, 因为之前行末尾有两个空格.

表格

表格不是核心的 Markdown 语义, 但它是 GFM 的, 这里 Markdown 支持表格.

| header 1 | header 2 |
| -------- | -------- |
| cell 1   | cell 2   |
| cell 3   | cell 4   |

上面代码会有如下输出:

注意

表格头和表格体中间的横线, 每一列至少需要有三个连字符.

通过添加冒号, 可以设置那一列的文本对其:

| 左对齐 |中间对齐 | 右对齐 | 左对齐 |中间对齐 | 右对齐 |
| :----------- | :------: | ------------: | :----------- | :------: | ------------: |
| Cell 1       | Cell 2   | Cell 3        | Cell 4       | Cell 5   | Cell 6        |
| Cell 7       | Cell 8   | Cell 9        | Cell 10      | Cell 11  | Cell 12       |

GitLab Flavored Markdown (GFM)

注意:
不是所有的 GitLab 的 Markdown 扩展在网站上都可用.

为了最好的效果, 请参考 GitLab 渲染的: markdown.md

GitLab 使用 Redcarpet Ruby library 来处理 Markdown.

GitLab 使用 "GitLab Flavored Markdown" (GFM). 它在一些方面扩展了标准的 Markdown, 并添加非常有用的功能. 它受到 GitHub Flavored Markdown 启发.

可以在以下区域使用 GFM:

• comments
• issues
• merge requests
• milestones
• snippets (the snippet must be named with a .md extension)
• wiki 页面
• 仓库里的 markdown 文档

也可以在 GitLab 中使用其它富文本文件. 可能需要安装依赖. 参考github-markup gem readme .

换行

如果这个没有正确渲染, 参考 https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/markdown/markdown.md#newlines

GFM 遵循 markdown 规则 paragraphs and line breaks are handled.

一个段落是一个或多个连续的文本行, 段与段之间由一个或多个空行分割. 换行符, 或软回车, 是行末有两个或更多空格:

Roses are red  [加两个或更多空格]
Violets are blue

Sugar is sweet

Roses are red
Violets are blue

Sugar is sweet

单词中多个下划线

如果这个没有正确渲染, 参考 https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/markdown/markdown.md#multiple-underscores-in-words

没有理由仅仅将一个单词的部分内容作为斜体. 尤其在处理代码和名字时, 经常出现多个下划线. 因此 GFM 忽略单词中的多个下划线:

perform_complicated_task

do_this_and_do_that_and_another_thing

perform_complicated_task

do_this_and_do_that_and_another_thing

URL 自动链接

如果这个没有正确渲染, 参考 https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/markdown/markdown.md#url-auto-linking

GFM 几乎会给所有 URL 自动加入超链接:

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

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

代码和语法高亮

如果这个没有正确渲染, 参考 https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/markdown/markdown.md#code-and-syntax-highlighting

GitLab 使用 Rouge Ruby library 来语法高亮. 支持的语言列表请访问 Rouge 网站.

代码块用 <code>```</code> 包围, 或者使用4个空格的缩进. 只有前一种支持语法高亮

行内 `code` 用  `` ` ``.

行内 code 用 `.

举例:

```javascript
var s = "JavaScript syntax highlighting";
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>.
```

生成:

var s = "JavaScript syntax highlighting";
alert(s);

def function():
    #indenting works just fine in the fenced code block
    s = "Python syntax highlighting"
    print s

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

行内 Diff

如果这个没有正确渲染, 参考 https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/markdown/markdown.md#inline-diff

使用行内 diff 标签, 可以显示 {+ additions +} 或 [- deletions -].

可以使用方括号或花括号, 例如 [+ additions +] 或 {- deletions -}.

然而不可以混合使用, 例如:

• {+ additions +]
• [+ additions +}
• {- deletions -]
• [- deletions -}

Emoji

如果这个没有正确渲染, 参考 https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/markdown/markdown.md#emoji

有时想要像 :monkey: 一样胡闹, 将 :star2: 放入 :speech_balloon:. 没问题:

:zap: 可以在支持 GFM 的任何地方使用 emoji. :v:

可以用来指出一个  :bug: 或警告 :speak_no_evil: 补丁. 如果有人优化了你  :snail: 一样的代码, 发给他们 :birthday: 以示感谢. 人们会 :heart: 你.

如果你第一次接触这些, 不要 :fearful:. 加入 :family: 很容易. 只需要看一下支持的代码 .

参考 [Emoji Cheat Sheet](http://emoji.codes) 以获取所有支持的 emoji 代码. :thumbsup:

有时想要像 :monkey: 一样胡闹, 将 :star2: 放入 :speech_balloon:. 没问题:

:zap: 可以在支持 GFM 的任何地方使用 emoji. :v:

可以用来指出一个 :bug: 或警告 :speak_no_evil: 补丁. 如果有人优化了你 :snail: 一样的代码, 发给他们 :birthday: 以示感谢. 人们会 :heart: 你.

如果你第一次接触这些, 不要 :fearful:. 加入 :family: 很容易. 只需要看一下支持的代码 .

参考 Emoji Cheat Sheet 以获取所有支持的 emoji 代码. :thumbsup:

特定的 GitLab 引用

GFM 可以识别特殊的引用.

可以很方便的引用项目中的 issue, commit, member 或整个 team.

GFM 会将其转换为指向引用的链接, 方便跳转.

GFM 支持以下符号:

GFM 也可以实现一定的跨项目引用:

任务列表

如果这个没有正确渲染, 参考 https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/markdown/markdown.md#task-lists

可以添加 issue, merge request 和 comment 的任务列表. 创建任务列表, 需要添加特定格式的 Markdown 列表:

- [x] Completed task
- [ ] Incomplete task
    - [ ] Sub-task 1
    - [x] Sub-task 2
    - [ ] Sub-task 3

• Completed task
• Incomplete task
  • Sub-task 1
  • Sub-task 2
  • Sub-task 3

任务列表不能在 title 里面创建, 只能在文章里.

Wiki 独有的 Markdown

以下样例显示 wiki 里面的链接行为.

Wiki - 直接网页链接

包含页面缩略名的链接会指向这个页面, 在 wiki 的最上一层.

以下超链接会链接到 wiki 根目录的 documentation 页面:

[Link to Documentation](documentation)

Wiki - 直接文件链接

带有文件名的链接指向那个文件, 相对于当前页面.

如果超链接在 <your_wiki>/documentation/related 页面, 会链接到 <your_wiki>/documentation/file.md 文件:

[Link to File](file.md)

Wiki - 层级链接

链接可以使用相对当前页面的结构 ./<page>, ../<page>, 等等.

• 如果超链接在 <your_wiki>/documentation/main, 它会链接到 <your_wiki>/documentation/related:

  [Link to Related Page](./related)
  

• 如果超链接在 <your_wiki>/documentation/related/content, 它会链接到 <your_wiki>/documentation/main:

  [Link to Related Page](../main)
  

• 如果超链接在 <your_wiki>/documentation/main, 它会链接到 <your_wiki>/documentation/related.md:

  [Link to Related Page](./related.md)
  

• 如果超链接在 <your_wiki>/documentation/related/content, 它会链接到 <your_wiki>/documentation/main.md:

  [Link to Related Page](../main.md)
  

Wiki - 根链接

以 / 开始的链接, 相对于 wiki 的根目录.

• 这个链接到 <wiki_root>/documentation:

  [Link to Related Page](/documentation)
  

• 这个链接到 <wiki_root>/miscellaneous.md:

  [Link to Related Page](/miscellaneous.md)
  

参考文献

• Markdown-Cheatsheet.
• Markdown Syntax Guide 标准 Markdown 语义
• Dillinger.io 测试标准 markdown.