此為前端開發(fā)團隊遵循和約定的 Markdown 編寫規(guī)范，意在提高文檔的可讀性。
另附中文文案排版指北：https://github.com/sparanoid/chinese-copywriting-guidelines/blob/master/README.zh-CN.md
1. 說明
文檔中使用的關鍵字「MUST」,「MUST NOT」,「REQUIRED」,「SHALL」,「SHALL NOT」,「SHOULD」,「SHOULD NOT」,「RECOMMENDED」,「MAY」和「OPTIONAL」在 RFC2119 中有說明。
還未定稿，對規(guī)范中提及的點有不贊同的歡迎提出 issues（請?zhí)砑?markdown 標簽）討論。
2. 規(guī)則
后綴必須「MUST」使用
.md。文件名必須「MUST」使用小寫，多個單詞之間使用
-分隔。文件編碼必須「MUST」用 UTF-8。
-
文檔標題應該「SHOULD」這樣寫。
Markdown 編寫規(guī)范 ========================== 章節(jié)標題必須「MUST」以
##開始，而不是#。-
章節(jié)標題必須「MUST」在
#后加一個空格，且后面沒有#。// bad ##章節(jié)1 // bad ## 章節(jié)1 ## // good ## 章節(jié)1 -
章節(jié)標題和內容間必須「MUST」有一個空行。
// bad ## 章節(jié)1 內容 ## 章節(jié)2 // good ## 章節(jié)1 內容 ## 章節(jié)2 -
代碼段的必須「MUST」使用 Fenced code blocks 風格，如下所示：
``` console.log(""); ``` -
表格的寫法應該「SHOULD」參考 GFM，如下所示：
First Header | Second Header ------------- | ------------- Content Cell | Content Cell Content Cell | Content Cell | Left-Aligned | Center Aligned | Right Aligned | | :------------ |:---------------:| -----:| | col 3 is | some wordy text | $1600 | | col 2 is | centered | $12 | | zebra stripes | are neat | $1 | -
中英文混排應該「SHOULD」采用如下規(guī)則：
- 英文和數(shù)字使用半角字符
- 中文文字之間不加空格
- 中文文字與英文、阿拉伯數(shù)字及 @ # $ % ^ & * . ( ) 等符號之間加空格
- 中文標點之間不加空格
- 中文標點與前后字符（無論全角或半角）之間不加空格
- 如果括號內有中文，則使用中文括號
- 如果括號中的內容全部都是英文，則使用半角英文括號
- 當半角符號 / 表示「或者」之意時，與前后的字符之間均不加空格
- 其它具體例子推薦 閱讀這里
-
中文符號應該「SHOULD」使用如下寫法：
-
表達方式，應當「SHOULD」遵循《The Element of Style》：
- 使段落成為文章的單元：一個段落只表達一個主題
- 通常在每一段落開始要點題，在段落結尾要扣題
- 使用主動語態(tài)
- 陳述句中使用肯定說法
- 刪除不必要的詞
- 避免連續(xù)使用松散的句子
- 使用相同的結構表達并列的意思
- 將相關的詞放在一起
- 在總結中，要用同一種時態(tài)（這里指英文中的時態(tài)，中文不適用，所以可以不理會）
- 將強調的詞放在句末
3. 擴展閱讀
- Google 后來也出了 Markdown 規(guī)范，很多和這里是一樣的，但也增加了一些約定，可以參考
