Markdown、Mermaid 與 LaTeX

技術文件、Wiki、部落格與筆記工具（HackMD、Notion、GitHub、本 Wiki）大多支援 Markdown 作為主要寫作格式。進階內容常搭配 Mermaid 畫圖、LaTeX 寫數學公式。本篇說明三者各自做什麼、怎麼寫、以及在本站如何呈現。

Markdown

Markdown 是一種輕量標記語言：用純文字加上簡單符號（#、*、` 等）描述格式，再由編輯器或網站轉成 HTML 顯示。

為什麼要用 Markdown？

常用語法速查

標題

# 一級標題
## 二級標題
### 三級標題Code language: PHP (php)

強調與行內程式碼

**粗體**、*斜體*、~~刪除線~~
行內程式碼：`const x = 1`Code language: JavaScript (javascript)

清單

- 無序項目 A
- 無序項目 B

1. 有序步驟一
2. 有序步驟二

連結與圖片

[顯示文字](https://example.com)
![替代文字](https://example.com/image.png)Code language: JavaScript (javascript)

引用與分隔線

> 這是一段引用說明。

---
（上方為水平分隔線）

表格

| 欄位 A | 欄位 B |
| --- | --- |
| 資料 1 | 資料 2 |
| 資料 3 | 資料 4 |

程式碼區塊

以三個反引號包住，並可標註語言以啟用語法高亮：

```javascript
function greet(name) {
  return `Hello, ${name}`;
}
```Code language: JavaScript (javascript)

Markdown 的局限

• 複雜版面（多欄、浮動圖）需靠 HTML 或平台擴充
• 不同平台實作略有差異（GitHub Flavored Markdown、CommonMark 等）
• 數學公式、流程圖需額外語法（LaTeX、Mermaid）

Mermaid

Mermaid 用「類 Markdown 的文字語法」描述圖表，由瀏覽器或建站工具即時渲染成 SVG。適合放在文件裡說明流程、架構、時序，而不必另外開 draw.io 匯出圖片。

基本寫法

在 Markdown 程式碼區塊標註 mermaid：

```mermaid
flowchart LR
  A[使用者] --> B[前端]
  B --> C[API]
  C --> D[(資料庫)]
```Code language: CSS (css)

渲染後會變成由左至右的流程圖。

常見圖表類型

範例：時序圖（SSO 登入）

sequenceDiagram
  participant U as 使用者
  participant F as 前端
  participant S as SSO 中心
  participant B as 後端

  U->>F: 點擊登入
  F->>S: 導向授權頁
  S->>U: 顯示登入畫面
  U->>S: 完成驗證
  S->>F: 302 帶授權碼
  F->>B: 交換 Token
  B->>F: 回傳 JWTCode language: JavaScript (javascript)

sequenceDiagram
  participant U as 使用者
  participant F as 前端
  participant S as SSO 中心
  participant B as 後端

  U->>F: 點擊登入
  F->>S: 導向授權頁
  S->>U: 顯示登入畫面
  U->>S: 完成驗證
  S->>F: 302 帶授權碼
  F->>B: 交換 Token
  B->>F: 回傳 JWT

範例：流程圖（RAG 檢索）

flowchart TB
  Q[使用者問題] --> E[Embedding]
  E --> V[(向量資料庫)]
  V --> R[Top-K 相關段落]
  R --> P[組裝 Prompt]
  P --> L[LLM 生成回答]
  L --> A[回覆使用者]Code language: CSS (css)

flowchart TB
  Q[使用者問題] --> E[Embedding]
  E --> V[(向量資料庫)]
  V --> R[Top-K 相關段落]
  R --> P[組裝 Prompt]
  P --> L[LLM 生成回答]
  L --> A[回覆使用者]

使用建議

1. 節點文字宜短：長句在圖上難讀，細節放正文。
2. 方向要一致：LR（左右）或 TB（上下）擇一，避免交叉線過多。
3. 中文標籤：Mermaid 支援 UTF-8，可直接寫中文；特殊符號用引號包起來。
4. 版本差異：較新語法如 stateDiagram-v2 在舊版渲染器可能不支援。

LaTeX

LaTeX 是排版系統，在學術與技術領域常用來寫數學公式。許多 Markdown 平台透過 MathJax 或 KaTeX，讓你在 Markdown 裡嵌入 LaTeX 語法顯示公式。

行內公式 vs 區塊公式

部分平台要求 $$ 前後空行，或改用 \[ \]，請依編輯器說明調整。

常用語法

分數、上下標

\frac{a}{b}        % 分數 a/b
x^{2}              % x 的平方
x_{i}              % 下標

希臘字母與符號

\alpha, \beta, \gamma
\sum_{i=1}^{n}     % 求和
\int_{a}^{b}       % 積分
\sqrt{x}           % 根號

矩陣

\begin{bmatrix}
  1 & 2 \\
  3 & 4
\end{bmatrix}

多行對齊

\begin{aligned}
  f(x) &= x^2 + 2x + 1 \\
       &= (x + 1)^2
\end{aligned}

實用範例

softmax（機器學習常見）

$$
\text{softmax}(z_i) = \frac{e^{z_i}}{\sum_{j=1}^{K} e^{z_j}}
$$

注意力機制（直覺式）：

$$
\text{Attention}(Q, K, V) = \text{softmax}\left(\frac{QK^\top}{\sqrt{d_k}}\right) V
$$

### 使用建議

1. **先確認平台有開數學渲染**（HackMD 設定、WordPress 外掛等）。
2. **反斜線要跳脫**：在部分模板裡 `\` 需寫成 `\\`。
3. **複雜公式拆步驟**：用 `aligned` 環境分多行，較易除錯。
4. **與 Markdown 混用**：公式前後保留空行，避免被當成一般文字。Code language: PHP (php)

結合

典型技術文章結構：

flowchart LR
MD[Markdown 正文] --> H[標題 / 清單 / 表格]
MD --> M[Mermaid 圖表]
MD --> L[LaTeX 公式]
H --> HTML[網站渲染]
M --> HTML
L --> HTML

參考資源

• Markdown 語法說明（CommonMark）
• Mermaid 官方文件
• KaTeX 支援的函式列表
• HackMD 功能說明