Markdown 入门

据 GitHub Flavored Markdown（GFM）官方文档介绍，Markdown是由约翰·格鲁伯（John Gruber）在亚伦·斯沃茨（Aaron Swartz）的帮助下开发，并在2004年发布的标记语言。

其设计灵感主要来源于纯文本电子邮件的格式，目标是让人们能够使用易读、易写的纯文本格式编写文档，而且这些文档可以转换为HTML（Hyper Text Markup Language，超文本标记语言）文档。

简单点说，Markdown就是由一些简单的符号（如* /-> [] （）#）组成的用于排版的标记语言，其最重要的特点就是可读性强。

基础语法

字体

标题
Markdown语法中标题支持使用两种标记：底线（-/=）和#。
- 使用底线的语法如下
  1
  2
  标题内容
  =========
  或
  1
  2
  标题内容
  --------
  说明
  1. 底线=表示一级标题；
  2. 底线-表示二级标题；
  3. 底线符号的数量至少两个；
  4. 该语法只支持一级标题和二级标题。
- 使用#的语法如下
  1
  # + 空格 + 标题内容
  说明
  1. 行首插入#表示标题；
  2. #的个数表示标题的等级；
  3. 推荐在#的后面使用一个空格与标题内容隔开；
  4. Markdown中最多只支持前六级标题。
- 规范建议
  1. 建议使用#标记标题，而不是使用底线，因为底线会使标题难以阅读和维护；
  2. 建议标题的前后都要空一行（除文章开头的标题外），#与标题文本之间也要留有一个空格；
  3. 不要有多余的空格。建议标题要写在一行的开头，结尾也不要有空格；
  4. 建议标题的结尾不要有标点符号。
粗体和斜体
在Markdown语法中，粗体由两个*或两个_包裹，斜体由一个*或一个_包裹。
- 粗体格式的语法如下
  1
  2
  3
  **加粗内容**
  或
  __加粗内容__
- 斜体格式的语法如下
  1
  2
  3
  *斜体内容*
  或
  _斜体内容_
- 规范建议
  1. 建议使用*包裹，而不使用_包裹，因为前者的可读性更强；
  2. 建议在粗体和斜体语法标记的内部不要使用空格。

段落与换行

Markdown中的段落由一行或多行文本组成，不同的段落之间使用空行来标记。

语法说明
1. 如果行与行之间没有空行，则会被视为同一段落；
2. 如果行与行之间有空行，则会被视为不同的段落；
3. 空行是指行内什么都没有，或只有空格和制表符；
4. 如果想在段内换行，则需要在上一行的结尾插入两个以上的空格然后按回车键。
规范建议
1. 为便于阅读，应限制每行字符的数量（通常为80个字符），可以在编辑器中进行设置；
2. 在一句话结束之后换行；
3. 当URL较长时换行（或通过引用链接进行优化）。

列表
在Markdown中支持使用有序列表和无序列表。
- 有序列表的语法如下
  1
  数字序号 + 英文句号 + 空格 + 列表内容
- 无序列表的语法如下
  1
  */+/- + 空格 + 列表内容
- 嵌套列表的使用方式为通过Tab控制缩进。
- 规范建议
  1. 建议使用-来标记无序列表；
  2. 如果一个列表中所有的列表项都没有换行，建议在-和列表项中使用一个空格；
  3. 如果列表项有换行，则建议给无序列表使用三个空格，给有序列表使用两个空格；
  4. 如果每个列表项都只有一行，建议列表项之间不要有空行；
  5. 如果列表项中有换行，建议在列表项之间空一行；
  6. 建议在列表前/后都空一行；
  7. 数字、字符、符号列表使用英文半角句号，句号后加空格。
分割线
在Markdown中使用三个以上的*/-/_来标记分割线。
- 分割线的语法如下
  1
  2
  3
  4
  5
  ***
  或
  ---
  或
  ___
- 语法说明
  1. 分割线须使用至少三个*/-/_来标记；
  2. 可以在标记符中间加上空格；
  3. 行内不能有其他的字符。

图片

插入图片的语法如下
1
![图片替代文字](图片地址)
语法说明
1. 图片替代文字在图片无法正常显示时会比较有用，正常情况下也可以为空；
2. 图片地址可以是本地图片的路径或网络图片的地址；
3. 本地图片支持相对路径和绝对路径两种方式。

链接

文字链接
1
[链接文字](链接地址)
引用链接
1
2
3
[链接文字][链接标记]
...
[链接标记]:链接地址
- 语法说明
  1. 链接标记可以有字母、数字、空格和标点符号；
  2. 链接标记不区分大小写；
  3. 定义的链接内容可以放在当前文件的任意位置，建议放在页尾；
  4. 当链接地址为网络地址时要以 http/https 开头，否则会被识别为本地地址；
  5. 链接地址外加括号()会使地址变成本地地址。
网址链接
在Markdown中，将网络地址或邮箱地址使用<>包裹起来会被自动转换为超链接，语法如下
1
<URL 或邮箱地址>
使用规范
1. 使用有意义的连接标题；
2. 建议使用<>包裹自动链接；
3. 自动链接要以 http/https 开头。

行内代码与代码块

行内代码
在Markdown中，行内代码应用使用`包裹，语法如下
1
...`行内代码`...
代码块
在Markdown中，代码块以Tab键或4个空格开头，语法如下
1
[Tab]代码块
或
1
代码块
使用规范
1. 除行内代码可以使用`包裹以外，也可用于转义或强调字符；
2. 如果代码超过一行，可以使用围栏代码块（扩展语法），并显式地声明语言；
3. 对于简单的代码片段，更推荐使用4个空格缩进的代码块；
4. 最好避免在shell命令中使用任何换行操作，可以在行尾使用一个\，这样既能避免换行，又能提高源码的可读性；
5. 建议不要在没有输出内容的shell命令前加上$；
6. 建议在有输出内容的shell命令前加上$。

引用

语法
在Markdown中，引用由> + 引用内容来标记。
- 语法说明
  1. 多行引用也可以在每一行的开头都插入>；
  2. 在引用中可以嵌套引用；
  3. 在引用中可以使用其他的Markdown语法；
  4. 引用中也可以使用段落与换行的格式。
使用规范
- 建议在引用的标记符号>后添加一个空格；
- 建议每一行引用都使用符号>；
- 不要在引用中添加空行。

转义

可以使用\符号来标记想正常在md文件中显示的符号，语法为\特殊符号。可被转义的特殊符号有

\ 反斜线
` 反引号
* 星号
_ 底线
{} 花括号
[] 方括号
() 括弧
# 井字号
+ 加号
- 减号
. 英文句点
! 惊叹号

扩展语法GFM

删除线

删除线的语法为~~被删除的文字~~。

表情符号

表情符号的语法为:表情代码:。

自动链接

在GFM扩展语法中，可以不使用<>包裹www或http://开头的URL地址的自动链接。

若不想使用该省略语法，可以使用`包裹来避免使用自动链接。

表格

表格的语法如下

|表头|表头|表头|
|----|----|----|
|内容|内容|内容|
|内容|内容|内容|

语法说明

单元格使用|来分隔；
单元格和|之间的空格会被移除；
表头与其他行之间使用-来分隔；
对齐格式写在-分隔行中，有
- 左对齐（默认）:-
- 右对齐-:
- 居中对齐:-:
表格中不能使用块级元素（代码区块、引用区块）。

使用规范

在表格的前后各空一行；
在每一行的最前和最后使用|，每一行中的|尽量对齐；
不要使用庞大复杂的表格。

任务列表

语法
1
2
- [ ] 未勾选
- [x] 已勾选
语法说明
1. 任务列表由-、+或空格开头；
2. x通常大小写不敏感，但出于兼容性考量，推荐使用小写；
3. []内的字符为空格时表示未选中，为x时表示选中；
4. 任务列表可以嵌套。

围栏代码块

语法

```
代码片段
```
或
~~~
代码片段
~~~

语法说明
使用围栏代码块可以通过加上编程语言的名字来实现语法高亮。
使用规范
建议使用空行包裹围栏代码块。

锚点

锚点，也称为书签，用来标记文档的特定位置。使用锚点可以跳转到当前文档或其他文档中指定的标记位置。

语法
1
[锚点描述](#锚点名)
语法说明
1. 锚点名建议使用字母和数字；
2. 锚点名大小写敏感；
3. 锚点名中不能使用空格和特殊字符。

排版技巧

空格

需要加空格的情况
- 中英文之间、中文/英文和数字之间需要加空格；
- 英文标点符号与后面的字符之间需要加空格，与前面的字符之间不需要加空格；
- 在中文/英文中使用半角字符>标识路径时，两边都需要加空格；
不需要加空格的情况
- 中文标点符号和数字、中文、英文之间不需要加空格；
- 数字和百分号之间不需要加空格；
- 数字与单位符号之间不需要添加空格；
- 英文和数字组合成的名字之间不需要空格；
- 当半角字符/表示“或”、“路径”的意思时，与前后的字符之间均不加空格；
- 货币符号后不加空格；
- -表示“负号”的意思时后面不加空格。

全角和半角

中文标点是全角，和中文字符一样占两个字节。英文标点和数字是半角，和英文字符一样占一个字节。

在中文排版中，使用全角标点符号；
在英文排版中，使用半角标点符号。