Markdown技術檔案撰寫規范
Markdown是一種可以使用普通文本編輯器撰寫的標記語言，通過簡單的標記語法，它可以使普通文本內容具有一定的格式，
檔案體系
-
結構
-
簡介（Introduction）： [必備] [檔案] 提供對產品和檔案本身的總體的、扼要的說明
-
快速上手（Getting Started）：[可選] [檔案] 如何最快速地使用產品
-
入門篇（Basics）： [必備] [目錄] 又稱”使用篇“，提供初級的使用教程
- 環境準備（Prerequisite）：[必備] [檔案] 軟體使用需要滿足的前置條件
- 安裝（Installation）：[可選] [檔案] 軟體的安裝方法
- 設定（Configuration）：[必備] [檔案] 軟體的設定
-
進階篇（Advanced)：[可選] [目錄] 又稱”開發篇“，提供中高級的開發教程
-
API（Reference）：[可選] [目錄|檔案] 軟體 API 的逐一介紹
-
FAQ：[可選] [檔案] 常見問題解答
-
附錄（Appendix）：[可選] [目錄] 不屬于教程本身、但對閱讀教程有幫助的內容
- Glossary：[可選] [檔案] 名詞解釋
- Recipes：[可選] [檔案] 最佳實踐
- Troubleshooting：[可選] [檔案] 故障處理
- ChangeLog：[可選] [檔案] 版本說明
- Feedback：[可選] [檔案] 反饋方式
-
規則
-
Markdown檔案檔案后綴名使用
.md， -
檔案名建議只使用小寫字母，多個單詞可使用
-分隔，- 檔案名不得含有空格，
- 檔案名不得使用全角字符（中文不能用于檔案名），
- （為了醒目，某些說明檔案的檔案名，可以使用大寫字母，例如
README.mdLICENSE.md檔案，）
-
檔案編碼統一使用
UTF-8， -
文章標題與內容之間必須有一個空行，
// false ## 章節一 內容 ## 章節二 // true ## 章節一 內容 ##章節二 -
代碼段必須使用如下風格：
···
// some code
// this is FCB(Fenced code blocks Style)
···
- 表格寫法應該參考如下風格：
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 |
-
中英文混排應該采用以下規則：
- 英文和數字應使用半角字符
- 中文文字之間不加空格
- 中文文字與英文、阿拉伯數字及 @ # $ % ^ & * . ( ) 等符號之間加空格
- 中文標點之間不加空格
- 中文標點與前后字符（無論全角或半角）之間不加空格
- 如果括號內有中文，則使用中文括號
- 如果括號中的內容全部都是英文，則使用半角英文括號
- 當半角符號 / 表示「或者」之意時，與前后的字符之間均不加空格
-
中文符號應該使用如下寫法
- 用直角引號（「」）代替雙引號（“”）
- 省略號使用「……」，而「，，，」僅用于表示停頓
-
表達方式（語法規范）：
- 使段落成為文章的單元：一個段落只表達一個主題
- 通常在每一段落開始要點題，在段落結尾要扣題
- 使用主動語態
- 陳述句中使用肯定說法
- 洗掉不必要的詞
- 避免連續使用松散的句子
- 使用相同的結構表達并列的意思
- 將相關的詞放在一起
- 在總結中，要用同一種時態（這里指英文中的時態，中文不適用，所以可以不理會）
- 將強調的詞放在句末
轉載請註明出處，本文鏈接：https://www.uj5u.com/qita/491.html
標籤：其他