基于 Markdown 的中文文档排版规范
文章首發(fā)于微信公眾號 “物聯(lián)網(wǎng)學(xué)前班”。
本篇文章先介紹 Markdown 的背景信息，然后著重介紹 Markdown 中文文檔的排版規(guī)范，不介紹 Markdown 的入門使用。
0 前言
相信閱讀本文的讀者一定有被 Markdown 靈活的寫作風(fēng)格搞懵過，不知道怎么寫更優(yōu)雅、更規(guī)范，那么本文就是來幫您梳理 Markdown 寫作過程中常見的一些問題，然后給出一個(gè)建議的應(yīng)用規(guī)范。
通過閱讀本文，相信你一定可以基于 Markdown 寫出更加優(yōu)雅的中文文檔。
1 關(guān)于 Markdown
Markdown 是由 John Gruber 于 2004 年創(chuàng)建的一種文本標(biāo)記語言，目的是讓人們使用“直觀的、便于閱讀的純文本格式”書寫文檔。
與類似于 HTML 標(biāo)記語言用于展示網(wǎng)頁不同，Markdown 被設(shè)計(jì)用來 專注于文本寫作；與 world 不同，Markdown 只有輸入文本字符，沒有復(fù)雜的格式控制，Markdown 僅通過數(shù)個(gè)文本標(biāo)記符來實(shí)現(xiàn)簡單的格式控制，讓寫作回歸寫作。
2 Markdown 語法規(guī)范
Markdown 設(shè)計(jì)之初沒有明確的語法規(guī)范，隨著 Markdown 被更多的人使用，這種不規(guī)范直接導(dǎo)致了多種 Markdown 語法的變體，Markdown 解析器也變得混亂，無法統(tǒng)一。
開源平臺 GitHub 做為 Markdown 文檔的直接支持者已經(jīng)無法忍受這種情況，2017 年 GitHub 發(fā)布了 Markdown GFM（GitHub Flavored Markdown） 標(biāo)準(zhǔn)規(guī)范，并且修改了 GitHub 的 Markdown 解析器以規(guī)范用戶行為。
GitHub 在 GFM 規(guī)范中詳細(xì)闡述了為什么需要規(guī)范 Markdown 語法，有興趣的讀者可以詳細(xì)閱讀。
重點(diǎn)：
推薦使用 GitHub GFM 規(guī)范！
3 中文文檔排版規(guī)范
3.1 語法規(guī)范建議
推薦使用 GitHub GFM 規(guī)范！ 其他規(guī)范不做介紹。
3.2 標(biāo)題格式建議
GitHub GFM 規(guī)范支持 ATX 標(biāo)題 和 Setext 標(biāo)題 規(guī)范，推薦使用 ATX 標(biāo)題 規(guī)范，最大支持 6 級標(biāo)題。
ATX 標(biāo)題 標(biāo)題規(guī)范示例：
# 一級標(biāo)題## 二級標(biāo)題### 三級標(biāo)題3.3 空行
-
不要有多余的空行
在 Markdown 文本中，想要做到渲染后 真換行 通常是使用兩個(gè)空格加一個(gè)回車換行符（Unix 下只有回車 CR），或者粗暴地空一行，但是 請不要連續(xù)空兩行及以上。
-
文件末尾空一行
強(qiáng)烈建議文件末尾空一行，大多數(shù)格式檢查工具都會檢查文件末尾的空行。文件末尾增加空行的可能原因是為了方便進(jìn)行文件拼接處理。
-
標(biāo)題前后各空一行
3.4 空格
重中之重，希望嚴(yán)格對待。
「有研究顯示，打字的時(shí)候不喜歡在中文和英文之間加空格的人，感情路都走得很辛苦，有七成的比例會在 34 歲的時(shí)候跟自己不愛的人結(jié)婚，而其余三成的人最后只能把遺產(chǎn)留給自己的貓。畢竟愛情跟書寫都需要適時(shí)地留白。
與大家共勉之。」——vinta/paranoid-auto-spacing
3.4.1 中英文之間需要增加空格
正確：
在 LeanCloud 上，數(shù)據(jù)存儲是圍繞 AVObject 進(jìn)行的。
錯(cuò)誤：
在LeanCloud上，數(shù)據(jù)存儲是圍繞AVObject進(jìn)行的。
在 LeanCloud上，數(shù)據(jù)存儲是圍繞AVObject 進(jìn)行的。
完整的正確用法：
在 LeanCloud 上，數(shù)據(jù)存儲是圍繞 AVObject 進(jìn)行的。每個(gè) AVObject 都包含了與 JSON 兼容的 key-value 對應(yīng)的數(shù)據(jù)。數(shù)據(jù)是 schema-free 的，你不需要在每個(gè) AVObject 上提前指定存在哪些鍵，只要直接設(shè)定對應(yīng)的 key-value 即可。
例外：「豆瓣FM」等產(chǎn)品名詞，按照官方所定義的格式書寫。
3.4.2 中文與數(shù)字之間需要增加空格
正確：
今天出去買菜花了 5000 元。
錯(cuò)誤：
今天出去買菜花了 5000元。
今天出去買菜花了5000元。
3.4.3 數(shù)字與單位之間需要增加空格
正確：
我家的光纖入屋寬帶有 10 Gbps，SSD 一共有 20 TB
錯(cuò)誤：
我家的光纖入屋寬帶有 10Gbps，SSD 一共有 20TB
例外：度 / 百分比與數(shù)字之間不需要增加空格：
正確：
今天是 233° 的高溫。
新 MacBook Pro 有 15% 的 CPU 性能提升。
錯(cuò)誤：
今天是 233 ° 的高溫。
新 MacBook Pro 有 15 % 的 CPU 性能提升。
3.4.4 全角標(biāo)點(diǎn)與其他字符之間不加空格
正確：
剛剛買了一部 iPhone，好開心！
錯(cuò)誤：
剛剛買了一部 iPhone ，好開心！
剛剛買了一部 iPhone， 好開心！
4 標(biāo)點(diǎn)符號
4.1 不重復(fù)使用標(biāo)點(diǎn)符號
正確：
德國隊(duì)竟然戰(zhàn)勝了巴西隊(duì)！
她竟然對你說「喵」？！
錯(cuò)誤：
德國隊(duì)竟然戰(zhàn)勝了巴西隊(duì)！！
德國隊(duì)竟然戰(zhàn)勝了巴西隊(duì)！！！！！！！！
她竟然對你說「喵」？？！！
她竟然對你說「喵」？！？！？？！！
5 全角和半角
不明白什么是全角（全形）與半角（半形）符號？請查看維基百科詞條『全形和半形』。
5.1 使用全角中文標(biāo)點(diǎn)
正確：
嗨！你知道嘛？今天前臺的小妹跟我說「喵」了哎！
核磁共振成像（NMRI）是什么原理都不知道？JFGI！
錯(cuò)誤：
嗨! 你知道嘛? 今天前臺的小妹跟我說 “喵” 了哎！
嗨!你知道嘛?今天前臺的小妹跟我說"喵"了哎！
核磁共振成像 (NMRI) 是什么原理都不知道? JFGI!
核磁共振成像(NMRI)是什么原理都不知道?JFGI!
5.2 數(shù)字使用半角字符
正確：
這個(gè)蛋糕只賣 1000 元。
錯(cuò)誤：
這個(gè)蛋糕只賣 １０００ 元。
例外：在設(shè)計(jì)稿、宣傳海報(bào)中如出現(xiàn)極少量數(shù)字的情形時(shí)，為方便文字對齊，是可以使用全形數(shù)字的。
5.3 遇到完整的英文整句、特殊名詞，其內(nèi)容使用半角標(biāo)點(diǎn)
正確：
賈伯斯那句話是怎么說的？「Stay hungry, stay foolish.」
推薦你閱讀《Hackers & Painters: Big Ideas from the Computer Age》，非常的有趣。
錯(cuò)誤：
賈伯斯那句話是怎么說的？「Stay hungry，stay foolish。」
推薦你閱讀《Hackers＆Painters：Big Ideas from the Computer Age》，非常的有趣。
6 名詞
6.1 專有名詞使用正確的大小寫
大小寫相關(guān)用法原屬于英文書寫范疇，不屬于本 wiki 討論內(nèi)容，在這里只對部分易錯(cuò)用法進(jìn)行簡述。
正確：
使用 GitHub 登錄
我們的客戶有 GitHub、Foursquare、Microsoft Corporation、Google、Facebook, Inc.。
錯(cuò)誤：
使用 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П?.。
注意：當(dāng)網(wǎng)頁中需要配合整體視覺風(fēng)格而出現(xiàn)全部大寫／小寫的情形，HTML 中請使用標(biāo)淮的大小寫規(guī)范進(jìn)行書寫；并通過 text-transform: uppercase;／text-transform: lowercase; 對表現(xiàn)形式進(jìn)行定義。
6.2 不要使用不地道的縮寫
正確：
我們需要一位熟悉 JavaScript、HTML5，至少理解一種框架（如 Backbone.js、AngularJS、React 等）的前端開發(fā)者。
錯(cuò)誤：
我們需要一位熟悉 Js、h5，至少理解一種框架（如 backbone、angular、RJS 等）的 FED。
7 有爭議的點(diǎn)
以下用法略帶有個(gè)人色彩，即：無論是否遵循下述規(guī)則，從語法的角度來講都是 正確 的。
7.1 鏈接之間增加空格
用法：
請 提交一個(gè) issue 并分配給相關(guān)同事。
訪問我們網(wǎng)站的最新動態(tài)，請 點(diǎn)擊這里 進(jìn)行訂閱！
對比用法：
請?zhí)峤灰粋€(gè) issue并分配給相關(guān)同事。
訪問我們網(wǎng)站的最新動態(tài)，請點(diǎn)擊這里進(jìn)行訂閱！
7.2 加粗、斜體、高亮文本前后加空格
建議在 加粗、斜體、高亮文本 前后加空格，否則某種情況會出現(xiàn)格式解析失敗。
建議用法：
修復(fù)了一個(gè) 內(nèi)存泄露 問題，該問題由 someone 在 版本 v0.1.1 中引入。
測試文本，這是測試。
不建議用法：
修復(fù)了一個(gè)內(nèi)存泄露問題，該問題由someone在版本 v0.1.1中引入。
測試文本 ，這是測試。
解析失敗的情況：
這是一個(gè)解析失敗的情況，當(dāng)引用了一個(gè)函數(shù)**void main(void)**的情況下，如果沒有在加粗文本前后增加空格，會導(dǎo)致格式解析失敗。這種情況在 GitHub 中存在。
7.3 列表縮進(jìn)
建議使用 4 個(gè)空格進(jìn)行文本縮進(jìn)，尤其是遇到有序列表或者無序列表的時(shí)候。另外，在使用無序列表或者有序列表的時(shí)候，建議在上下級之間空一行，同級之間可以不空行。
示例：
- 一級- 二級- 一級- 二級- 二級- 一級- 二級- 三級- 二級- 三級- 三級7.4 / 的使用
建議 / 字符前后留空格，充當(dāng)路徑描述符的時(shí)候除外。
7.5 簡體中文使用直角引號
用法：
「老師，『有條不紊』的『紊』是什么意思？」
對比用法：
“老師，‘有條不紊’的‘紊’是什么意思？”
8 誰在這樣做？
| Apple 中國 | 是 | N/A |
| Apple 香港 | 是 | N/A |
| Apple 臺灣 | 是 | N/A |
| Microsoft 中國 | 是 | N/A |
| Microsoft 香港 | 是 | N/A |
| Microsoft 臺灣 | 是 | N/A |
| LeanCloud | 是 | N/A |
| V2EX | 是 | 是 |
| Apple4us | 是 | N/A |
| Ruby China | 是 | 標(biāo)題達(dá)成 |
| PHPHub | 是 | 標(biāo)題達(dá)成 |
| 少數(shù)派 | 是 | N/A |
9 工具推薦
Markdown 實(shí)時(shí)編輯實(shí)時(shí)渲染工具推薦以下兩個(gè)：
- Typora
- vscode
10 參考
- 中文文案排版指北
- 中文文案排版指北-修改版
- Typora 完全使用詳解
引用
1. Markdown 發(fā)起者 John Gruber：https://en.wikipedia.org/wiki/John_Gruber 2. GitHub GFM 規(guī)范：https://github.github.com/gfm/ 3. ATX 標(biāo)題規(guī)范：https://github.github.com/gfm/#atx-headings 4. Setext 標(biāo)題規(guī)范：https://github.github.com/gfm/#setext-heading 5. 關(guān)于空格調(diào)研說法的引用：https://github.com/vinta/pangu.js 6. 維基百科全角與半角：https://zh.wikipedia.org/wiki/%E5%85%A8%E5%BD%A2%E5%92%8C%E5%8D%8A%E5%BD%A2 7. 中文文案排版指北：https://github.com/sparanoid/chinese-copywriting-guidelines 8. 中文文案排版指北-修改版：https://github.com/sparanoid/chinese-copywriting-guidelines 9. Typora 完全使用詳解：https://sspai.com/post/54912我結(jié)合 中文文案排版指北 一文和自己的應(yīng)用經(jīng)驗(yàn)匯總輸出了 中文文案排版指北-修改版，本文是基于該修改版本。
關(guān)注我吧
總結(jié)
以上是生活随笔為你收集整理的基于 Markdown 的中文文档排版规范的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 手机离线地图地图数据包教程
- 下一篇： 中国搜索引擎白名单