Markdown系列（5）- Markdown书写建议

Markdown书写建议

---

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

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

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

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

• 清晰原则。清晰是Markdown文档“易读性”的体现，如果一份Markdown文档让人读起来都可能有语法歧义，那么对于机器来说，也很容易产生兼容性问题。清晰原则具体表现为区块间有明确的区分、行内元素有明确的范围、避免使用歧义语法、避免使用Lazy输入等方面。
• **简单原则。**Markdown本身只是轻量级的标记语言，使用过度复杂的功能、画蛇添足式的输入内容，都会产生兼容性问题。简单原则具体表现为避免使用不被公认的偏僻功能、避免不不要的输入、尽量少用嵌套、范围行内元素避免嵌套等方面。一言以蔽之——No Zuo No Die。

---

范围元素的书写建议

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

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

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

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

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

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

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

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

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

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

---

强调和重强调的书写建议

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

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

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

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

强调有两种书写方式：一个星号*或下划线_包裹。

重强调也有两种书写方式：两个星号**或下划线__包裹。

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

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

---

自动链接的书写建议

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

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

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

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

---

行首空格的使用建议

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

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

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

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

---

空行的使用建议

空行的作用主要是用于区块元素的链接，关于区块的相接问题，在之前的《你不知道的Markdown基础知识》这篇文章里已经讲过。这里的建议是除了标题后接区块时可以不加空行以外，所有区块都建议使用一个空行区分。因为目前还没有一款编辑器会去要求标题后接区块必须添加空行。而且目前大部分编辑器都会把文档中的标题这种突出，也不存在易读性问题，所以标题后面的空行是可有可无的。

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

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

---

标题的书写建议

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

Atx标题比Setext标题有太多优势：

1. Atx标题支持6阶标题，而Setext只支持2阶标题；
2. Atx标题只占用一行，而Setext标题占用多行；
3. 次阶Setext标题语法与分割线共用三个减号—作为语法，容易造成语法错误。

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

---

区块代码的书写建议

区块代码有两种书写方式：缩进式和围栏式。建议使用围栏式区块代码。

围栏式代码比缩进式代码有太多优势：

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

---

分割线的书写建议

分割线的写法有三种：三个或以上的_、*或-。

建议使用三个星号书写分割线，因为这样最安全、也最方便：

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

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

---

区块引用的书写建议

区块引用的书写其实很简单，因为最多就是嵌套一下段落之类的，出错率很低。

建议不要使用Lazy输入，老老实实在每一行敲>号。>号后面可接空格，也可不接，建议还是接一个空格，因为这样更好看，而且可以与列表、Atx标题等语法齐平，减少记忆负担。

---

列表的书写建议

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

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

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

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

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

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

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

---

Markdown书写建议汇总

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