鸭梨写作规范

Alex Sun大约 3 分钟

鸭梨定义的 Markdown 文本写作规范。

1. 基本规范

如果有元数据（Front Matter），则应该使用三个连字符（---）包裹，使用标准的 YAML 语法并尽可能简洁。
文本摘要在  段落的上方，在元数据的下方，各自之间都有空行。
标题的上下留有空行，一级标题上可以没有空行，一篇文章只有一个一级标题。
段落之间留有一个空行，段落中遇到应该使用空格的地方可以用换行代替，其他地方不要换行。
这里建议不要换行，编辑器会帮助你换行，而 MarkDown 常常被渲染成网页，也不需要手动换行。
中文和英文、中文和数字、中文和公式、代码字体和其他部分之间要空格，除非在标点符号旁边。
英文的逗号后加空格，其他语言遵循对应语言规范，中文中不要随意加空格。
加粗、斜体、下划线或删除线的内容，可以与前后文本留有空格，链接也可以在前后加上空格，不强制。

代码块上下必须留有空行，且代码块全部使用反引号（```）来约束。不应该使用缩进表达代码，这会导致不正确的空格数量。

如果一个代码块中的所有代码都被缩进了指定长度，则应该将此缩进去掉，以便于阅读。例如：

// 这里的代码块缩进了 2 个空格
for (let i = 0; i < 10; i++) {
  console.log(i);
}

// 这是从一个 JS 文件中复制来的
// 它有不正确的缩进，应该去掉 6 个空格的缩进
      for (let i = 0; i < 10; i++) {
        console.log(i);
      }

尽可能给代码块标记语言，以便于编辑器高亮显示或用户识别，避免使用编辑器提供的自动识别语言。

语言标记尽量写全称，而不是简写，这样可以兼容大多数编辑器。例如 Python 不应该写作 py，而应该写作 python。但是也有例外，必须常用的 js、ts 也可以被多数编辑器支持。

如果代码块又需要包含三个反引号（即嵌套 MarkDown 语法的代码块），使用四个反引号（````）来约束。

我们常常需要表达 MarkDown 自己的语法，使用四个反引号包裹三个反引号吧！

```python
for i in range(10):
    print(i)
```

$$
\begin{aligned}
  x_{1,\,2} = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
\end{aligned}
$$

\begin{aligned} x_{1,\,2} = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a} \end{aligned}

公式内的 , 后边建议给出空格符号（可以使用 \\ 或者 \,），以便于阅读。