如何基於 Markdown 編寫技術文件
摘要：
需求
文件版本清晰化，充分利用Git 的版本管理能力，輕鬆對比不同版的修改演進。
減少在文件格式排版上的投入，爭取簡歷上不再有精通word。
充分利用開發者既有工具，減少工具量，少就是多。
工具鏈
OS：macOS Mojave V10.14.3 ...
需求
- 文件版本清晰化，充分利用Git 的版本管理能力，輕鬆對比不同版的修改演進。
- 減少在文件格式排版上的投入，爭取簡歷上不再有精通word。
- 充分利用開發者既有工具，減少工具量，少就是多。
工具鏈
- OS：macOS Mojave V10.14.3
- IDE：Visual Studio Code
- Visual Studio Code擴充套件外掛：
- markdownlint：在寫書中如有違規，會在編輯區提示你。
- Markdown PDF：將 md 檔案轉換為 pdf、html、jgp 等，便於非技術人員閱讀。
- Preview：預覽最終效果。
- Excel to Markdown table: 將 Excel 錶快速變成 markdown 格式的。
技術文件基本元素的實現
文章標題及各章節標題
用“#”來標記標題，每增加一級增加一個 # ，字號也會減小。# 和文字之間留一個空格。
# 史上最牛的設計方案 ## 1. 產品需求 ### 1.1 功能需求 #### 1.1.1 移動端需求 ##### 1.1.1.1 iOS 版需求 ###### 1.1.1.1.1 支援 Carplay ### 1.2 非功能需求 ## 2. 產品設計 ## 3. 資源需求
資訊列表
在文字前面加上 * 或 數字 1. 2. 3. 等即可顯示列表。
無序列表的語法示例
* 效能需求 * 穩定性需求 * 相容性需求
無序列表的顯示效果
- 效能需求
- 穩定性需求
- 相容性需求
有序列表的語法示例
1. 設計約束1 2. 設計約束2 3. 設計約束3
有序列表的顯示效果
- 設計約束1
- 設計約束2
- 設計約束3
表格
語法示意
| 序號 | 姓名 | 年齡| |---- |:----:| ----:| |1| 張三 | 20 | |2| 李四 | 30 | |3| 王五 | 40 |
顯示效果：
| 序號 | 姓名 | 年齡 |
|---|---|---|
| 1 | 張三 | 20 |
| 2 | 李四 | 30 |
| 3 | 王五 | 40 |
說明：
- ”：---：“ 居中對齊
- ”---：“ 右對齊
- 預設左對齊
基於外掛快速搞定
手工編輯大表有點反人性，基於“Excel to Markdown table”會省心很多，具體如下：
- 在 Excel 中建好所用表
- 回到VS Code 中，開啟需要貼上的 md 檔案
- 使用快捷鍵“Shift + Alt + V”
- 完成。
嵌入程式碼
- 需要引用程式碼時，如果只引用一段，不用分行，可以用 ` 將語句包起來。
- 如果引用的語句為多行，可以將```置於這段程式碼的首行和末行，在開始的```後面加上語言，便於相關解析器排版配色。
示例1: bash語句
示例1：語法
```bash
#!/bin/bash
echo Hello world
```
示例1：最終效果
#!/bin/bash echo Hello world
示例2: sql語句
示例2：語法
```sql
SELECT Persons.LastName, Persons.FirstName, Orders.OrderNo
FROM Persons
INNER JOIN Orders
ON Persons.Id_P = Orders.Id_P
ORDER BY Persons.LastName
```
示例2：最終效果
SELECT Persons.LastName, Persons.FirstName, Orders.OrderNo FROM Persons INNER JOIN Orders ON Persons.Id_P = Orders.Id_P ORDER BY Persons.LastName
連結
語法
[a link](https://commonmark.org/)
最終效果
圖片
與連結類似，使用 [圖片說明](圖片地址)]] 來展示圖片。
- 網路圖片
-
 -
網路圖片
-
- 本地圖片
-
[本地圖片](本地圖片地址) -
本地圖片
-
引用
在需要引用他人的參考資訊時，在引用的文字前面加上 > ，例如：
> TPC Benchmark E is an on-line transaction processing (OLTP) benchmark. TPC-E is more complex than previous OLTP benchmarks such as TPC-C because of its diverse transaction types, more complex database and overall execution structure.
注：> 和文字之間要保留一個字元的空格。
最終顯示效果：
TPC Benchmark E is an on-line transaction processing (OLTP) benchmark. TPC-E is more complex than previous OLTP benchmarks such as TPC-C because of its diverse transaction types, more complex database and overall execution structure.
生成外發文件
- 按 F1
- 按提示選擇 “markdown-pdf: Export (pdf)”
- 按回車，即生成 PDF 檔案
常用Tips
獲得目錄的樹形展示
Mac預設沒有 tree 命令，又不想安裝其他工具，可以通過下面的命令來救急。
find . -print | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
預覽效果
- 方式1：使用側邊預覽
- 優點：markdown 編輯視窗與預覽視窗並列，及時反饋。
- 不足：空間受限，會影響排版效果。
- 點選編輯框右上角圖示啟動。
- 方式2：使用獨立頁面預覽
- 優點：完整展示效果
- 不足：反饋滯後
- 快捷鍵：Shift + Cmd + V