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

效果对比截图:


©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 118,170评论 1 238
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 51,474评论 1 200
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 73,398评论 0 167
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 36,051评论 0 127
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 42,849评论 1 205
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 35,584评论 1 124
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 27,553评论 2 206
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 26,693评论 0 119
  • 想象着我的养父在大火中拼命挣扎,窒息,最后皮肤化为焦炭。我心中就已经是抑制不住地欢快,这就叫做以其人之道,还治其人...
    爱写小说的胖达阅读 25,658评论 5 172
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 29,717评论 0 178
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 26,965评论 1 167
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 28,219评论 1 177
  • 白月光回国,霸总把我这个替身辞退。还一脸阴沉的警告我。[不要出现在思思面前, 不然我有一百种方法让你生不如死。]我...
    爱写小说的胖达阅读 22,537评论 0 25
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 25,126评论 2 163
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 28,968评论 3 172
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 23,960评论 0 4
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 24,029评论 0 113
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 30,163评论 2 188
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 30,592评论 2 188

推荐阅读更多精彩内容

  • 阿里巴巴 JAVA 开发手册 1 / 32 Java 开发手册 版本号 制定团队 更新日期 备 注 1.0.0 阿...
    糖宝_阅读 7,173评论 0 5
  • 一、编程规约 (一)命名规约 【强制】 代码中的命名均不能以下划线或美元符号开始,也不能以下划线或美元符号结束。反...
    喝咖啡的蚂蚁阅读 1,405评论 0 2
  • Markdown概述 宗旨 Markdown 的目标是实现「易读易写」。Markdown 的特点就是,让写作变得更...
    心疼你萌萌哒阅读 7,226评论 1 24
  • 命名风格 【强制】代码中的命名均不能以下划线或美元符号开始,也不能以下划线或美元符号结束 【强制】代码中的命名严禁...
    云A00000阅读 3,292评论 0 0
  • 周末清晨7时,我们一行8人驾车前往五堡“魔鬼城”,全程100余公里。一路上我向朋友讲述着早年畅游“魔鬼城”的感受和...
    瑨瑀轩馬永紅阅读 518评论 7 6