空垠尘

Markdown 排版規範與高階擴展實踐

· 約 2644 字 · 需 6 分鐘
/ /
#Markdown #排版規範 #LaTeX #Mermaid #技術寫作

引言：純文本寫作的優雅力量

2004 年，約翰·格魯伯（John Gruber）與阿隆·斯沃茨（Aaron Swartz）共同發明了 Markdown 標記語言。其設計的初衷非常純粹：「讓人們能夠使用易讀易寫的純文本格式編寫文檔，並能夠將其輕鬆轉換為結構良好的 XHTML 或 HTML。」

在現代軟體工程與技術寫作領域，Markdown 已經成為事實上的通用排版標準。無論是 GitHub 上的開源專案說明（README.md）、技術部落格的文章記錄，還是企業內部的架構設計文檔，Markdown 都以其極輕的語法負擔、極佳的版本控制友好性，贏得了無數開發者的青睞。

然而，在實際寫作中，「寫出 Markdown」和「寫出專業、工整且具高度可讀性的 Markdown」之間，往往存在著巨大的排版差距。本文將從 基礎排版規範、中英文混排美學 以及 高階擴展語法（LaTeX 公式與 Mermaid 架構圖） 三個維度，系統性地梳理 Markdown 的寫作實踐。

一、 Markdown 核心基礎排版規範

1. 語意化標題結構與層級嚴格性

標題是文檔大綱與閱讀目錄（TOC）的單一事實來源。在技術排版中，必須遵守嚴格的層級遞進規則：

  • 一級標題 (#)：單篇文章僅建議出現一次，通常由部落格系統的文章元數據（Frontmatter title）自動作為主標題渲染；
  • 二級標題 (##)：代表文章的核心獨立大章；
  • 三級標題 (###)：大章內部的具體知識模組；
  • 嚴禁跨層級使用：例如在 ## 下直接跳躍使用 ####，這會導致自動生成的目錄導航（TOC）結構斷裂。
1<!-- 正確示範：嚴格逐級遞進 -->
2## 1. 架構設計原則
3### 1.1 單一職責
4### 1.2 開放封閉
5
6<!-- 錯誤示範：跳級使用導致大綱解析混亂 -->
7## 1. 架構設計原則
8#### 1.1 單一職責 (跳過了 H3)

2. 清單排版與巢狀縮排規範

清單能將散亂的資訊結構化呈現。但在多級清單混排時，空格與縮排是常見的格式崩塌點：

  • 無序清單：推薦統一使用減號 -，同級清單項符號必須全局一致，切勿在同一篇文章中混用 *、+ 和 -；
  • 巢狀縮排：子清單必須相較於父級縮排 2 個空格或 4 個空格（建議全站統一為 2 個空格）；
  • 清單間距：緊湊型清單項之間無需空行，若某一項包含多段文字或程式碼區塊，則整個清單建議使用鬆散型空行分隔。
1- **核心中介軟體層**
2  - 身分鑑權攔截器（JWT / WebAuthn 校驗）
3  - 存取限流中介軟體（基於 Token Bucket 演算法）
4- **資料持久化層**
5  - SQLite WAL 關聯型儲存
6  - 全局唯讀 KV 快取

3. 程式碼區塊與語法高亮規範

程式碼區塊是技術文檔的核心組成部分。優秀的排版應當滿足可讀性與功能性的雙重要求：

  1. 顯式宣告語言標識：在三個反引號後，必須明確標明編程語言的代號（如 go、typescript、rust、bash、json、sql 等）。這不僅能觸發 Chroma 或 Prism 的語法高亮引擎，更能讓前端程式碼卡片正確顯示語言 Badge 並啟用一鍵複製功能；
  2. 區分行內程式碼與區塊級程式碼：
    • 檔案路徑（如 /etc/hosts）、指令選項（如 --minify）、變數名稱（如 userToken）必須使用單個反引號包裹；
    • 包含多行邏輯的程式片段，必須使用獨立程式碼區塊。
1// 宣告語言標識為 typescript
2interface UserSession {
3  userId: string;
4  role: "admin" | "member";
5  expiresAt: number;
6}

4. 引用區塊（Blockquote）的層次感

引用區塊通常用於引經據典、特別宣告、核心結論或設計準則的突出強調：

  • 可以透過多個 > 符號實現多級巢狀引用；
  • 可以在引用區塊內部巢狀使用粗體、斜體、清單甚至程式碼區塊。

核心設計準則：

“簡單性是可靠性的先決條件。在滿足業務需求的前提下，最優秀的程式碼往往是那些被精簡掉的程式碼。”

—— 艾茲格·迪傑斯特拉（Edsger W. Dijkstra）

二、 中英文混排美學與排版細節

一份專業的文檔不僅在於語法無誤，更體現在對標點符號與空白字符等微小細節的雕琢上。

1. 中英文與數字之間的「盤古之白」

在中文排版傳統中，漢字屬於全形方塊字，而英文字母與阿拉伯數字屬於半形字符。當中文字與英文/數字直接貼合在一起時，視覺上會顯得極其擁擠。

  • 推薦做法：在中文字符與英文字符、中文字與數字之間，主動保留一個半形空格；
  • 排版對比：
    • ❌ 差評：我們在2026年使用Hugo編譯了全站的HTML檔案。
    • ✅ 推薦：我們在 2026 年使用 Hugo 編譯了全站的 HTML 檔案。

2. 標點符號的準確使用

  • 中文主句：必須使用標準的全形標點符號（，。！？；：「」『』（））；
  • 英文短語與程式碼段內：必須使用標準的半形標點符號（, . ! ? : "" '' ()）；
  • 避免中英標點混用：中文句子結尾切勿使用英文半形句號 .。

三、 Markdown 進階擴展功能實戰

現代純靜態部落格透過整合 KaTeX 與 Mermaid 渲染引擎，使 Markdown 能夠原生渲染複雜的科學公式與軟體架構圖。

1. 原生 LaTeX / KaTeX 數學公式排版

無需截取低解析度的圖片，直接在 Markdown 中書寫標準 LaTeX 語法即可完成高精度排版。

(1) 行內數學公式（Inline Math）

使用單個美元符號 $ 包裹公式，常用於正文中穿插參數或簡短等式：

  • 質能方程式：$E = mc^2$
  • 歐拉恆等式：$e^{i\pi} + 1 = 0$
  • 常態分佈機率密度函數：$f(x) = \frac{1}{\sigma\sqrt{2\pi}} e^{-\frac{1}{2}\left(\frac{x-\mu}{\sigma}\right)^2}$

(2) 區塊級獨立公式（Display Math）

使用雙美元符號 $$ 包裹獨立公式區塊，公式將置中排版並保留完整的上下標與積分範圍：

  • 高斯積分公式： $$ \int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi} $$

  • 離散傅立葉變換 (DFT)： $$ X_k = \sum_{n=0}^{N-1} x_n \cdot e^{-i \frac{2\pi}{N} k n} \quad (k = 0, 1, \dots, N-1) $$

  • 馬克士威方程組（微分形式）： $$ \begin{aligned} \nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \ \nabla \cdot \mathbf{B} &= 0 \ \nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \ \nabla \times \mathbf{B} &= \mu_0 \mathbf{J} + \mu_0 \varepsilon_0 \frac{\partial \mathbf{E}}{\partial t} \end{aligned} $$

2. Mermaid 向量流程圖與架構圖

在文本中宣告 ```mermaid 程式碼區塊，瀏覽器將在前端動態渲染為向量 SVG 圖表，支援深淺色模式自適應。

(1) 現代邊緣架構流程圖 (graph LR)

flowchart LR
    Client["終端訪客"] -->|"HTTPS / HTTP/3"| CDN["Cloudflare 邊緣網路"]
    CDN -->|"快取命中 (&lt; 10ms)"| EdgeCache["Edge Cache 邊緣快取"]
    CDN -->|"快取未命中"| Pages["Cloudflare Pages 靜態分發"]
    Pages -->|"純淨渲染"| Storage["Markdown 內容庫"]

(2) OAuth 2.1 PKCE 狀態機互動時序圖 (sequenceDiagram)

sequenceDiagram
    autonumber
    actor User as 使用者
    participant Client as 前端應用
    participant Authz as 認證服務
    participant API as 業務 API

    User->>Client: 點擊通行金鑰 Passkey 登入
    Client->>Client: 生成 code_verifier 與 challenge
    Client->>Authz: 發起授權請求 /authorize
    Authz->>User: 觸發 WebAuthn 硬體金鑰驗簽
    User-->>Authz: 驗證指紋或人臉成功
    Authz-->>Client: 返回臨時授權碼 Code
    Client->>Authz: 兌換權杖 /token
    Authz->>Authz: 校驗簽名與 challenge 一致
    Authz-->>Client: 簽發 JWT Access Token
    Client->>API: 攜帶 Token 請求業務資料
    API-->>Client: 200 OK 返回受保護資源

四、 總結：Docs as Code 的工程哲學

在現代技術實踐中，「文檔即代碼（Docs as Code）」的理念正日益成為共識：

  1. 版本控制：文檔與原始碼一同保存在 Git 倉庫中，每次修改都有跡可循；
  2. 規範化治理：透過統一的排版規範與樣式約定，確保團隊產出高標準的知識資產；
  3. 內容與展示分離：純淨的 Markdown 專注於內容本身的邏輯嚴密性，而視覺呈現交由現代靜態渲染引擎全權處理。

養成規範、嚴謹的排版習慣，不僅能讓技術總結更加清晰，更能讓每一次閱讀都成為一種享受。

文章目錄