Markdown 轉 HTML 完全指南：從語法基礎到進階排版技巧

檔案效率

為什麼用 Markdown？

Markdown 是技術文件的事實標準——GitHub、Stack Overflow、Notion、VS Code 都原生支援。

對比 Markdown Word HTML
學習成本 低 中 高
版本控制 ✅ 純文字 ❌ 二進位 ✅ 純文字
可讀性 ✅ 原始碼即文件 ❌ ❌
表達力 中（擴充後強） 強 強
渲染一致性 中 ❌ 各平台不同 ✅

基礎語法速查

標題

# 一級標題
## 二級標題
### 三級標題
#### 四級標題
##### 五級標題
###### 六級標題

強調

**粗體**    → <strong>粗體</strong>
*斜體*      → <em>斜體</em>
~~刪除線~~  → <del>刪除線</del>
`行內程式碼`  → <code>行內程式碼</code>

清單

- 無序清單項目 1
- 無序清單項目 2
  - 巢狀項目

1. 有序清單項目 1
2. 有序清單項目 2
   1. 巢狀有序項目

- [ ] 待辦事項（未完成）
- [x] 待辦事項（已完成）

連結與圖片

[連結文字](https://example.com)
[帶標題的連結](https://example.com "標題")
![圖片替代文字](image.png)
![帶標題的圖片](image.png "圖片標題")

引用與分隔線

> 引用文字
> > 巢狀引用

---

GFM 擴充語法

表格

| 左對齊 | 置中 | 右對齊 |
|:-------|:----:|-------:|
| 內容   | 內容 | 內容   |
| 長內容 | 短   | 中等   |

渲染結果：

左對齊 置中 右對齊
內容 內容 內容
長內容 短 中等

任務清單

- [x] 需求分析
- [x] 技術設計
- [ ] 開發實作
- [ ] 測試驗收

圍欄程式碼區塊

```javascript
function hello() {
  console.log('Hello, Markdown!');
}
```

```python
def hello():
    print("Hello, Markdown!")
```

註腳

這是一段文字[^1]，還有另一段[^note]。

[^1]: 這是第一個註腳的內容。
[^note]: 這是自訂 ID 的註腳。

進階排版技巧

1. 數學公式（KaTeX/MathJax）

行內公式：$E = mc^2$

區塊公式：
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

矩陣：
$$
\begin{bmatrix}
a & b \\
c & d
\end{bmatrix}
$$

2. Mermaid 圖表

```mermaid
graph TD
    A[使用者請求] --> B{認證檢查}
    B -->|已認證| C[取得資料]
    B -->|未認證| D[回傳 401]
    C --> E[渲染頁面]
```

支援的圖表類型：

類型 語法關鍵字 用途
流程圖 graph 業務流程、決策樹
時序圖 sequenceDiagram API 呼叫、互動流程
類別圖 classDiagram 物件導向設計
狀態圖 stateDiagram 狀態機
甘特圖 gantt 專案排程
圓餅圖 pie 資料佔比

3. 目錄（TOC）

<!-- 自動生成目錄 -->
[[toc]]

<!-- 或手動 -->
- [安裝](#安裝)
- [設定](#設定)
- [使用](#使用)

4. 定義清單

術語 1
: 定義 1

術語 2
: 定義 2

5. 縮寫

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

HTML 是 W3C 制定的標準。

使用工具庫轉換 Markdown

操作步驟

  1. 開啟 Markdown 編輯器
  2. 在左側編輯區輸入 Markdown
  3. 右側即時預覽 HTML 渲染結果
  4. 可切換「原始碼」模式查看生成的 HTML
  5. 支援匯出為 HTML 檔案

支援的擴充功能

擴充 說明 範例
GFM 表格、任務清單、註腳 GitHub 風格
數學公式 KaTeX 渲染 $E=mc^2$
Mermaid 圖表渲染 流程圖、時序圖
語法高亮 Prism.js/highlight.js 程式碼區塊著色
Emoji :smile: → 😄 短代碼替換

Markdown 轉 HTML 的原理

解析流程

Markdown 文字
  ↓
詞法分析（Lexer）→ Token 流
  ↓
語法分析（Parser）→ AST（抽象語法樹）
  ↓
渲染器（Renderer）→ HTML 字串

主流解析函式庫

函式庫 語言 特點 大小
marked JS 最快、最流行 40KB
markdown-it JS 外掛豐富、可擴充 60KB
remark JS AST 生態、MDX 基礎 100KB+
CommonMark JS 嚴格標準合規 50KB
pulldown-cmark Rust 極致效能 WASM 200KB

marked 基礎用法

import { marked } from 'marked';

const html = marked.parse('# Hello **Markdown**');
// <h1>Hello <strong>Markdown</strong></h1>

markdown-it + 外掛

import MarkdownIt from 'markdown-it';
import mk from 'markdown-it-mark';
import footnote from 'markdown-it-footnote';
import tasklist from 'markdown-it-task-lists';

const md = new MarkdownIt({ html: true, linkify: true })
  .use(mk)
  .use(footnote)
  .use(tasklist);

const result = md.render('# Hello Markdown');

MDX：Markdown + JSX

MDX 讓你在 Markdown 中使用 React 元件：

---
title: "我的文章"
---

import { Chart } from './components/Chart';
import { Callout } from './components/Callout';

# 資料分析報告

<Callout type="warning">
  以下資料基於 2026 年 Q1 採樣。
</Callout>

## 使用者成長趨勢

<Chart data={growthData} type="line" />

| 月份 | 使用者數 | 成長率 |
|------|---------|--------|
| 1月  | 10,000  | -      |
| 2月  | 12,500  | 25%    |
| 3月  | 15,000  | 20%    |

最佳實踐

1. 檔案組織

docs/
├── getting-started.md
├── configuration.md
├── api/
│   ├── authentication.md
│   ├── endpoints.md
│   └── errors.md
└── guides/
    ├── deployment.md
    └── troubleshooting.md

2. 寫作規範

  • 一行一句：Git diff 友好，方便審查修改
  • 標題層級不跳級：H1 → H2 → H3，不要 H1 → H3
  • 程式碼區塊指定語言：````javascript` 而非 `````
  • 連結用引用式：長文件中 [文字][ref] 比 [文字](url) 更整潔
  • 圖片加替代文字：![描述](圖片) 提升無障礙性

3. Lint 工具

# 安裝 markdownlint
npm install -g markdownlint-cli

# 檢查
markdownlint docs/**/*.md

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

常見問題

Markdown 中的 HTML 不生效？

部分解析器預設停用原始 HTML，需要開啟 html: true 選項。

表格不支援合併儲存格？

標準 Markdown 表格不支援合併儲存格。需要時使用 HTML 表格：

<table>
  <tr>
    <th>名稱</th>
    <th>描述</th>
  </tr>
  <tr>
    <td rowspan="2">專案 A</td>
    <td>子項目 1</td>
  </tr>
  <tr>
    <td>子項目 2</td>
  </tr>
</table>

程式碼區塊中的 Markdown 語法被解析？

使用更多反引號巢狀：

````markdown
```javascript
console.log('不會被外層解析');
```


---

## 總結

Markdown 是技術寫作的最佳格式——簡潔、可版本控制、生態豐富。掌握基礎語法 + GFM 擴充 + 數學公式 + Mermaid 圖表，就能寫出專業級技術文件。工具庫的 [Markdown 編輯器](/zh-TW/utils/markdown) 提供即時預覽和匯出，讓你專注內容而非排版。
#Markdown#HTML转换#文档编写#排版#教程