Markdown 完整語法教學：30 個技巧 + 線上預覽工具

寫給：每天寫 README、Notion / Obsidian 筆記、技術文件、GitHub Issue 的工程師、PM、技術寫手，以及想擺脫 Word 的所有人。

Markdown 由 John Gruber 與 Aaron Swartz 於 2004 年提出，理念是「用純文字寫出能轉成漂亮 HTML 的文件」。20 年後它已是技術寫作事實標準：GitHub、Reddit、Discord、Notion、Obsidian、Slack、Bear 全部支援。但 Markdown 並非單一規格——CommonMark / GFM / MDX / Pandoc 之間細節有別。本文 13 分鐘整理 30 個實用技巧、跨平台陷阱，並示範 SuperTools 線上預覽工具。

1. Markdown 是什麼

Markdown 是一種輕量級標記語言。設計目標：

  1. 純文字格式（任何編輯器可開）
  2. 語法直觀（即使不轉 HTML 也好讀）
  3. 可一鍵轉成 HTML / PDF / DOCX

對比 HTML：

想要的格式 HTML Markdown
粗體 <strong>foo</strong> **foo**
連結 <a href="url">text</a> [text](url)
標題 <h2>foo</h2> ## foo
列表 <ul><li>...</li></ul> - ...

寫作體驗差距巨大。

1.1 規格家族

規格 全名 特色
CommonMark CommonMark 嚴格標準化（2014 起）
GFM GitHub Flavored Markdown CommonMark + 表格 + 任務清單 + 自動連結
MDX Markdown + JSX React 元件嵌入（Docusaurus、Astro）
Pandoc Pandoc Markdown 學術寫作（腳註、citation、LaTeX）
MultiMarkdown MMD metadata + 表格
Obsidian Markdown - wikilink + tag + Dataview

寫作前先確認目標平台支援哪種。本文以 GFM 為主，標註 CommonMark 不支援之處。

2. 5 個核心觀念

2.1 基本元素

# H1
## H2
### H3

**粗體** 或 __粗體__
*斜體* 或 _斜體_
~~刪除線~~
`inline code`

> blockquote
>> 巢狀 blockquote

- 無序列表
- 第二項
  - 巢狀
    - 再巢狀

1. 有序列表
2. 第二項

[連結文字](https://example.com)
![圖片 alt](image.png)

---  (水平線)

慣例：

  • H1 一篇只用一次（SEO + 無障礙）
  • 列表用 - 不用 *（容易與斜體混淆）
  • 巢狀縮排用 2 spaces（CommonMark）或 4 spaces（pre-CommonMark）

2.2 連結與圖片進階

# inline 連結
[Google](https://google.com "Tooltip 文字")

# reference 連結（適合重複連結）
這是 [Google][1] 跟 [Bing][2]。

[1]: https://google.com
[2]: https://bing.com

# 自動連結
<https://example.com>
<email@example.com>

# 圖片含尺寸（GFM 不支援，需 HTML）
<img src="logo.png" alt="logo" width="200" />

# 圖片連結（點圖片開新頁）
[![alt](thumb.png)](https://full-image-url)

2.3 程式碼塊與語法 highlight

` ` `python
def hello():
    print("hello")
` ` `

（實際寫的時候三個反引號連在一起。）

支援的語言：幾乎所有（python / js / go / rust / bash / sql / yaml / json / ...）。錯誤 highlight 通常用 text 或 plaintext。

GitHub 額外支援 diff：

` ` `diff
- old line
+ new line
` ` `

2.4 表格（GFM）

| 欄位 1 | 欄位 2 | 欄位 3 |
|--------|:------:|-------:|
| 左對齊 | 置中 | 右對齊 |
| data | data | data |

對齊由分隔行的冒號控制：

  • :--- 左對齊（預設）
  • :---: 置中
  • ---: 右對齊

表格不能有跨行 cell，需要時用 HTML <table>。

2.5 任務清單（GFM）

- [x] 已完成
- [ ] 未完成
- [ ] 巢狀
  - [x] 子任務 1
  - [ ] 子任務 2

GitHub Issue / Notion / Obsidian / Linear 均支援。可作為 mini Kanban。

3. 實戰範例 30 個技巧

3.1 表格與資料

技巧 1：HTML 表格細粒度控制

<table>
  <tr>
    <th rowspan="2">名稱</th>
    <th colspan="2">數據</th>
  </tr>
  <tr>
    <td>2025</td>
    <td>2026</td>
  </tr>
</table>

技巧 2：表格內含程式碼

| Command | Description |
|---------|-------------|
| `git pull` | 抓最新 |
| `git push` | 推到遠端 |

技巧 3：表格內含換行

GFM 用 <br> 強制換行：

| Col |
|-----|
| Line 1<br>Line 2 |

3.2 連結與引用

技巧 4：頁內錨點跳轉

跳到 [第三章](#第三章標題)

## 第三章標題

GitHub 自動把 H 標題轉成 kebab-case slug。

技巧 5：腳註（GFM + Pandoc）

這裡有一個腳註[^1]。

[^1]: 腳註內容寫這。

技巧 6：定義列表（Pandoc / Obsidian）

詞 1
:   定義 1

詞 2
:   定義 2

3.3 列表進階

技巧 7：列表間的程式碼塊

1. 第一步
2. 第二步：
   ` ` `bash
   npm install
   ` ` `
3. 第三步

縮排 3 spaces（對齊 2. 後）讓 code block 算同一個 item。

技巧 8：跳號的有序列表

1. 第一
1. 第二
1. 第三

數字隨意（Markdown 自動編號），但建議用 1. 1. 1. 維持 diff 乾淨。

技巧 9：嵌套引用 + 列表

> 名言：
> 
> - 第一句
> - 第二句

3.4 媒體

技巧 10：影片嵌入（多數渲染器不支援直接 mp4，用 GIF 或 thumbnail）

[![Watch the video](thumbnail.png)](https://youtube.com/watch?v=xxx)

技巧 11：GitHub README 顯示 Badge

![Build](https://img.shields.io/github/actions/workflow/status/owner/repo/ci.yml)
![License](https://img.shields.io/github/license/owner/repo)

技巧 12：響應式圖片（依主題切換）

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="logo-dark.png">
  <img alt="logo" src="logo-light.png">
</picture>

3.5 樣式與排版

技巧 13：HTML inline style 強迫顏色

<span style="color: red">紅色文字</span>

注意 GitHub README 不允許 style attribute，會被 sanitize 掉。

技巧 14：警告框（GitHub 2023+）

> [!NOTE]
> 一般提示

> [!TIP]
> 小技巧

> [!IMPORTANT]
> 重要資訊

> [!WARNING]
> 警告

> [!CAUTION]
> 危險

技巧 15：摺疊區段（Details）

<details>
<summary>點擊展開</summary>

隱藏內容寫這。可以是 markdown 也可以是 HTML。

</details>

技巧 16：縮排程式碼塊

4 個空白縮排等於 code block：

這是一段。

    def hello():
        print("indented code")

但 GFM 偏好三反引號方式。

3.6 圖表（特定平台）

技巧 17：Mermaid 圖（GitHub / GitLab / Obsidian 支援）

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
```

支援流程圖、序列圖、甘特圖、ER 圖、類別圖。

技巧 18：LaTeX 數學公式（GitHub 2022+）

inline： $E = mc^2$

block：
$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

3.7 寫作流程

技巧 19：YAML front matter（Jekyll、Hugo、Astro、Next.js content layer）

---
title: 文章標題
date: 2026-06-05
tags: [markdown, tutorial]
---

正文從這開始。

技巧 20：自動目錄（依工具）

VSCode 用 Markdown All in One plugin Cmd+Shift+P → Create Table of Contents。GitHub Issue / Wiki 自動產 TOC（H 標題）。

技巧 21：跨檔案連結（Obsidian / Notion）

[[其他筆記]]
[[其他筆記|顯示文字]]

技巧 22：標籤（Obsidian / Bear）

#javascript #tutorial #2026

3.8 跨平台陷阱

技巧 23：硬換行用兩個空白 + Enter

第一行  
第二行

行尾兩空白 = <br>。多數渲染器支援，少數不支援（直接寫 <br>）。

技巧 24：跳脫特殊字元

\* 這個星號不是斜體
\# 這個井字不是標題
\\ 反斜線本身

技巧 25：避免被 emoji

:smile: 在 GFM 渲染成 😀，但 CommonMark 維持字面。需要顯示字面時用 `:smile:` code 標記。

3.9 進階格式

技巧 26：上下標

H<sub>2</sub>O
X<sup>2</sup>

需要 HTML（CommonMark 無）。

技巧 27：高亮（GFM 不支援，Obsidian 支援）

==高亮文字==

GitHub 用 HTML：

<mark>高亮文字</mark>

技巧 28：鍵盤輸入

按 <kbd>Cmd</kbd> + <kbd>K</kbd> 開啟搜尋。

技巧 29：縮寫定義（Pandoc）

*[HTML]: HyperText Markup Language

HTML 是網頁標準。

游標移到 HTML 會顯示全名 tooltip。

技巧 30：metadata 註解

<!-- 這段不會顯示，只在原始碼可見 -->

可用於 TODO 標記、給 AI 看的指令。

4. 進階技巧

4.1 Pandoc 一鍵轉 PDF / DOCX

# Markdown → PDF（需 LaTeX）
pandoc input.md -o output.pdf

# Markdown → DOCX
pandoc input.md -o output.docx

# 套用樣板
pandoc input.md --reference-doc=template.docx -o output.docx

4.2 lint Markdown 規範性

npm i -g markdownlint-cli
markdownlint **/*.md

可在 CI 跑，確保所有 README 符合規範。

4.3 自動更新目錄（doctoc）

npm i -g doctoc
doctoc README.md

會在 <!-- START doctoc --> 與 <!-- END doctoc --> 之間插入目錄。

4.4 Markdown 寫作器選擇

工具 特色 適用
Obsidian 雙向連結、Plugin 多 個人知識庫
Notion 多人協作、DB 團隊 wiki
iA Writer 極簡 typography 長文寫作
Bear macOS / iOS 同步 行動裝置
VSCode 開發者整合 技術文件
Typora 所見即所得 大眾用戶

4.5 MDX：Markdown 中嵌入 React

Docusaurus、Astro、Next.js 使用：

import Chart from "./Chart";

# 我的部落格

<Chart data={...} />

Markdown 可以與 React 元件混用。

5. 常見錯誤與解法

錯誤 1：星號太多搞混斜體 / 粗體

症狀：***foo*** 渲染怪。 根因：三星號是斜體+粗體，部分渲染器解析不一。 解法：用 **_foo_** 明確分開。

錯誤 2：列表斷裂

症狀：兩段列表中間放一段文字，列表編號重置。 根因：Markdown 把空段視為列表結束。 解法：中間段落縮排對齊列表（4 spaces / 對應 1. 後 3 spaces）。

錯誤 3：HTML 被 sanitize 移除

症狀：寫 <div style="..."> 但 GitHub 不顯示樣式。 根因：GitHub 為了安全 sanitize <script> / style。 解法：能用 emoji / 普通 markdown 就用；非要 style 改 PDF 輸出。

錯誤 4：表格欄寬不一致

症狀：每列字數差很多，markdown 原始碼很醜。 根因：沒對齊。 解法：VSCode 用 Markdown Table Formatter plugin 一鍵對齊。

錯誤 5：圖片找不到

症狀：本地預覽正常，GitHub 上 broken image。 根因：相對路徑跑掉。 解法：圖片用 /images/xxx.png 絕對路徑，或統一放 assets/ 目錄。

6. 用 SuperTools 線上版完成相同任務

不想開 VSCode 就想預覽？打開 SuperTools Markdown 工具：

  • 即時雙欄預覽：左寫右看
  • GFM / CommonMark 切換：選對標準
  • Mermaid 渲染：嵌入流程圖即時顯示
  • 匯出：HTML / PDF / DOCX 一鍵下載
  • 複製 HTML：貼到 WordPress / 信件
  • TOC 自動產生：勾選後自動加目錄
  • 字數統計：含中文與英文 word count
  • 語法高亮：Prism.js 50+ 語言

工具完全 client-side，內容不會上傳，可放心貼公司內部文件。

實際使用流程：

  1. 開 supertools.tw/text/markdown
  2. 左側貼 README.md 原始碼
  3. 右側即時看渲染結果
  4. 點「Export HTML」貼到部落格

立即使用 SuperTools Markdown 工具：https://supertools.tw/text/markdown

7. 其他語言實作

Python（markdown 套件）

import markdown
html = markdown.markdown("# Hello\n\nWorld", extensions=["tables", "fenced_code"])

JavaScript（marked）

import { marked } from "marked";
const html = marked.parse("# Hello\n\nWorld");

Go（goldmark）

import "github.com/yuin/goldmark"
goldmark.Convert([]byte("# Hello"), &buf)

Rust（pulldown-cmark）

use pulldown_cmark::{Parser, html};
let parser = Parser::new("# Hello");
let mut html_buf = String::new();
html::push_html(&mut html_buf, parser);

Bash（pandoc）

echo "# Hello" | pandoc -f markdown -t html

8. FAQ

Q1：Markdown 跟 reStructuredText 哪個好？ Markdown 較流行、學習曲線低。reStructuredText 較嚴謹（Python 文件用）。一般優先 Markdown。

Q2：要選 CommonMark 還是 GFM？ 個人筆記 / GitHub README 用 GFM；學術 / 跨工具用 CommonMark。

Q3：HTML 可以混進 Markdown 嗎？ 原則上可以，但渲染器可能 sanitize（GitHub 移除 <script> / style）。

Q4：Markdown 怎麼做密碼保護的文件？ Markdown 本身無此功能。導出 PDF 後用 PDF 密碼，或用 Notion / Confluence 等平台級權限。

Q5：多人協作 Markdown 怎麼解決衝突？ 用 Git 管理。重大格式改動分開 commit（diff 比較乾淨）。

9. 實戰案例研究

案例 1：README 在 npm 與 GitHub 渲染差異

某開源 lib 的 README 在 GitHub 顯示完美：表格漂亮、warning 框 highlight、Mermaid 圖正常。發布到 npm 後變得殘破：

  • Warning > [!NOTE] 變成普通 blockquote
  • Mermaid code block 純文字顯示
  • 表格部分對齊跑掉

根因：npm 只支援 CommonMark 子集，不支援 GFM 進階語法。

修法：

  1. README.md 用 CommonMark 子集（給 npm 看）
  2. 額外寫 README-github.md 用 GFM 進階語法
  3. CI 自動同步基本內容、進階語法只放 GitHub 版

教訓：跨平台 README 用最小公因數語法。

案例 3：Notion 匯出 Markdown 撞奇怪 escape

某團隊把 Notion 文件匯出 Markdown 給 Hugo 部落格。Notion 對所有 _ 做了 escape：

some\_variable\_name

Hugo 渲染時保留反斜線，網頁顯示變 some\_variable\_name。

修法：

# 把所有 \_ 還原 _
sed -i 's/\\_/_/g' content/posts/*.md

教訓：跨工具 Markdown 流轉時需 post-process。

案例 3：GitHub Action 用 Mermaid 自動產架構圖

某團隊把系統架構用 Mermaid 寫在 docs/ARCHITECTURE.md，每次 PR 更新架構必同步圖。原本要重畫圖（draw.io / Lucid）很麻煩。

改用 Mermaid + GitHub Action：

- name: Render Mermaid to PNG
  uses: mermaidjs/mermaid-cli-action@v1
  with:
    files: "docs/ARCHITECTURE.md"

PR 自動 render 出最新架構圖，版本控制內建 diff。

教訓：圖即代碼，可 diff、可版控。

10. 結論 + 延伸閱讀

Markdown 是技術寫作的瑞士刀。掌握本文 30 個技巧後，幾乎所有寫作場景（README、Issue、部落格、筆記、技術文件）都能高效處理。下次寫文件前，先到 SuperTools 線上預覽工具實驗版面，避免 push 到 GitHub 才發現渲染變形。三條黃金法則：跨平台用最小公因數、結構圖用 Mermaid 取代外部工具、front matter 把 metadata 留在 markdown 內。

延伸閱讀：