Markdown 书写语法及规范

发表于 2017/11/05 更新于 2021/03/03 阅读次数：

markdown

区块元素

标题

Markdown 支持两种标题的语法，类 Setext 和类 atx 形式。

类 Setext 形式是用底线的形式，利用 = （最高阶标题）和 - （第二阶标题），例如：

1 2	这是一级标题 ==========

1 2	这是二级标题 ----------

至少两个以上的 = 和 - 都可以有效果。

类 Atx 形式则是在行首插入 1 到 6 个 # ，对应到标题 1 到 6 阶，例如：

# 这是一级标题

## 这是二级标题

### 这是三级标题

#### 这是四级标题

##### 这是五级标题

###### 这是六级标题

你可以选择性地「闭合」类 atx 样式的标题，这纯粹只是美观用的，若是觉得这样看起来比较舒适，你就可以在行尾加上 # ，而行尾的 # 数量也不用和开头一样（行首的井字符数量决定标题的阶数）：

# 这是一级标题 #

## 这是二级标题 ##

### 这是三级标题 ###

区块引用

Markdown 区块引用是使用类似 email 中用 > 的引用方式。如果你还熟悉在 email 信件中的引言部分，你就知道怎么在 Markdown 文件中建立一个区块引用，那会看起来像是你自己先断好行，然后在每行的最前面加上 > ：

引用区块的第一段。

引用区块的第二段。

1
2
3

> 引用区块的第一段。
> 
> 引用区块的第二段。

Markdown 也允许你偷懒只在整个段落的第一行最前面加上 > ：

从前有座山，山里有个庙，庙里有个老和尚，给小和尚讲故事。故事讲的是：从前有座山，山里有个庙，庙里有个老和尚，给小和尚讲故事。故事讲的是：从前有座山，山里有个庙，庙里有个缸，缸里有个盆，盆里有个碗，碗里有个豆，我吃了，你馋了（完）。

> 从前有座山，山里有个庙，庙里有个老和尚，给小和尚讲故事。故事讲的是：从前有座山，山里有个庙，庙里有个老和尚，给小和尚讲故事。故事讲的是：从前有座山，山里有个庙，庙里有个缸，缸里有个盆，盆里有个碗，碗里有个豆，我吃了，你馋了（完）。

区块引用可以嵌套（例如：引用内的引用），只要根据层次加上不同数量的 > ：

这是第一个引用。

这是嵌套引用。

回到第一级。

> 这是第一个引用。
> 
> > 这是嵌套引用。
> 
> 回到第一级。

引用的区块内也可以使用其他的 Markdown 语法，包括强调、列表、代码块等：

这是一段强调文本

这是第一行列表项。

这是第二行列表项。

列表

Markdown 支持有序列表和无序列表。

无序列表使用 * 、 + 或是 - 作为列表标记：

Red
Green
Blue

1
2
3

* Red
* Green
* Blue

等同于：

1
2
3

+ Red
+ Green
+ Blue

也等同于：

1
2
3

- Red
- Green
- Blue

有序列表则使用数字接着一个英文句点：

Red
Green
Blue

1
2
3

1. Red
2. Green
3. Blue

很重要的一点是，你在列表标记上使用的数字并不会影响输出的 HTML 结果，上面的列表所产生的 HTML 标记为：

<ol>
    <li>Red</li>
    <li>Green</li>
    <li>Blue</li>
</ol>

如果你的列表标记写成：

1
2
3

1. Red
1. Green
1. Blue

或甚至是：

1
2
3

5. Red
2. Green
1. Blue

你都会得到完全相同的 HTML 输出。重点在于，你可以让 Markdown 文件的列表数字和输出的结果相同，或是你懒一点，你可以完全不用在意数字的正确性。

如果你使用懒惰的写法，建议第一个项目最好还是从 1. 开始，因为 Markdown 未来可能会支持有序列表的 start 属性。

代码块

和程序相关的写作或是标签语言原始码通常会有已经排版好的代码区块，通常这些区块我们并不希望它以一般段落文件的方式去排版，而是照原来的样子显示，Markdown 会用 <pre> 和 <code> 来把代码区块包起来。

要在 Markdown 中建立代码区块很简单，只要简单地缩进 4 个空格或是 1 个制表符就可以，例如下面的输入：

1
2
3

这是一个普通段落。

    这是一个代码区块。

Markdown 会转换成：

1
2
3

<p>这是一个普通段落。</p>

<pre><code>这是一个代码区块。</code></pre>

这个每行一阶的缩进（4 个空格或是 1 个制表符），都会被移除，例如：

Here is an example of AppleScript:

    tell application "Foo"
        beep
    end tell

会被转换为：

<p>Here is an example of AppleScript:</p>

<pre><code>
    tell application "Foo"
        beep
    end tell
</code></pre>

一个代码区块会一直持续到没有缩进的那一行（或是文件结尾）。

在代码区块里面， & 、 < 和 > 会自动转成 HTML 实体，这样的方式让你非常容易使用 Markdown 插入范例用的 HTML 原始码，只需要复制贴上，再加上缩进就可以了，剩下的 Markdown 都会帮你处理，例如：

1
2
3

<div class="footer">
    &copy; 2004 Foo Corporation
</div>

会被转换为：

<pre><code>
&lt;div class="footer"&gt;
    &amp;copy; 2004 Foo Corporation
&lt;/div&gt;
</code></pre>

Shell

不要在 shell 代码前加 $ 符号，除非你想要展示命令的输出。

解释：复制粘贴比较困难，不利于阅读。

建议使用:

1 2	echo a echo a > file

展示输出:

1
2
3

$ echo a
a
$ echo a > file

不建议：

1 2	$ echo a $ echo a > file

分割线

你可以在一行中用三个以上的 * 、 - 、 _ 来建立一个分隔线，行内不能有其他东西。你也可以在 * 或是 - 中间插入空格。下面每种写法都可以建立分隔线：

* * *

***

- - -

---

区段元素

链接

Markdown 支持两种形式的链接语法：行内式和参考式两种形式。

不管是哪一种，链接文字都是用 [] 来标记。

要建立一个行内式的链接，只要在 [] 后面紧接着 () 并插入网址链接即可，如果你还想要加上链接的 title 文字，只要在网址后面，用 "" 把 title 文字包起来即可，例如：

欢迎来到我的博客

1	欢迎来到[我的博客](https://zpp0196.me/ "zpp0196's Blog")

转换后的 HTML 代码：

1	<p>欢迎来到<a href="https://zpp0196.me/" title="zpp0196's Blog">我的博客</a></p>

如果你是要链接到该主机的资源，你可以使用相对路径：

公益404

1	[公益404](/404.html)

锚链接

直接使用 HTML 中的锚链接语法即可。

点击回到本节标题

1
2
3

## <a name="锚链接">锚链接</a>

<a href="#锚链接">点击回到本节标题</a>

强调

Markdown 使用 * 和 _ 作为标记强调字词的符号，被 * 或 _ 包围的字词会被转成用 <em> 标签包围，用两个 * 或 _ 包起来的话，则会被转成 <strong> ，例如：

single asterisks

single underscores

double asterisks

double underscores

*single asterisks*

_single underscores_

**double asterisks**

__double underscores__

转换后的 HTML 代码：

<em>single asterisks</em>

<em>single underscores</em>

<strong>double asterisks</strong>

<strong>double underscores</strong>

你可以随便用你喜欢的样式，唯一的限制是，你用什么符号开启标签，就要用什么符号结束。

强调也可以直接插在文字中间：

unfriggingbelievable

1	unfriggingbelievable

但是如果你的 * 和 _ 两边都有空白的话，它们就只会被当成普通的符号。

如果要在文字前后直接插入普通的 * 或 _ ，你可以用 \ ：

*this text is surrounded by literal asterisks*

1	\this text is surrounded by literal asterisks\

代码

如果要标记一小段行内代码，你可以用 ` 把它包起来，例如：

1	Use the `printf()` function.

转换后的 HTML 代码：

1	<p>Use the <code>printf()</code> function.</p>

如果要在代码区段内插入 `** ，你可以用至少 **n + 1** 个 **` 来开启和结束代码区段：

There is a literal backtick (`) here.

1	``There is a literal backtick (`) here.``

转换后的 HTML 代码：

1	<p><code>There is a literal backtick (`) here.</code></p>

在代码区段内， & 和 <> 都会被自动地转成 HTML 实体，这使得插入 HTML 原始码变得很容易，Markdown 会把下面这段：

1	Please don't use any `<blink>` tags.

转换为：

1	<p>Please don't use any <code><blink></code> tags.</p>

你也可以这样写：

1	`—` is the decimal-encoded equivalent of `—`.

转换后的 HTML 代码：

1	<p><code>&#8212;</code> is the decimal-encoded equivalent of <code>&mdash;</code>.</p>

图片

Markdown 使用一种和链接很相似的语法来标记图片，同样也允许两种样式：行内式和参考式。

行内式的图片语法看起来像是：

Bing 每日一图

1
2
3

![Bing 每日一图](http://api.dujin.org/bing/1920.php)

![Bing 每日一图](http://api.dujin.org/bing/1920.php "Bing 每日一图")

详细格式如下：

前面一个 !。
接着一对 []，里面放上图片的替代文字。
接着一对 ()，里面放上图片的网址，最后还可以用引号包住并加上选择性的 title 文字。

到目前为止，Markdown 还没有办法指定图片的宽高，如果你需要的话，你可以使用 HTML 中的 <img> 标签。

其他

自动链接

Markdown 支持以比较简短的自动链接形式来处理网址和电子邮件信箱，只要是用 <> 方括号包起来， Markdown 就会自动把它转成链接。一般网址的链接文字就和链接地址一样，例如：

https://zpp0196.me

1	<https://zpp0196.me>

转换后的 HTML 代码：

1	<a href="https://zpp0196.me">https://zpp0196.me</a>

邮址的自动链接也很类似，只是 Markdown 会先做一个编码转换的过程，把文字字符转成 16 进位码的 HTML 实体，这样的格式可以糊弄一些不好的邮址收集机器人，例如：

1	<address@example.com>

转换后的 HTML 代码：

1	<a href="mailto:address@exa#109;ple.com">address@example.com</a>

在浏览器里面，这段字符串转码后的结果是 <a href="mailto:address@example.com">address@example.com</a> ，即一个可以点击的 address@example.com 链接。

（这种作法虽然可以糊弄不少的机器人，但并不能全部挡下来，不过总比什么都不做好些。不管怎样，公开你的信箱终究会引来广告信件的。）

反斜杠

Markdown 可以利用 \ 来插入一些在语法中有其它意义的符号，例如：如果你想要用 * 加在文字旁边的方式来做出强调效果（但不用 <em> 标签），你可以在 * 号的前面加上 \ ：

*literal asterisks*

1	\literal asterisks\

Markdown 支持以下这些符号前面加上 \ 来帮助插入普通的符号：

\ 反斜线
` 反引号
* 星号
_ 底线
# 井字号
+ 加号
- 减号
. 英文句点
! 惊叹号
() 括弧
[] 方括号
{} 花括号
| 仅在制作表格中有效

表格

姓名	性别	年龄
张三	男	24
李四	男	25

| 姓名 | 性别 | 年龄 |
| --- | --- | --- |
| 张三 | 男 | 24 |
| 李四 | 男 | 25 |

参考上面的格式自行修改，| 旁边的空格只是为了美观，可以没有，如果要在表格中显示 | 可以在前面加上转义字符 \ 。

Markwon 暂不支持表格内容居中显示，如果需要表格内容居中显示，将需要居中的内容按照这种格式写即可： <center>需要居中的内容</center> 。

下划线

带下划线的句子。

1	<u>带下划线的句子。</u>

如上，直接使用 HTML 的 <u> 标签就行了。

删除线

~~带删除线的句子。~~

1	~~带删除线的句子。~~

在需要删除的句子前后各加上两个 ~ 即可。

MiscStuff

Lorem ^superscript dolor _subscript amet, consectetuer adipiscing elit. Nullam dignissim convallis est. Quisque aliquam. cite. Nunc iaculis suscipit dui. Nam sit amet sem. Aliquam libero nisi, imperdiet at, tincidunt nec, gravida vehicula, nisl. Praesent mattis, massa quis luctus fermentum, turpis mi volutpat justo, eu volutpat enim diam eget metus. Maecenas ornare tortor. Donec sed tellus eget sapien fringilla nonummy. NBA Mauris a ante. Suspendisse quam sem, consequat at, commodo vitae, feugiat in, nunc. Morbi imperdiet augue quis tellus. AVE

Lorem <sup>superscript</sup> dolor <sub>subscript</sub> amet, consectetuer adipiscing elit. Nullam dignissim convallis est. Quisque aliquam. <cite>cite</cite>. Nunc iaculis suscipit dui. Nam sit amet sem. Aliquam libero nisi, imperdiet at, tincidunt nec, gravida vehicula, nisl. Praesent mattis, massa quis luctus fermentum, turpis mi volutpat justo, eu volutpat enim diam eget metus. Maecenas ornare tortor. Donec sed tellus eget sapien fringilla nonummy. <acronym title="National Basketball Association">NBA</acronym> Mauris a ante. Suspendisse quam sem, consequat at, commodo vitae, feugiat in, nunc. Morbi imperdiet augue quis tellus.  <abbr title="Avenue">AVE</abbr>

此段内容引用自jekyll-theme-next-demo。

编写规范

文件后缀必须使用 .md。
文件名必须必须使用小写，多个单词之间使用 - 分隔。
文件编码必须必须用 UTF-8。

文档标题应该这样写：

1 2	Markdown 编写规范 ==========================

章节标题必须必须以 ## 开始，而不是 #。
章节标题必须必须在 ## 后加一个空格，且后面没有 ##。
1
2
3
4
5
6
7
8
// bad
##章节 1

// bad
## 章节 1 ##

// good
## 章节 1

章节标题和内容间必须必须有一个空行。

// bad
## 章节 1
内容。
## 章节 2

// good
## 章节 1

内容。

## 章节 2

代码段的必须必须使用 Fenced code blocks 风格，如下所示：

```javascript
console.log(“”);
```

表格的写法应该应该参考 Organizing information with tables，如下所示：

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell

| Left-Aligned  | Center Aligned  | Right Aligned |
| :------------ |:---------------:| -----:|
| col 3 is      | some wordy text | $1600 |
| col 2 is      | centered        |   $12 |
| zebra stripes | are neat        |    $1 |

中英文混排应该采用如下规则：
- 英文和数字使用半角字符。
- 中文文字之间不加空格。
- 中文文字与英文、阿拉伯数字及 @ # $ % ^ & * . () 等符号之间加空格。
- 中文标点之间不加空格。
- 中文标点与前后字符（无论全角或半角）之间不加空格。
- 如果括号内有中文，则使用中文括号。
- 如果括号中的内容全部都是英文，则使用半角英文括号。
- 当半角符号 / 表示「或者」之意时，与前后的字符之间均不加空格
- 其它具体例子推荐阅读这里。
中文符号应该使用如下写法：
- 用直角引号 「」 代替双引号 “”，不同输入法的具体设置方法请参考这里。
- 省略号使用 …… ，而 。。。 仅用于表示停顿。
- 其它可以参考知乎规范。
表达方式，应当遵循《The Element of Style》：
- 使段落成为文章的单元：一个段落只表达一个主题。
- 通常在每一段落开始要点题，在段落结尾要扣题。
- 使用主动语态。
- 陈述句中使用肯定说法。
- 删除不必要的词。
- 避免连续使用松散的句子。
- 使用相同的结构表达并列的意思。
- 将相关的词放在一起。
- 在总结中，要用同一种时态（这里指英文中的时态，中文不适用，所以可以不理会）。
- 将强调的词放在句末。

参考文档：《Google Markdown style guide》。

区块元素

标题

区块引用

列表

代码块

Shell

分割线

区段元素

链接

锚链接

强调

代码

图片

其他

自动链接

反斜杠

表格

下划线

删除线

MiscStuff

编写规范

参考资料