基於 Markdown 的中文文檔排版規範

本篇文章先介紹 Markdown 的背景信息，然後著重介紹 Markdown 中文文檔的排版規範，不介紹 Markdown 的入門使用。

0 前言

相信閱讀本文的讀者一定有被 Markdown 靈活的寫作風格搞懵過，不知道怎麼寫更優雅、更規範，那麼本文就是來幫您梳理 Markdown 寫作過程中常見的一些問題，然後給出一個建議的應用規範。

通過閱讀本文，相信你一定可以基於 Markdown 寫出更加優雅的中文文檔。

1 關於 Markdown

Markdown 是由 John Gruber 於 2004 年創建的一種文本標記語言，目的是讓人們使用「直觀的、便於閱讀的純文本格式」書寫文檔。

與類似於 HTML 標記語言用於展示網頁不同，Markdown 被設計用來 專注於文本寫作；與 word 不同，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 誰在這樣做？ 網站文案UGCApple 中國是N/AApple 香港是N/AApple 臺灣是N/AMicrosoft 中國是N/AMicrosoft 香港是N/AMicrosoft 臺灣是N/ALeanCloud是N/AV2EX是是Apple4us是N/ARuby China是標題達成PHPHub是標題達成少數派是N/A9 工具推薦

Markdown 實時編輯實時渲染工具推薦以下兩個：

10 參考

中文文案排版指北

中文文案排版指北-修改版

Typora 完全使用詳解

引用

1. Markdown 發起者 John Gruber：https://en.wikipedia.org/wiki/John_Gruber
2. GitHub GFM 規範：https://github.github.com/gfm/
3. ATX 標題規範：https://github.github.com/gfm/#atx-headings
4. Setext 標題規範：https://github.github.com/gfm/#setext-heading
5. 關於空格調研說法的引用：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

我結合 中文文案排版指北 一文和自己的應用經驗匯總輸出了 中文文案排版指北-修改版，本文是基於該修改版本。

由於微信排版原因，Markdown 展示效果不是非常理想，請閱讀原文查看！