Markdown 语法说明及写作风格

Markdown 是一种轻量级标记语言，创始人为约翰·格鲁伯（John Gruber）。它允许人们“使用易读易写的纯文本格式编写文档，然后转换成有效的XHTML(或者HTML)文档”。这种语言吸收了很多在电子邮件中已有的纯文本标记的特性。

Markdown同时还是一个由Gruber编写的Perl脚本：Markdown.pl。它把用markdown语法编写的内容转换成有效的、结构良好的XHTML或HTML内容，并将左尖括号(‘<’)和&号替换成它们各自的字符实体引用。它可以用作单独的脚本，Blosxom和Movable Type的插件又或者BBEdit的文本过滤器。

Markdown 提倡简洁明快的语言来标记编辑文档，并且它是宽松的，提供了多种形式的标记语法，例如链接和标题的标记。但使用同一的写作风格有利于管理文档，使文档结构清晰，前后一致。本文旨在整理一些流传的 Markdown 写作风格，同时可作为 Markdown 的语法参考。因为带有主观的风格偏向，所以文中并没有指明完善的 Markdown 标记语法，只选择了自己感觉良好的形式。文中内容来源于网络社区的贡献，非本人原创，仅作整理提炼。写作风格带有个人色彩，文中指出的风格并不一定适合其他人，你可以根据自己的需求来调整。写作风格指导涉及各个平台及语言处理 Markdown 的解析方式、使用的 Style 文件的差别、排版领域等相关的知识，因而随着发展会产生变化，此文档也会不断更新。文末会有修订记录，供参考查阅。

换行符

避免使用换行符，因为它们没有明确的语义。必要时使用末尾两个空格加换行来插入换行符。

标题

1
2
3

# Header 1
## Header 2
### Header 3

• 使用 atx-style 风格且不闭合 #.
• 在 # 和标题间加入一个空格，在 # 前不加空格。
• 在标题上下用空行隔开，除非标题在文档开头。
• 避免在同 Markdown 文件中使用相同的标题。
• 不要跳跃使用标题等级。
• 标题不要以 : 。 .结尾。
• 每一个同层级的空标题都假定是同义的。若希望在标题中使用多个关键词，就创建一个同层级的空标题吧。

引用

1
2
3
4

> a
> b
>
> c

• 符号 > 后接一个空格。
• 在每一行使用 > 符号，包括强制换行的句子。
• 不要在单独的引用中使用空行。

列表

标记

无序

1
2

- a
- b

使用 - 来标记。

有序

1
2
3

1. a
1. b
1. c

• 尽量选用 1. 标记有序列表，除非打算通过数字在相同 Markdown 文件或者外部文件中引用他们。
• 尽量使用无序列表，除非有通过数字引用的需求。最佳则是从来不通过序号来引用。

列表项中的空格

1
2
3
4
5
6
7
8
9
10
11
12

- a
- b

-   item that
    is wrapped

-   item 2

1.  item that
    is wrapped

2.  item 2

• 如果每一个列表项的内容都只有一段，使用一个空格。
• 否则，对于列表中每一项：
  • 无序列表使用 3 个空格。
  • 有序列表使用 2 个空格。

列表内容的缩进及空行

1
2
3
4
5
6
7
8
9
10
11
12

Before.

-   item that
    is wrapped

-   item 2

-   item 3

    Content 3

After.

• 列表中内容的缩进必须和第一个列表项一致。
• 如果每一个列表项只有一行，不要再列表项之间增加空行，否则，在每一个列表项之间增加空行。
• 列表外建议留有一空行。

代码区域

1

var a = 1;

使用 fenced code blocks.

水平横线

1

---

• 使用 3 个无空格连字符。
• 不要使用水平线除非表明 End of a header.

表格

1
2
3
4
5
6
7
8

Before.

| h    | Long header |
|------|-------------|
| abc  | def         |
| abc2 | def2        |

After.

• 用一空行包围表格。
• 不要缩进表格。
• 用 | 包裹表格的每一行。
• 竖直对齐所有表格边框。
• 将标题和内容用连字符分割，用对齐的 |.
• | 周围必须要有一个空格，除非是外部的 |.
• 列的宽度通过列中最长的单元格确定。

分离相连的列表

1
2
3
4
5
6
7
8
9
10
11
12

- list 1
- list 1

<!-- -->

- list 2
- list 2

<!-- -->

> blockquote 1
> blockquote 2

分离连续:

• 列表
• 缩进的代码块
• 引用
• 列表之后跟随额外的代码块

使用一个空白的 HTML 注释 <!-- -->.

强调

强调（强调元素，默认粗体）

使用双星号 **blod**.

强调（强调语义，默认斜体）

使用单星号 *italic*.

链接

1
2
3

<http://example.com>
<a href="mailto:[email protected]">Mail</a>
[example](http://example.com "example")

• 不要使用不带尖括号的自动链接。
• 如果不想文字链接自动链接，将他们以代码区块方式包裹。
• 不适用电子邮件自动链接 <[email protected]>. 使用纯 HTML.

图像

1

![alt text](/iamges/rainy.jpg "title")

修订记录

• 2016.3.1 - 初版发布
• 2016.3.5 - 新增图像；修正强调语义；修正链接表示；优化修订记录样式。

参考链接

1. Markdonw书写风格指南
2. 原始设计规范
3. CommonMark
4. Markdown Style Guide
5. Style Guidelines: Markdown