本文档主要讲述了 Markdown 作为富文本基础格式的时候编写专业文档时应当采取的格式， 读者应当具备一些基础的 Markdown 知识，了解 Markdown 各种内嵌样式和块状样式的用法和区别。 关于 Markdown 文档的详细规范，可以参考 CommonMark 规范。 中文文本的排版格式，参考 GitHub《中文文案排版指北》。
[TOC]
本指南主要有以下几个目标：
- 一致性：保证在遵循 CommonMark 标准的同时，使用更严格的规范来统一风格，避免因为风格导致的奇异解读；
- 可读性：在源码模式下依然能够正确地掌握和理解文档的结构，清晰阅读文档的内容；
- 易理解：通过控制内容的结构和颗粒度，让读者更容易理解和掌握文档的信息。
通常来说标准的文档结构如下：
# 标题
简介
[TOC]
## 分节
分节内容。
## 参考
- https://example.com# 标题对于有额外标题区域的文档（如微信公众号等），标题部分在正文内容中可以省略[TOC]如果使用的文档平台支持自动生成目录，那 [TOC] 节最好加上## 分节所有除文档标题外的分节标题都应该从 2 级标题开始，每一级的子分节只能有一层标题递增## 参考参考区域可以作为给读者获取更多信息的指导内容，放置一些相关的备注和链接。
Markdown 文档对换行符不敏感，对于非连续换行，会尝试通过尾部字符（英文句号）来决定是否拆分段落。 所以尽可能按照项目源码规范（比如 80 字符一行）来选择拆行，这样既不失文档的标准性， 又能在非渲染模式下可以正常阅读。
字符数较长的 URL 链接和表格除外。
要这样做：
你可以这样来安排一个段落，
其实看起来不会差太远。
但是如果有一个[占据空间非常大非常长的链接](https://https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md)。
就让他保持那么长吧。尽量不要在尾部加两个空格来进行换行。 大部分行尾的空格会被一些编辑器给忽略掉，造成不必要的麻烦。 如果需要切分段落，通过额外一个空行来实现。
要这样做：
这是第一段。
这是第一段的第二句。
这是第二段。跟第一段之间记得空一行。Markdown 虽然支持===和---来表示一级标题和二级标题，但因为其区分比较让人迷惑
（你第一反应是---是一级标题还是二级标题？），并且丢失了跟其他层级标题的一致性。
要这样做：
## 这样才是一个标准的标题不要这样做：
别这样做，因为你很难确定这是第几层标题
----#之后要添加一个空格，标题前后各空一行。
#前不要添加空格。
空白能够更加突出标题，提升文档源码的可读性。
要这样做：
## 标题
段落
## 另一个标题，跟前面要空一行
另一个段落，跟标题之间要空一行。不要这样做：
## 标题前面多出来个空格
##内容跟标题之间挨得紧密，中间也没留空白
内容紧接着标题。标题尾部不要出现任何类似句号或者冒号的标点。标题会作为目录的一部分，目录中出现尾部标点会显得十分的滑稽。
要这样做：
## 参考
- [参考链接](https://example.com)不要这样做：
## 参考：
## 这是下文的一个主要观点。如果列表项内容需要多句话描述完，考虑拆分成更深一级的子分节来表示。
通常一个列表不要超过 4 项。除非内容主题就是列举项目（比如购物清单等），否则请尝试其他展示形式（比如图表、流程等）。
不要这样做：
1. xxx
2. yyy
...
19. zzz顶层列表的引导符号要顶行书写。 在列表引导符号后添加一个空格。 次一级的内嵌列表，引导符号与前一级的内容对齐，保证层次感。
要这样做：
- 第一层
- 第二层
- 第三层
- 回到第二层
1. 有序列表也是这样
1. 看起来会更清晰
1. 层级明确并且不会导致缩进混乱。不要这样做：
- 第一层符号前面空了几格
- 下一层紧挨着上一层
- 再下一层多缩进了了几格如果列表项内容超出了一句话，尽量通过简短的摘要或总结在列表项之前突出重点。
> 与引用内容之间使用一个空格分隔，>之前不能有空格。
引用内容的每一行都要使用>，包括空行。
引用应该是作为正文的补充说明引入，不应该有太多的内容。如果引用内容超过了半屏显示，容易中断读者关注正文的上下文。这种时候尽量把引用通过链接的方式引入。
要这样做：
> 学医救不了中国人。
>
> —— 鲁迅不要这样做：
> 空格打头，
>与内容之间没有间隔，
> 与内容之间间隔太多，
> 跳过了一个空行。
> —— 鲁迅代码块与上下文之间要有空行间隔。
使用隔离式代码块(```)时，尽量加上语言标签。
要这样做：
参考以下代码（fenced）
```javascript
console.log("hello world")
```
或者（indented）
console.log("hello world")
都可以得出结果。
内联元素之间尽量不要存在内部边界空格。
要这样做：
**加粗字体**
_倾斜字体_
[链接](http://example.com)
`代码元素`不要这样做：
** 加粗字体 **
_ 倾斜字体 _
[ 链接 ]( http://example.com )
` 代码元素 `**加粗字体**信息主要用来强调，突出显示主要的信息，比如句子中的关键字，或者是列表项突出的重点信息；_倾斜字体_用来区分文本内有相关性的部分内容，比如英文书籍名，或者是其他相关引用；`代码元素`用于文档中的一些符号信息，比如代码片段等。
隐式链接一定要保留尾部的空[]块。
要这样做：
[link-to-something][]不要这样做：
[link-to-something]引用式链接的定义列表，一定要放在文档的最底部，作为引用和参考链接存在。 引用式链接的 URL 不要使用尖括号包括起来。 链接 ID 尽量使用小写字母。并按照字母序排序。
链接的标题要使用双引号来包括。
要这样做：
[link](https://example.com "链接")
[another-link][1]
[1]: https://example.com "另一个链接"只是给出一个“这里”或者“链接”这样的词语，很难给读者传达你想要描述的内容。
要这样做：
你可以参考[CommonMark 标准文档](https://commonmark.org/)来了解更多内容。不要这样做：
点击[这里](https://example.com)获取更多相关信息。