Markdown文档书写建议

转变你的思维

从以往的word、记事本做笔记，到现在的Markdown，你需要做一些思维的转变：

• 并没有增加你的工作量。使用Markdown来书写并不会增加你的工作量，你只需要记住一些标记，就可以不借助鼠标实现各种效果；相比之下，你书写文档的效率会更高
• 遵循一定的书写规则。知道语法≠能写好一篇文档。即使非常熟悉Markdown语法，也可能写出一篇“烂文档”。请尽可能按照下文建议的去书写，避免下文中禁止的内容。
• 大纲先行。写一篇文档，先写大纲，再填充内容；如果填充内容过程中发现缺漏，可以随时补充。改变想到哪里写到哪里的坏习惯（随笔除外）。

基本规则

• 遵循Markdown书写规则。Markdown的语法在不同的编辑器会有不同的效果，尽量遵循标准的语法。
• 编辑状态下的行文也要规范。确保在没有渲染的情况下依然能正常阅读
• 采用“论点+解释”的模式。段落内容尽量以“论点”开头，后面是对这个论点的解释。避免随心所欲地书写流水账，总结和梳理后再写，不要说一大段没有核心的话。（如果你不能把一段话提炼为一句10个字以内短话，一般来说这段话会让别人很难理解）

段落

文章标题不要在编辑区写

文章标题不要在编辑区写，这样既避免了重复写标题，又减少了标题的层级

正例：

反例：

各级标题与正文内容空一行

各级标题与正文内容不要粘在一起，有些渲染Markdown的工具会把正文当成标题渲染。也不要空太多行，这样会把正文和标题隔离，不便于编辑状态时的阅读。

正例：

# 一级标题
(这里空一行)
正文内容正文内容正文内容正文内容正文内容

反例：

# 一级标题
正文内容正文内容正文内容正文内容正文内容

每一节与上一节之间至少空一行

这里说的“节”，包括 # 一级标题 ## 二级标题 等全部层级。建议一级标题与上一节内容空出2行以上，便于自己修改。此外，在无Markdown渲染的情况下也能很准确地阅读。

正例：

# 一级标题1

正文内容正文内容正文内容正文内容正文内容正文内容

(这里空了3行)

# 一级标题2

正文内容正文内容正文内容正文内容正文内容正文内容

反例：

# 一级标题1

正文内容正文内容正文内容正文内容正文内容正文内容
# 一级标题2

正文内容正文内容正文内容正文内容正文内容正文内容

同一节内容中，如果不想再分小节，可用分割线划分

同一节内容中，如果不想再分小节，可用分割线 --- 划分。

正例：

# 一级标题1

正文内容1,正文内容1,正文内容1,正文内容1,正文内容1,正文内容1,正文内容1

---

正文内容2,正文内容2,正文内容2,正文内容2,正文内容2,正文内容2,正文内容2

代码块、分割线、引用等要与上下文各空一行

代码块 ```、分割线 ---、引用 > 要和上下文内容各空一行，不要粘在一起。

正例：

` ` `c
int a = 0;
` ` `

正文内容正文内容正文内容正文内容正文内容正文内容

---

正文内容正文内容正文内容正文内容正文内容正文内容

> 引用内容引用内容引用内容引用内容引用内容引用内容

上面示例中，代码库的标记 ``` 中间带了空格，是因为无法在Markdown的代码快中直接使用连续的 ```，实际使用时不需要加空格。

标记

代码块必须标记

代码块不允许直接暴露在文档中，尤其是C语言的一些代码包含 #include 内容的，会直接被当作一级标题进行渲染。此外，将代码块包裹在 ``` 标记中，可读性更好。

正例：

以下是代码块：

` ` `c
#include 
#define PI 3.14

int main() {
    // ...
}
` ` `

反例：

以下是代码块：

#include 
#define PI 3.14

int main() {
    // ...
}

反例的后果：

数值或常量、变量名要标记

这个不是必须的，但建议把一些常量、变量或数值用 ` 标记包裹。

正例：

我们可以定义 `PI` 为 `3.14` 或 `3.14159` 等值

标记后的效果：

一些标记前后要加空格

用 ` 标记包裹的内容，前后要空一格。如果前面是标点符号，则不需要在前面加空格；同理，后面如果是标点符号，也不需要在后面加空格。

正例：

前后文要加空格：我们可以定义 `PI` 为 `3.14` 或 `3.14159` 等值
前面可以不加空格：我们知道，`PI` 是圆周率的缩写
后面可以不加空格：它的值是 `3.1415926....`。

反例：

我们可以定义`PI`为`3.14`或`3.14159`等值

---

各级标题的 # 后面要加一个空格

正例：

# 一级标题
## 二级标题
### 三级标题

反例：

#一级标题
##二级标题
###三级标题

突出论点

一些段落、列表中，如果采用“论点+内容”的模式，可以把论点加粗，突出重点（非必须）。必要的话甚至可以换行，让论点单独一行。

正例：

自然段落

**我是论点**。下面是对论点的解释和说明。下面是对论点的解释和说明。下面是对论点的解释和说明。下面是对论点的解释和说明。下面是对论点的解释和说明。

**我是论点**。
下面是对论点的解释和说明。下面是对论点的解释和说明。下面是对论点的解释和说明。下面是对论点的解释和说明。下面是对论点的解释和说明。

---

列表

- **我的论点1**。下面是对论点的解释和说明。下面是对论点的解释和说明。下面是对论点的解释和说明。下面是对论点的解释和说明。下面是对论点的解释和说明。
- **我的论点2**。下面是对论点的解释和说明。下面是对论点的解释和说明。下面是对论点的解释和说明。下面是对论点的解释和说明。下面是对论点的解释和说明。

- **我的论点1**。
下面是对论点的解释和说明。下面是对论点的解释和说明。下面是对论点的解释和说明。下面是对论点的解释和说明。下面是对论点的解释和说明。
- **我的论点2**。
下面是对论点的解释和说明。下面是对论点的解释和说明。下面是对论点的解释和说明。下面是对论点的解释和说明。下面是对论点的解释和说明。

效果对比截图：