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 <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**。
下面是对论点的解释和说明。下面是对论点的解释和说明。下面是对论点的解释和说明。下面是对论点的解释和说明。下面是对论点的解释和说明。

效果对比截图:


推荐阅读更多精彩内容

  • 阿里巴巴 JAVA 开发手册 1 / 32 Java 开发手册 版本号 制定团队 更新日期 备 注 1.0.0 阿...
    糖宝_d864阅读 2,656评论 0 4
  • 一、编程规约 (一)命名规约 【强制】 代码中的命名均不能以下划线或美元符号开始,也不能以下划线或美元符号结束。反...
    喝咖啡的蚂蚁阅读 694评论 0 1
  • Markdown概述 宗旨 Markdown 的目标是实现「易读易写」。Markdown 的特点就是,让写作变得更...
    心疼你萌萌哒阅读 5,314评论 1 22
  • 命名风格 【强制】代码中的命名均不能以下划线或美元符号开始,也不能以下划线或美元符号结束 【强制】代码中的命名严禁...
    云A00000阅读 1,649评论 0 0
  • 2019年投资哪个项目能赚钱 友鸭连锁轻松当老板 2019有哪些值得投资的品牌!创业选项目是很重要的一个环节,也可...
    youya222阅读 13评论 0 1