Markdown 文件寫作完全指南

為什麼用 Markdown 寫文件

如果你參與過軟體開發或技術團隊協作，大概率已經接觸過 Markdown 了——GitHub 上的 README、專案 Wiki、技術部落格，到處都是它的身影。但很多人只是零散地用著，沒有系統地考慮過怎麼用它來組織完整的技術文件。

用 Markdown 寫文件有幾個很實在的好處。它是純文字格式，任何編輯器都能開啟，不依賴特定的軟體或平台。這也意味著它天生適合 Git 版本管理——誰改了哪一行，什麼時候改的，一目了然。說實話，我之前用過 Word 寫內部技術文件，多人協作時合併格式簡直是噩夢，後來切到 Markdown 之後，這類問題基本消失了。

另一個好處是可攜性。同一份 Markdown 檔案，可以渲染成網頁、匯出 PDF、轉換成 Word，甚至產生電子書。你只需要維護一份原始檔，不同輸出格式交給工具去處理。

不過 Markdown 也不是萬能的。它本質上是一個輕量標記語言，如果你需要複雜的排版（比如多欄佈局、精確的頁面控制），那 Markdown 並不是最佳選擇。對於這類需求，AsciiDoc 或 reStructuredText 可能更合適。但對於絕大多數技術文件場景——API 說明、專案手冊、開發指南——Markdown 完全夠用，而且上手成本最低。

Markdown 文件的基本結構

一篇結構清晰的技術文件，通常包含這些部分：

---
title: API 介面文件
version: 2.1.0
last_update: 2026-05-14
---

## 概述

簡要說明這個介面的用途和適用場景。

## 介面列表

### 取得使用者資訊

**請求方式**：`GET /api/users/{id}`

**參數說明**：

| 參數 | 類型 | 必填 | 說明 |
|------|------|------|------|
| id | string | 是 | 使用者唯一識別碼 |
| fields | string | 否 | 回傳欄位篩選 |

**回應範例**：

```json
{
  "id": "u_10086",
  "name": "王小明",
  "email": "wangming@example.com"
}
```

## 錯誤碼

| 錯誤碼 | 說明 |
|--------|------|
| 404 | 使用者不存在 |
| 403 | 無存取權限 |

這個範本涵蓋了技術文件的核心要素：元資料（frontmatter）、概述、詳細說明、範例和錯誤處理。你可能會注意到，參數和錯誤碼這類結構化資料，用表格呈現比純文字描述清楚得多。

Front Matter 元資料

檔案開頭的 --- 包裹部分叫做 frontmatter，用於儲存文件的元資訊。在靜態網站產生器中，這些欄位會被讀取並用於頁面渲染——比如標題、排序、分類、標籤等。常見的 frontmatter 格式是 YAML：

---
title: 快速開始
order: 1
category: 入門指南
tags: [安裝, 設定, 快速開始]
---

在 Markdown 標題和正文之前放置 frontmatter，可以讓文件系統自動產生導航、麵包屑和搜尋索引。這是我建置文件網站時最基礎也最實用的一個習慣。

文件寫作規範

標題層級

每篇文件只用一個頂級結構來組織，避免標題層級混亂。具體來說：

H2（##）作為主要章節分隔
H3（###）用於子章節
盡量不要超過 H4，層級太深說明內容結構需要重新組織

## 安裝
### 系統需求
### 下載安裝包
## 設定
### 基本設定
### 進階選項

有一個細節值得注意：不要在同一個檔案裡混用 ATX 風格（#）和 Setext 風格（=== 底線）的標題。不同 Markdown 解析器對混用場景的處理可能不一致，CommonMark 規範雖然定義了兩者的等價性，但部分工具在產生目錄時會遺漏 Setext 風格的標題。

程式碼範例

技術文件裡的程式碼區塊幾乎是標配。幾個實用建議：

```python
def get_user(user_id: str) -> dict:
    """根據 ID 取得使用者資訊"""
    return db.query("SELECT * FROM users WHERE id = ?", user_id)
```

首先，始終指定語言標籤（python、bash、json 等），這樣渲染時才能啟用語法高亮。其次，程式碼範例要能直接複製執行。我之前寫過一篇部署文件，結果裡面有個指令少了 sudo，讀者直接複製執行後報權限錯誤，這種細節很容易被忽略但影響很大。

如果指令很長需要換行，用 \ 明確標記續行：

docker run -d \
  --name my-docs \
  -p 8080:80 \
  -v $(pwd)/docs:/usr/share/nginx/html \
  nginx:latest

列表和強調

技術文件中大量使用列表來組織步驟或要點。無序列表用 - 或 *，有序列表用 1.。巢狀列表時保持縮排一致（2 或 4 個空格都可以，但全文統一）。

強調要節制使用。**粗體** 留給真正需要突顯的關鍵詞，不要整段加粗——那只會讓讀者分不清重點。*斜體* 適合標註術語或英文縮寫的首次出現。

API 文件的 Markdown 寫法

API 文件是 Markdown 技術文件中最常見也最有價值的應用場景之一。一套規範的 API 文件通常包含這些部分：

## 建立訂單

**介面位址**：`POST /api/v2/orders`

**請求標頭**：

| 欄位 | 值 | 說明 |
|------|-----|------|
| Content-Type | application/json | 請求體格式 |
| Authorization | Bearer {token} | 認證令牌 |

**請求參數**：

| 參數 | 類型 | 必填 | 說明 |
|------|------|------|------|
| product_id | string | 是 | 商品 ID |
| quantity | integer | 是 | 購買數量，最小值 1 |
| coupon_code | string | 否 | 優惠券代碼 |

**請求範例**：

```json
{
  "product_id": "p_20001",
  "quantity": 2,
  "coupon_code": "SAVE20"
}
```

**回應範例**：

```json
{
  "order_id": "ord_20260514001",
  "status": "created",
  "total": 199.00,
  "discount": 39.80
}
```

這種表格加程式碼區塊的組合方式，資訊密度高、結構清晰，是 API 文件的標準寫法。如果介面數量多，建議按模組拆分成多個 Markdown 檔案，然後用文件工具自動聚合成完整的 API 參考。

文件工具和產生器

寫好 Markdown 檔案只是第一步，你還需要工具把它們變成可瀏覽的文件網站。以下是幾個主流的靜態文件網站產生器比較：

工具	語言	特色	適合場景
MkDocs	Python	設定簡單、Material 主題美觀、搜尋體驗好	中小型專案文件、技術部落格
Docusaurus	React/Node	版本管理、MDX 支援、i18n 國際化	開源專案文件、產品文件
Hugo	Go	建置速度極快、適合大型網站	大量頁面的文件站
Docsify	JavaScript	無需建置、執行時渲染、部署簡單	快速原型、內部文件

MkDocs 實戰

我第一次用 MkDocs 建文件網站，從安裝到上線只花了不到半小時。它的核心設定就是一個 mkdocs.yml 檔案：

site_name: 我的專案文件
theme:
  name: material
  language: zh
  features:
    - navigation.tabs
    - search.suggest

nav:
  - 首頁: index.md
  - 快速開始: getting-started.md
  - API 參考:
    - 使用者介面: api/users.md
    - 訂單介面: api/orders.md

專案結構也很直觀：

docs/
├── index.md
├── getting-started.md
└── api/
    ├── users.md
    └── orders.md
mkdocs.yml

有個坑值得一提：MkDocs 預設的搜尋外掛對中文支援不太好，需要安裝 mkdocs-material 主題並設定 search.suggest，或者額外整合 jieba 分詞。我當時折騰了半天才發現這個問題，後來在 mkdocs.yml 裡加了一行 language: zh 就解決了大部分情況。

Docusaurus 適合更大的專案

如果你的文件需要多語言支援或者版本管理，Docusaurus 是更好的選擇。它內建了 i18n（國際化）方案，可以為不同語言產生對應的文件目錄。而且它支援 MDX——也就是在 Markdown 中嵌入 React 元件，非常適合需要互動式範例的 API 文件。

不過 Docusaurus 的學習成本比 MkDocs 高一些，設定也更複雜。對於個人專案或小型團隊，MkDocs 通常就夠了。

文件自動化工作流

把文件當程式碼來管理（Docs-as-Code），是現代技術團隊的標準做法。核心思路是：文件和程式碼放在同一個 Git 儲存庫裡，用同樣的分支、PR、Review 流程來管理。

CI/CD 自動部署

以 GitHub Actions 為例，每次推送到 main 分支時自動建置和部署文件：

name: Deploy Docs
on:
  push:
    branches: [main]
    paths: ['docs/**']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

這樣每次文件更新，網站就會自動重新建置和部署。搭配 paths 過濾器，只有 docs 目錄變更時才觸發，避免不必要的建置。

Markdown Lint

在 CI 中加入 lint 檢查，可以統一團隊的文件風格。markdownlint 是最常用的工具：

# 安裝
npm install -g markdownlint-cli

# 檢查所有文件
markdownlint docs/**/*.md

# 自動修復
markdownlint docs/**/*.md --fix

常見的規則包括：標題層級不能跳級、每行不超過指定長度、程式碼區塊必須指定語言、列表縮排一致等。這些規則看起來繁瑣，但在多人協作時能有效避免格式混亂。

進階技巧

Mermaid 流程圖

在文件中插入流程圖、時序圖，可以讓複雜的邏輯一目了然。Mermaid 是 Markdown 生態中最流行的圖表擴充功能，大部分文件工具都原生支援：

```mermaid
sequenceDiagram
    participant 使用者
    participant 前端
    participant 後端
    使用者->>前端: 提交訂單
    前端->>後端: POST /api/orders
    後端-->>前端: 回傳訂單 ID
    前端-->>使用者: 顯示建立成功
```

MkDocs Material、GitHub、Obsidian 都支援直接渲染 Mermaid 圖表。需要注意的是，有些靜態網站產生器需要額外安裝外掛才能渲染 Mermaid。

Admonition 提示塊

技術文件中經常需要標註提示、警告、注意事項。除了基本的 blockquote（>），很多文件工具支援增強的提示塊語法：

!!! note "注意"
    這個介面在 v3 版本中將被廢棄，請遷移到 v2/orders。

!!! warning "警告"
    刪除操作不可逆，請確認後再執行。

這是 MkDocs Material 主題的語法。Docusaurus 使用的是類似的 :::tip / :::warning 語法。GitHub 則使用 [!NOTE] / [!WARNING] 風格的 Alert 語法。選擇哪種取決於你使用的文件工具。

交叉參照和錨點連結

長文件中經常需要跳轉到其他章節。Markdown 連結支援錨點跳轉：

詳細資訊請參閱 [錯誤碼說明](#錯誤碼)。

大部分文件工具會自動根據標題產生錨點（把標題轉成小寫、空格替換為短橫線）。如果你的文件工具支援，也可以用 [連結文字][ref] 的參照式寫法，把所有連結定義集中放在檔案末尾，保持正文簡潔。

常見問題

Markdown 文件和 Word 文件哪個好？

看場景。團隊內部的技術文件、API 說明、開發指南，Markdown 更合適——版本管理方便、協作效率高、自動化整合簡單。如果是要給外部客戶交付的正式文件（合約、報告），Word 或 PDF 更正式。兩者不衝突，Markdown 作為原始檔，需要時用 Pandoc 轉換輸出即可。

怎麼讓團隊統一 Markdown 寫作風格？

制定一份簡單的 Markdown 風格指南，寫明標題怎麼寫、列表怎麼縮排、程式碼區塊怎麼標註語言等基本規則。然後在 CI 中加入 markdownlint 檢查，不符合規範的文件會在 PR 階段被標記出來。比口頭約定有效得多。

Markdown 文件怎麼產生 PDF？

最常用的方案是 Pandoc。一行指令就行：

pandoc document.md -o document.pdf --pdf-engine=xelatex -V mainfont="Noto Sans CJK SC"

如果文件中有中文內容，必須用 xelatex 引擎並指定中文字體，否則會亂碼。MkDocs 也可以透過外掛匯出 PDF，但設定稍複雜一些。

參考來源

CommonMark Spec — Markdown 標準規範
MkDocs 官方文件 — 專案文件產生工具
GitHub Docs - Markdown — GitHub Flavored Markdown 語法參考
Google Technical Writing Course — 技術寫作線上課程
Write the Docs 社群指南 — 文件寫作實踐指南

Edward Wang