鸭梨公共文档

主题

2. MarkDown 编写规范 ​

1. 文件约束 ​

  1. 文本编码：全部使用 UTF-8 编码。
  2. 文件名：首选使用 kebab-case 命名法（即只使用小写字母或数字，并使用 - 连接单词），禁止使用拼音命名。

2. 文本约束 ​

  1. 如果有 元数据（Front Matter），则应该使用三个连字符（---）包裹，使用标准的 YAML 语法并尽可能简洁。
  2. 如果有文本摘要，文本摘要需要在 <!-- more --> 注释的上方，在主标题的下方，各自之间都有空行。
  3. 标题的上下留有空行，一级标题上可以没有空行，一篇文章有且只有一个一级标题（主标题）。
  4. 段落之间留有 1 个空行，段落中遇到应该使用空格的地方可以用换行代替，其他地方不要换行。

    这里建议不要换行，编辑器会帮助你换行，而 MarkDown 常常被渲染成网页，也不需要手动换行。

  5. 中文和英文、中文和数字、中文和公式、代码字体和正文之间要空格，除非在标点符号旁边。

    如 code 而不是code连在一起，数字 123 万而不是123万。

  6. 英文的逗号和点的前面没有空格，后面需要加空格，其他语言遵循对应语言规范，在书写中文时不要随意加空格。

    This is a sentence, and this is another sentence.

  7. 加粗、斜体、下划线或删除线的内容，可以与前后文本留有空格，链接也可以在前后加上空格，不强制。
  8. 表达专有名词时，需要使用此名词的广泛称呼，一般是首字母大写的标题形式。

    例如 Java、Python、MySQL、Rust、HTML、CSS、JavaScript、Vue、MyBatis、Spring、Spring Boot、WiFi、Windows、Mac OS X、npm、apt、pip 是标准写法。

3. 样式约束 ​

  1. 首选 markdownlint 提供的样式约束，可以在 IDE 中安装插件来提供支持。
  2. 在正文中建议使用 2 个空格或 4 个空格缩进，这样能兼容性最多的编辑器，而代码块和元数据可以按照习惯缩进。
  3. 不宜过度渲染和标注。

    反例：大量使用 加粗、斜体、删除线 来强调某一段内容，大量使用 代码字体 表达专有名词，如 Java、Python。

  4. 不要在列表元素上嵌套过深，列表元素应该简短、紧凑。

    反例：

    • 1
      • 1.1
        • 1.1.1
          • 1.1.1.1

4. 代码块 ​

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

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

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

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

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

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

markdown
## 这是 MarkDown 语法

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

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

1(ϕ5−ϕ)e25π=1+e−2π1+e−4π1+e−6π1+e−8π1+⋯\frac{1}{\Bigl(\sqrt{\phi\sqrt{5}} - \phi\Bigr) \mathrm{e}^{\frac{2}{5} \pi}} = 1 + \frac{\mathrm{e}^{-2\pi}}{ 1 + \frac{\mathrm{e}^{-4\pi}}{ 1 + \frac{\mathrm{e}^{-6\pi}}{ 1 + \frac{\mathrm{e}^{-8\pi}}{1 + \cdots} } } }

5. 公式 ​

  1. 公式推荐使用 KaTeX 提供的语法，更快且兼容性更好，可以使用 VS Code 插件 MarkDown All in One 来提供语法支持。
  2. 行内公式使用 $ 包裹，公式内靠近 $ 的地方不能有空格

    例如 $x$ 是正确写法，而 $ x $ 是错误的写法。

  3. 行间公式的范围符号 $$ 单独占一行，且公式上下有空行。
  4. 公式在适当位置换行并使用空格、对其等方式使得公式更易读。空格的添加方式遵循代码中运算符的空格添加规范。
  5. 公式内的 , 后边建议给出空格符号（可以使用 \\ 或者 \,），以便于阅读。
latex
$$
\begin{aligned}
  x_{1,\,2} = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
\end{aligned}
$$

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

latex
$$
\frac{1}{\Bigl(\sqrt{\phi\sqrt{5}} - \phi\Bigr) \mathrm{e}^{\frac{2}{5} \pi}} =
  1 + \frac{\mathrm{e}^{-2\pi}}{
    1 + \frac{\mathrm{e}^{-4\pi}}{
      1 + \frac{\mathrm{e}^{-6\pi}}{
        1 + \frac{\mathrm{e}^{-8\pi}}{1 + \cdots}
      }
    }
  }
$$

1(ϕ5−ϕ)e25π=1+e−2π1+e−4π1+e−6π1+e−8π1+⋯\frac{1}{\Bigl(\sqrt{\phi\sqrt{5}} - \phi\Bigr) \mathrm{e}^{\frac{2}{5} \pi}} = 1 + \frac{\mathrm{e}^{-2\pi}}{ 1 + \frac{\mathrm{e}^{-4\pi}}{ 1 + \frac{\mathrm{e}^{-6\pi}}{ 1 + \frac{\mathrm{e}^{-8\pi}}{1 + \cdots} } } }

参考 LaTeX 数学符号指南 来输入特殊符号。

6. GFM 使用 ​

请优先遵循 GFM（GitHub Flavored MarkDown）的规范和语法，以便于在更多平台上受到支持。具体内容请参见 GFM 中文文档。

例如警告容器：

容器示例

注释

注释文字

重要

重要文字

提示

提示文字

注意

注意文字

警告

警告文字

md
> [!NOTE] 注释
> 注释文字

-------

> [!IMPORTANT] 重要
> 重要文字
-------

> [!TIP] 提示
> 提示文字
-------

> [!WARNING] 注意
> 注意文字
-------

> [!CAUTION] 警告
> 警告文字