Markdown文档书写建议
2019-12-21 本文已影响0人
Mike的读书季
转变你的思维
从以往的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 <stdio.h>
#define PI 3.14
int main() {
// ...
}
` ` `
反例：
以下是代码块：
#include <stdio.h>
#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**。
下面是对论点的解释和说明。下面是对论点的解释和说明。下面是对论点的解释和说明。下面是对论点的解释和说明。下面是对论点的解释和说明。
效果对比截图：
