Paul

Markdown 书写建议

虽然目前编辑器对 Markdown 的支持存在很大差异，方言现象严重，但是对于 Markdown 基础语法的支持都是相似的。

针对 Markdown 基础语法产生的差异大部分是在区块相接、嵌套和 Lazy 输入时产生的。所以养成一个良好的书写习惯可以规避掉大部分兼容性问题。

下面提供一些 Markdown 书写的建议，遵循这些建议会让你的 Markdown 文档更加易读，出现更少的语法歧义，同时也会具备更高的兼容性。

书写高兼容性的 Markdown 文档应该遵循以下两个原则：

• 清晰原则。清晰是 Markdown 文档“易读性”的体现，如果一份 Markdown 文档让人读起来都可能有语法歧义，那么对于机器来说，也很容易产生兼容性问题。清晰原则具体表现为区块间有明确的区分、行内元素有明确的范围、避免使用歧义语法、避免使用 Lazy 输入等方面。

• 简单原则。Markdown 本身只是轻量级的标记语言，使用过度复杂的功能、画蛇添足的输入内容，都会产生兼容性问题。简单原则具体表现为避免不被公认的偏僻功能、避免不不要的输入、尽量少用嵌套、范围行内元素避免嵌套等方面。

范围元素

这里所说的范围元素指采用行内元素中标识包裹的语法元素，包括强调、重强调、删除线、行内代码和下划线 HTML 标签。

• 范围元素不能超出所在的区块，最好不超出所在行，表格内的不能超出单元格。

  虽然目前部分编辑器很智能，允许跨行甚至跨区块使用，但是并不提倡这么使用，容易导致意想不到的结果。既然是行内元素，那么就最好让它在一行内结束。

  不能跨区块很好理解，为什么不提倡跨行呢？一般的跨行使用是没有问题的，但是如果跨行使用行内代码，有的编辑器会变成同一行。另外跨行扩大了范围，再添加范围元素时容易出现范围元素的嵌套或交叉。最重要的原因是当我们实际书写时，很多时候我们是不能很好的区分到底应该使用多个文本行还是多个段落，当我们需要在文本行间添加空行转化为段落时，跨行的范围元素就会变成跨区块而失效。

• 范围元素尽量避免使用交叉，少用嵌套。

  交叉不应该使用，因为太容易出现错误，而且目前很多编辑器支持不好，更重要的原因是交叉违背了 Markdown 的易读特性，不符合清晰原则。

  尽量少用嵌套也是因为可以让文档更清晰更简单。但是在实际的书写过程中，使用嵌套的几率是很高的。如果使用嵌套，特别是很多个范围元素作用于同一段文本时，需要注意让元素标识两侧对称。

• 除了行内代码之外的范围元素，书写时标识内侧应该紧贴文字，避免紧贴空格或特殊符号。紧贴文字之后易读性更高，也更符合 Markdown 的理念。

  内侧避免紧贴符号：123,**456**,789，不推荐：123**,456,**789。

  内侧避免紧贴空格：test *span* elements，不推荐：test* span *elements。

强调和重强调

强调默认是斜体，重强调默认是粗体。

为什么不直接叫斜体或粗体呢？因为强调和重强调的语法在 HTML 中输出就是 <em> 和 <strong> 标签，而不是直接表示斜体的 <i> 和粗体 <b> 标签，只不过 <em> 和 <strong> 标签默认对应斜体和粗体。

它们看似没有区别，但是在本质上有很大的区别。就好比在 Word 中使用样式添加标题，和直接对文字进行加粗并放大字号的区别一样。

强调不是一个具体的添加格式，它的格式是可以改变的，不一定非要是斜体。只是目前大部分编辑器都是直接把强调理解为斜体，这就感觉有些掉价了。这也是非常可惜的做法，尤其是在中文领域。

强调有两种书写方式：一对 * 或 _ 包裹。重强调也有两种书写方式：一对 ** 或 __ 包裹。

无论强调还是重强调，都建议只使用星号，不建议使用下划线：

• 有些编辑器会把 _ 作为添加下划线的语法，而不是强调的语法。
• 在计算机领域常使用 _ 作为连字符或代替空格。部分 Markdown 语法规定两个字母间的 _ 不被识别为强调。
• 中文状态下，无法直接输入 _，需要切换成英文才能输入。

自动链接

链接的书写方式有三种：行内式、参考式和自动链接。

其中，自动链接是一种快速添加方式，只要用 <> 包裹即可。而有些编辑器的 Lazy 输入允许不用尖括号包裹，可以直接输入链接，请记得在后面加一个空格以防万一。

建议使用自动链接时用尖括号包裹，如 <https://www.baidu.com>，因为很多编辑器不一定能自动识别链接。

这三种链接书写方式建议使用行内式。当然，如果掌握熟练的话，随意使用。

行首空格

行首的空格（包括 Tab）主要的功能是用于缩进式区块代码、列表嵌套等。

原生 Markdown 允许在每一行行首任意输入 0~3 个空格，不会影响最终输出。其原意是让用户可以根据需要使用行首空格对源码进行对齐，增加易读性。

但是在 Markdown 语法百花齐放的今天，使用这种方式输入是很危险的，而且现在的编辑器都非常智能，基本不存在易读性问题。所以建议只在缩进式代码和列表嵌套时使用行首空格。

有的教程说可以在段落行首添加 2 个空格进行缩进，更好看。除非对 Markdown 非常熟练，否则不建议随意添加。

空行

空行的作用主要是用于区块元素的连接。这里的建议是除了标题后接区块时可以不加空行以外，所有区块都使用一个空行区分。因为目前还没有一款编辑器要求标题后接区块必须添加空行。而且目前大部分编辑器都会把文档中的标题着重突出，也不存在易读性问题，所以标题后面的空行是可有可无的。

至于其他区块，都用空行区分，就可以大大增加文档的可读性了。而且，这样也不必去记忆到底哪些区块相接需要空行，哪些不需要。多敲一个空行也不是什么难事，这样做即符合清晰原则又符合简单原则。

一般使用一个空行就够了，多了虽然不会影响最后的输出，但是会让源码间隔过宽不利于源码的阅读。

标题

标题有两种书写方式：一种 Setext 标题，采用 = 或 - 作为底线；一种 Atx 标题，采用行首 #。

建议使用 Atx 标题。它比 Setext 标题有太多优势：

• Atx 标题支持 6 阶标题，而 Setext 只支持 2 阶标题；
• Atx 标题只占用一行，而 Setext 标题占用多行；
• 次阶 Setext 标题与分割线一样使用三个 - 作为语法，容易造成语法错误。

总之，Setext 标题不稳定、容易出错、功能也单一，所以只推荐使用 Atx 标题。使用 Atx 标题唯一需要注意的是，井号后面加一个空格，这是标准的 Markdown 书写方式。

区块代码

区块代码有两种书写方式：缩进式和围栏式。建议使用围栏式区块代码，它比缩进式代码有太多优势：

• 围栏式代码有明确的的开始和结束标识，而缩进式采用的 Tab 不是明确的开始标识；
• 围栏式代码可以代码种类并高亮语法，而缩进式不能；
• 缩进式代码与嵌套列表一样使用 Tab 作为语法，容易出现错误。

分割线

分割线的写法有三种：三个或以上的 _、* 或 -。建议使用三个星号书写分割线，因为这样最安全、也最方便：

• 下划线需要切换英文才能输入，星号更方便直接；
• 减号与次阶 Setext 标题共用一个语法，不够安全。

如果想使用减号写分割线，可以在减号前预留空行，这样会更安全。

区块引用

区块引用的书写其实很简单，因为最多就是嵌套一下段落之类的，出错率很低。建议不要使用 Lazy 输入，老老实实在每一行的行首输入 >。

> 后面可接空格，也可不接，建议还是接一个空格，因为这样更好看，而且可以与列表、Atx 标题等语法对齐，减少记忆负担。

列表

与区块引用一样，请避免使用 Lazy 输入，因为列表太容易出问题。

项目表示后需要接空格，同时应该尽量少用列表嵌套。如果列表需要包含很多内容，可以多使用标题。

对于有序列表，建议从数字 1 开始，虽然后的语法允许用户自定义开始的数字，但是一般用不到。

对于无序列表，项目标识可以用 *、+ 或 - 三种方式。首选使用减号，因为减号可以直接输入，非常方便。

另外还有一个建议：同一个列表中，同一级的项目使用同一个项目标识，不同级的列表用不同标识，这样效果更好。

- 一级列表
  + 二级列表
    * 三级列表
- 一级列表
  + 二级列表
    * 三级列表
- 一级列表
  + 二级列表
    * 三级列表

尽量不要使用不同符号写同一级列表，因为有的语法规定，用不同的项目符号会生成全新的列表，而且易读性差，也不符合清晰原则。

总结

• 范围元素不超出行，表格内的不超出单元格。
• 范围元素不交叉，少嵌套。如果嵌套，记得两侧标识要对称。
• 除行内代码之外的范围元素应紧贴文字。
• 不使用 Lazy 输入。
• 除了标题后可以不接空行，所有区块使用空行区分。
• 只在缩进式代码与列表嵌套时使用行首缩进。
• 标题首选 Atx 式。
• 区块代码首选围栏式。
• 分隔线首选使用星号。
• 有序列表建议从 1 开始写。
• 无序列表的项目符号首选减号。
• 同一级的无序列表使用同一个项目符号。