markdown的学习和.md文件使用

作者: 求长生 | 来源:发表于2020-05-27 16:57 被阅读0次

Markdown

标准 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 由标题内容生成, 规则如下:

所有文本转化为小写
所有非单词文本被移除 (例如标点 / HTML)
所有空格转化为连字符 -
两个以上连续的连字符变为一个
如果已经有相同 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:

this-header-has-spaces-in-it
this-header-has-a-in-it
this-header-has-unicode-in-it-한글
this-header-has-spaces-in-it
this-header-has-spaces-in-it-1

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

强调

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

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

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

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

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

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

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

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

列表

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

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

第一行
另一行

没有行号的子列表.

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

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

或者减号

或者加号

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

1.  第一行

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

第一行

第一行的第二段.
另一行

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

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   |

上面代码会有如下输出:

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       |

左对齐	中间对齐	右对齐	左对齐	中间对齐	右对齐
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://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 支持以下符号:

输入	引用
`@user_name`	特定用户
`@group_name`	特定组
`@all`	整个 team
`#123`	issue
`!123`	merge request
`$123`	snippet
`~123`	label ID
`~bug`	单个词语 label
`~"feature request"`	多个词语 label
`%123`	milestone ID
`%v1.23`	单个词语 milestone
`%"release candidate"`	多个词语 milestone
`9ba12248`	特定的 commit
`9ba12248...b19a04f5`	commit 范围
`[README](doc/README)`	仓库文件引用

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

输入	引用
`namespace/project#123`	issue
`namespace/project!123`	merge request
`namespace/project%123`	milestone
`namespace/project$123`	snippet
`namespace/project@9ba12248`	特定的 commit
`namespace/project@9ba12248...b19a04f5`	commit 范围
`namespace/project~"Some label"`	指定 label 的 issue

任务列表

如果这个没有正确渲染, 参考 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.