基于 Markdown 的中文文档排版规范
文章首发于公众号“物联网学前班”，由于排版原因，不能非常好的展示，请阅读原文。
本篇文章先介绍 Markdown 的背景信息，然后着重介绍 Markdown 中文文档的排版规范，不介绍 Markdown 的入门使用。
0 前言
相信阅读本文的读者一定有被 Markdown 灵活的写作风格搞懵过，不知道怎么写更优雅、更规范，那么本文就是来帮您梳理 Markdown 写作过程中常见的一些问题，然后给出一个建议的应用规范。
通过阅读本文，相信你一定可以基于 Markdown 写出更加优雅的中文文档。
1 关于 Markdown
Markdown 是由 John Gruber 于 2004 年创建的一种文本标记语言，目的是让人们使用“直观的、便于阅读的纯文本格式”书写文档。
与类似于 HTML 标记语言用于展示网页不同，Markdown 被设计用来 专注于文本写作；与 world 不同，Markdown 只有输入文本字符，没有复杂的格式控制，Markdown 仅通过数个文本标记符来实现简单的格式控制，让写作回归写作。
2 Markdown 语法规范
Markdown 设计之初没有明确的语法规范，随着 Markdown 被更多的人使用，这种不规范直接导致了多种 Markdown 语法的变体，Markdown 解析器也变得混乱，无法统一。
开源平台 GitHub 做为 Markdown 文档的直接支持者已经无法忍受这种情况，2017 年 GitHub 发布了 Markdown GFM（GitHub Flavored Markdown） 标准规范，并且修改了 GitHub 的 Markdown 解析器以规范用户行为。
GitHub 在 GFM 规范中详细阐述了为什么需要规范 Markdown 语法，有兴趣的读者可以详细阅读。
重点：
推荐使用 GitHub GFM 规范！
3 中文文档排版规范
3.1 语法规范建议
推荐使用 GitHub GFM 规范！ 其他规范不做介绍。
3.2 标题格式建议
GitHub GFM 规范支持 ATX 标题 和 Setext 标题 规范，推荐使用 ATX 标题 规范，最大支持 6 级标题。
ATX 标题 标题规范示例：
# 一级标题## 二级标题### 三级标题
3.3 空行
不要有多余的空行
文件末尾空一行
标题前后各空一行
3.4 空格
重中之重，希望严格对待。
「有研究显示，打字的时候不喜欢在中文和英文之间加空格的人，感情路都走得很辛苦，有七成的比例会在 34 岁的时候跟自己不爱的人结婚，而其余三成的人最后只能把遗产留给自己的猫。毕竟爱情跟书写都需要适时地留白。
与大家共勉之。」——vinta/paranoid-auto-spacing
3.4.1 中英文之间需要增加空格
正确：
在 LeanCloud 上，数据存储是围绕
AVObject进行的。
错误：
在LeanCloud上，数据存储是围绕
AVObject进行的。在 LeanCloud上，数据存储是围绕
AVObject进行的。
完整的正确用法：
在 LeanCloud 上，数据存储是围绕
AVObject进行的。每个AVObject都包含了与 JSON 兼容的 key-value 对应的数据。数据是 schema-free 的，你不需要在每个AVObject上提前指定存在哪些键，只要直接设定对应的 key-value 即可。
例外：「豆瓣FM」等产品名词，按照官方所定义的格式书写。
3.4.2 中文与数字之间需要增加空格
正确：
今天出去买菜花了 5000 元。
错误：
今天出去买菜花了 5000元。
今天出去买菜花了5000元。
3.4.3 数字与单位之间需要增加空格
正确：
我家的光纤入屋宽带有 10 Gbps，SSD 一共有 20 TB
错误：
我家的光纤入屋宽带有 10Gbps，SSD 一共有 20TB
例外：度 / 百分比与数字之间不需要增加空格：
正确：
今天是 233° 的高温。
新 MacBook Pro 有 15% 的 CPU 性能提升。
错误：
今天是 233 ° 的高温。
新 MacBook Pro 有 15 % 的 CPU 性能提升。
3.4.4 全角标点与其他字符之间不加空格
正确：
刚刚买了一部 iPhone，好开心！
错误：
刚刚买了一部 iPhone ，好开心！
刚刚买了一部 iPhone， 好开心！
4 标点符号
4.1 不重复使用标点符号
正确：
德国队竟然战胜了巴西队！
她竟然对你说「喵」？！
错误：
德国队竟然战胜了巴西队！！
德国队竟然战胜了巴西队！！！！！！！！
她竟然对你说「喵」？？！！
她竟然对你说「喵」？！？！？？！！
5 全角和半角
不明白什么是全角（全形）与半角（半形）符号？请查看维基百科词条『全形和半形』。
5.1 使用全角中文标点
正确：
嗨！你知道嘛？今天前台的小妹跟我说「喵」了哎！
核磁共振成像（NMRI）是什么原理都不知道？JFGI！
错误：
嗨! 你知道嘛? 今天前台的小妹跟我说 "喵" 了哎！
嗨!你知道嘛?今天前台的小妹跟我说"喵"了哎！
核磁共振成像 (NMRI) 是什么原理都不知道? JFGI!
核磁共振成像(NMRI)是什么原理都不知道?JFGI!
5.2 数字使用半角字符
正确：
这个蛋糕只卖 1000 元。
错误：
这个蛋糕只卖 １０００ 元。
例外：在设计稿、宣传海报中如出现极少量数字的情形时，为方便文字对齐，是可以使用全形数字的。
5.3 遇到完整的英文整句、特殊名词，其内容使用半角标点
正确：
贾伯斯那句话是怎么说的？「Stay hungry, stay foolish.」
推荐你阅读《Hackers & Painters: Big Ideas from the Computer Age》，非常的有趣。
错误：
贾伯斯那句话是怎么说的？「Stay hungry，stay foolish。」
推荐你阅读《Hackers＆Painters：Big Ideas from the Computer Age》，非常的有趣。
6 名词
6.1 专有名词使用正确的大小写
大小写相关用法原属于英文书写范畴，不属于本 wiki 讨论内容，在这里只对部分易错用法进行简述。
正确：
使用 GitHub 登录
我们的客户有 GitHub、Foursquare、Microsoft Corporation、Google、Facebook, Inc.。
错误：
使用 github 登录
使用 GITHUB 登录
使用 Github 登录
使用 gitHub 登录
使用 gｲんĤЦ8 登录
我们的客户有 github、foursquare、microsoft corporation、google、facebook, inc.。
我们的客户有 GITHUB、FOURSQUARE、MICROSOFT CORPORATION、GOOGLE、FACEBOOK, INC.。
我们的客户有 Github、FourSquare、MicroSoft Corporation、Google、FaceBook, Inc.。
我们的客户有 gitHub、fourSquare、microSoft Corporation、google、faceBook, Inc.。
我们的客户有 gｲんĤЦ8、ｷouЯƧquﾑгє、๓เςг๏ร๏Ŧt ς๏гק๏гคtเ๏ภn、900913、ƒ4ᄃëв๏๏к, IПᄃ.。
注意：当网页中需要配合整体视觉风格而出现全部大写／小写的情形，HTML 中请使用标淮的大小写规范进行书写；并通过 text-transform: uppercase;／text-transform: lowercase; 对表现形式进行定义。
6.2 不要使用不地道的缩写
正确：
我们需要一位熟悉 JavaScript、HTML5，至少理解一种框架（如 Backbone.js、AngularJS、React 等）的前端开发者。
错误：
我们需要一位熟悉 Js、h5，至少理解一种框架（如 backbone、angular、RJS 等）的 FED。
7 有争议的点
以下用法略带有个人色彩，即：无论是否遵循下述规则，从语法的角度来讲都是 正确 的。
7.1 链接之间增加空格
用法：
请 提交一个 issue 并分配给相关同事。
访问我们网站的最新动态，请 点击这里 进行订阅！
对比用法：
请提交一个 issue并分配给相关同事。
访问我们网站的最新动态，请点击这里进行订阅！
7.2 加粗、斜体、高亮文本前后加空格
建议在 加粗、斜体、高亮文本 前后加空格，否则某种情况会出现格式解析失败。
建议用法：
修复了一个 内存泄露 问题，该问题由 someone 在
版本 v0.1.1中引入。测试文本，这是测试。
不建议用法：
修复了一个内存泄露问题，该问题由someone在
版本 v0.1.1中引入。测试文本 ，这是测试。
解析失败的情况：
这是一个解析失败的情况，当引用了一个函数void main(void)的情况下，如果没有在加粗文本前后增加空格，会导致格式解析失败。这种情况在 GitHub 中存在。
7.3 列表缩进
建议使用 4 个空格进行文本缩进，尤其是遇到有序列表或者无序列表的时候。另外，在使用无序列表或者有序列表的时候，建议在上下级之间空一行，同级之间可以不空行。
示例：
7.4 `/` 的使用
建议 / 字符前后留空格，充当路径描述符的时候除外。
7.5 简体中文使用直角引号
用法：
「老师，『有条不紊』的『紊』是什么意思？」
对比用法：
“老师，‘有条不紊’的‘紊’是什么意思？”
8 谁在这样做？
9 工具推荐
Markdown 实时编辑实时渲染工具推荐以下两个：
Typora
vscode
10 参考
我结合 中文文案排版指北 一文和自己的应用经验汇总输出了 中文文案排版指北-修改版，本文是基于该修改版本。
关注我
版权声明: 本文为 InfoQ 作者【Murphy】的原创文章。
原文链接:【http://xie.infoq.cn/article/69feb60ca6fba4ae0c8adeef6】。文章转载请联系作者。
公众号：物联网学前班；专注物联网知识分享 2020.05.20 加入
从事物联网行业的 Coder，做物联网操作系统开发，熟悉 RTOS 和 IoT 协议。 正在实现自我价值的路上不断奔跑。
评论