如何基于 Markdown 編寫技術文檔

需求

1. 文檔版本清晰化，充分利用Git 的版本管理能力，輕松對比不同版的修改演進。
2. 減少在文檔格式排版上的投入，争取履歷上不再有精通word。
3. 充分利用開發者既有工具，減少工具量，少就是多。

工具鍊

• 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. 設計限制1
2. 設計限制2
3. 設計限制3

表格

文法示意

| 序号 | 姓名 | 年齡  |
|---- |:----:| ----:|
|  1  | 張三 | 20 |
|  2  | 李四 | 30 |
|  3  | 王五 | 40 |           

顯示效果：

序号	姓名	年齡
1	張三	20
2	李四	30
3	王五	40

說明：

• ”：---：“ 居中對齊
• ”---：“ 右對齊
• 預設左對齊

基于插件快速搞定

手工編輯大表有點反人性，基于“Excel to Markdown table”會省心很多，具體如下：

1. 在 Excel 中建好所用表
2. 回到VS Code 中，打開需要粘貼的 md 檔案
3. 使用快捷鍵“Shift + Alt + V”
4. 完成。

嵌入代碼

• 需要引用代碼時，如果隻引用一段，不用分行，可以用 ` 将語句包起來。
• 如果引用的語句為多行，可以将```置于這段代碼的首行和末行，在開始的```後面加上語言，便于相關解析器排版配色。

示例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/)           

最終效果

a link

圖檔

與連結類似，使用

[圖檔說明](圖檔位址)]]

來展示圖檔。

• 網絡圖檔

  • 

  • 

• 本地圖檔

  • [本地圖檔](本地圖檔位址)

引用

在需要引用他人的參考資訊時，在引用的文字前面加上 > ，例如：

> 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

擴充閱讀

• https://commonmark.org/
• https://thisdavej.com/build-an-amazing-markdown-editor-using-visual-studio-code-and-pandoc/