當(dāng)前位置：首頁(yè) > 编程资源 > 编程问答 >内容正文

编程问答

基于 Markdown 的中文文档排版规范

發(fā)布時(shí)間：2024/8/1 编程问答 43 豆豆

生活随笔收集整理的這篇文章主要介紹了基于 Markdown 的中文文档排版规范小編覺(jué)得挺不錯(cuò)的,現(xiàn)在分享給大家,幫大家做個(gè)參考.

文章首發(fā)于微信公眾號(hào) “物聯(lián)網(wǎng)學(xué)前班”。

本篇文章先介紹 Markdown 的背景信息，然后著重介紹 Markdown 中文文檔的排版規(guī)范，不介紹 Markdown 的入門使用。

0 前言

相信閱讀本文的讀者一定有被 Markdown 靈活的寫作風(fēng)格搞懵過(guò)，不知道怎么寫更優(yōu)雅、更規(guī)范，那么本文就是來(lái)幫您梳理 Markdown 寫作過(guò)程中常見(jiàn)的一些問(wèn)題，然后給出一個(gè)建議的應(yīng)用規(guī)范。

通過(guò)閱讀本文，相信你一定可以基于 Markdown 寫出更加優(yōu)雅的中文文檔。

1 關(guān)于 Markdown

Markdown 是由 John Gruber 于 2004 年創(chuàng)建的一種文本標(biāo)記語(yǔ)言，目的是讓人們使用“直觀的、便于閱讀的純文本格式”書寫文檔。

與類似于 HTML 標(biāo)記語(yǔ)言用于展示網(wǎng)頁(yè)不同，Markdown 被設(shè)計(jì)用來(lái) 專注于文本寫作；與 world 不同，Markdown 只有輸入文本字符，沒(méi)有復(fù)雜的格式控制，Markdown 僅通過(guò)數(shù)個(gè)文本標(biāo)記符來(lái)實(shí)現(xiàn)簡(jiǎn)單的格式控制，讓寫作回歸寫作。

2 Markdown 語(yǔ)法規(guī)范

Markdown 設(shè)計(jì)之初沒(méi)有明確的語(yǔ)法規(guī)范，隨著 Markdown 被更多的人使用，這種不規(guī)范直接導(dǎo)致了多種 Markdown 語(yǔ)法的變體，Markdown 解析器也變得混亂，無(wú)法統(tǒng)一。

開(kāi)源平臺(tái) GitHub 做為 Markdown 文檔的直接支持者已經(jīng)無(wú)法忍受這種情況，2017 年 GitHub 發(fā)布了 Markdown GFM（GitHub Flavored Markdown）標(biāo)準(zhǔn)規(guī)范，并且修改了 GitHub 的 Markdown 解析器以規(guī)范用戶行為。

GitHub 在 GFM 規(guī)范中詳細(xì)闡述了為什么需要規(guī)范 Markdown 語(yǔ)法，有興趣的讀者可以詳細(xì)閱讀。

重點(diǎn)：

推薦使用 GitHub GFM 規(guī)范！

3 中文文檔排版規(guī)范

3.1 語(yǔ)法規(guī)范建議

推薦使用 GitHub GFM 規(guī)范！ 其他規(guī)范不做介紹。

3.2 標(biāo)題格式建議

GitHub GFM 規(guī)范支持 ATX 標(biāo)題 和 Setext 標(biāo)題 規(guī)范，推薦使用 ATX 標(biāo)題規(guī)范，最大支持 6 級(jí)標(biāo)題。

ATX 標(biāo)題 標(biāo)題規(guī)范示例：

# 一級(jí)標(biāo)題## 二級(jí)標(biāo)題### 三級(jí)標(biāo)題

3.3 空行

不要有多余的空行

在 Markdown 文本中，想要做到渲染后 真換行 通常是使用兩個(gè)空格加一個(gè)回車換行符（Unix 下只有回車 CR），或者粗暴地空一行，但是 請(qǐng)不要連續(xù)空兩行及以上。
文件末尾空一行

強(qiáng)烈建議文件末尾空一行，大多數(shù)格式檢查工具都會(huì)檢查文件末尾的空行。文件末尾增加空行的可能原因是為了方便進(jìn)行文件拼接處理。
標(biāo)題前后各空一行

3.4 空格

重中之重，希望嚴(yán)格對(duì)待。

「有研究顯示，打字的時(shí)候不喜歡在中文和英文之間加空格的人，感情路都走得很辛苦，有七成的比例會(huì)在 34 歲的時(shí)候跟自己不愛(ài)的人結(jié)婚，而其余三成的人最后只能把遺產(chǎn)留給自己的貓。畢竟愛(ài)情跟書寫都需要適時(shí)地留白。

與大家共勉之。」——vinta/paranoid-auto-spacing

3.4.1 中英文之間需要增加空格

正確：

在 LeanCloud 上，數(shù)據(jù)存儲(chǔ)是圍繞 AVObject 進(jìn)行的。

錯(cuò)誤：

在LeanCloud上，數(shù)據(jù)存儲(chǔ)是圍繞AVObject進(jìn)行的。

在 LeanCloud上，數(shù)據(jù)存儲(chǔ)是圍繞AVObject 進(jìn)行的。

完整的正確用法：

在 LeanCloud 上，數(shù)據(jù)存儲(chǔ)是圍繞 AVObject 進(jìn)行的。每個(gè) AVObject 都包含了與 JSON 兼容的 key-value 對(duì)應(yīng)的數(shù)據(jù)。數(shù)據(jù)是 schema-free 的，你不需要在每個(gè) AVObject 上提前指定存在哪些鍵，只要直接設(shè)定對(duì)應(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，好開(kāi)心！

錯(cuò)誤：

剛剛買了一部 iPhone ，好開(kāi)心！

剛剛買了一部 iPhone，好開(kāi)心！

4 標(biāo)點(diǎn)符號(hào)

4.1 不重復(fù)使用標(biāo)點(diǎn)符號(hào)

正確：

德國(guó)隊(duì)竟然戰(zhàn)勝了巴西隊(duì)！

她竟然對(duì)你說(shuō)「喵」？！

錯(cuò)誤：

德國(guó)隊(duì)竟然戰(zhàn)勝了巴西隊(duì)！！

德國(guó)隊(duì)竟然戰(zhàn)勝了巴西隊(duì)！！！！！！！！

她竟然對(duì)你說(shuō)「喵」？？！！

她竟然對(duì)你說(shuō)「喵」？！？！？？！！

5 全角和半角

不明白什么是全角（全形）與半角（半形）符號(hào)？請(qǐng)查看維基百科詞條『全形和半形』。

5.1 使用全角中文標(biāo)點(diǎn)

正確：

嗨！你知道嘛？今天前臺(tái)的小妹跟我說(shuō)「喵」了哎！

核磁共振成像（NMRI）是什么原理都不知道？JFGI！

錯(cuò)誤：

嗨! 你知道嘛? 今天前臺(tái)的小妹跟我說(shuō) “喵” 了哎！

嗨!你知道嘛?今天前臺(tái)的小妹跟我說(shuō)"喵"了哎！

核磁共振成像 (NMRI) 是什么原理都不知道? JFGI!

核磁共振成像(NMRI)是什么原理都不知道?JFGI!

5.2 數(shù)字使用半角字符

正確：

這個(gè)蛋糕只賣 1000 元。

錯(cuò)誤：

這個(gè)蛋糕只賣１０００元。

例外：在設(shè)計(jì)稿、宣傳海報(bào)中如出現(xiàn)極少量數(shù)字的情形時(shí)，為方便文字對(duì)齊，是可以使用全形數(shù)字的。

5.3 遇到完整的英文整句、特殊名詞，其內(nèi)容使用半角標(biāo)點(diǎn)

正確：

賈伯斯那句話是怎么說(shuō)的？「Stay hungry, stay foolish.」

推薦你閱讀《Hackers & Painters: Big Ideas from the Computer Age》，非常的有趣。

錯(cuò)誤：

賈伯斯那句話是怎么說(shuō)的？「Stay hungry，stay foolish。」

推薦你閱讀《Hackers＆Painters：Big Ideas from the Computer Age》，非常的有趣。

6 名詞

6.1 專有名詞使用正確的大小寫

大小寫相關(guān)用法原屬于英文書寫范疇，不屬于本 wiki 討論內(nèi)容，在這里只對(duì)部分易錯(cuò)用法進(jìn)行簡(jiǎ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)頁(yè)中需要配合整體視覺(jué)風(fēng)格而出現(xiàn)全部大寫／小寫的情形，HTML 中請(qǐng)使用標(biāo)淮的大小寫規(guī)范進(jìn)行書寫；并通過(guò) text-transform: uppercase;／text-transform: lowercase; 對(duì)表現(xiàn)形式進(jìn)行定義。

6.2 不要使用不地道的縮寫

正確：

我們需要一位熟悉 JavaScript、HTML5，至少理解一種框架（如 Backbone.js、AngularJS、React 等）的前端開(kāi)發(fā)者。

錯(cuò)誤：

我們需要一位熟悉 Js、h5，至少理解一種框架（如 backbone、angular、RJS 等）的 FED。

7 有爭(zhēng)議的點(diǎn)

以下用法略帶有個(gè)人色彩，即：無(wú)論是否遵循下述規(guī)則，從語(yǔ)法的角度來(lái)講都是正確的。

7.1 鏈接之間增加空格

用法：

請(qǐng) 提交一個(gè) issue 并分配給相關(guān)同事。

訪問(wèn)我們網(wǎng)站的最新動(dòng)態(tài)，請(qǐng) 點(diǎn)擊這里進(jìn)行訂閱！

對(duì)比用法：

請(qǐng)?zhí)峤灰粋€(gè) issue并分配給相關(guān)同事。

訪問(wèn)我們網(wǎng)站的最新動(dòng)態(tài)，請(qǐng)點(diǎn)擊這里進(jìn)行訂閱！

7.2 加粗、斜體、高亮文本前后加空格

建議在加粗、斜體、高亮文本 前后加空格，否則某種情況會(huì)出現(xiàn)格式解析失敗。

建議用法：

修復(fù)了一個(gè) 內(nèi)存泄露 問(wèn)題，該問(wèn)題由 someone 在版本 v0.1.1 中引入。

測(cè)試文本，這是測(cè)試。

不建議用法：

修復(fù)了一個(gè)內(nèi)存泄露問(wèn)題，該問(wèn)題由someone在版本 v0.1.1中引入。

測(cè)試文本 ，這是測(cè)試。

解析失敗的情況：

這是一個(gè)解析失敗的情況，當(dāng)引用了一個(gè)函數(shù)**void main(void)**的情況下，如果沒(méi)有在加粗文本前后增加空格，會(huì)導(dǎo)致格式解析失敗。這種情況在 GitHub 中存在。

7.3 列表縮進(jìn)

建議使用 4 個(gè)空格進(jìn)行文本縮進(jìn)，尤其是遇到有序列表或者無(wú)序列表的時(shí)候。另外，在使用無(wú)序列表或者有序列表的時(shí)候，建議在上下級(jí)之間空一行，同級(jí)之間可以不空行。

示例：

- 一級(jí)- 二級(jí)- 一級(jí)- 二級(jí)- 二級(jí)- 一級(jí)- 二級(jí)- 三級(jí)- 二級(jí)- 三級(jí)- 三級(jí)

7.4 / 的使用

建議 / 字符前后留空格，充當(dāng)路徑描述符的時(shí)候除外。

7.5 簡(jiǎn)體中文使用直角引號(hào)

用法：

「老師，『有條不紊』的『紊』是什么意思？」

對(duì)比用法：

“老師，‘有條不紊’的‘紊’是什么意思？”

8 誰(shuí)在這樣做？

網(wǎng)站文案UGC

Apple 中國(guó)	是	N/A
Apple 香港	是	N/A
Apple 臺(tái)灣	是	N/A
Microsoft 中國(guó)	是	N/A
Microsoft 香港	是	N/A
Microsoft 臺(tái)灣	是	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)研說(shuō)法的引用：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 的中文文档排版规范的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

如果覺(jué)得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。