Markdown 實戰指南

CommonMark 核心語法的最佳實踐、常見格式錯誤與修正方式

Overview##

Markdown 的設計哲學是「原始碼本身就應該具備可讀性」。John Gruber 在 2004 年創造 Markdown 時，目標是讓純文字檔案即使不經渲染也能輕鬆閱讀。

但正因為語法寬鬆，同一種效果常常有多種寫法，導致：

不同解析器的行為不一致
格式「看起來對」但渲染結果錯誤
團隊協作時風格混亂

CommonMark 在 2014 年誕生，為 Markdown 建立了明確的規範。本文以 CommonMark 為基準，整理實務上最常踩到的坑與推薦寫法。

Note

本文假設你已熟悉 Markdown 基本語法。重點放在「為什麼這樣寫更好」而非「怎麼寫」。

Common Pitfalls##

Heading###

問題一：沒有空行隔開

<!-- ❌ 某些解析器不會將這行視為 heading -->

Some paragraph text.

## Heading

<!-- ✅ heading 前後都留空行 -->

Some paragraph text.

## Heading

問題二：層級跳躍

<!-- ❌ 從 h2 直接跳到 h4 -->

## Architecture

#### Component A

<!-- ✅ 逐級遞進 -->

## Architecture

### Component A

規則	說明
每份文件只有一個 `#`	作為文件標題，部分系統會自動產生
Heading 前後留空行	確保所有解析器正確辨識
不跳級	`h2 → h3 → h4`，不要跳過層級
使用 ATX 風格	`## Heading` 而非 `Heading\n------`

Line Break & Paragraph###

這是 Markdown 最反直覺的設計之一：

<!-- ❌ 這不會產生換行，會被合併成同一段 -->

第一行
第二行

<!-- ✅ 方法一：尾部兩個空格（trailing spaces） -->

第一行··
第二行

<!-- ✅ 方法二：空行分段（推薦） -->

第一行

第二行

Warning

Trailing spaces 在大多數編輯器中不可見，且容易被 formatter 自動移除。建議改用空行分段，或在必須 soft break 的場景使用 <br>。

List###

清單是格式錯誤的重災區：

問題一：縮排不一致

<!-- ❌ 混用 2 格和 4 格縮排 -->

- Item A
  - Sub item
    - Sub sub item

<!-- ✅ 統一使用 2 格或 4 格（CommonMark 建議清單內容對齊標記後的文字） -->

- Item A
  - Sub item
    - Sub sub item

問題二：清單項目內的多段落

<!-- ❌ 缺少縮排，第二段會跳出清單 -->

1. First item

Second paragraph of first item.

<!-- ✅ 後續段落需縮排對齊 -->

1. First item

   Second paragraph of first item.

問題三：混用有序與無序標記

<!-- ❌ 在同一層級混用 -->

- Item A

* Item B

- Item C

<!-- ✅ 統一使用 - -->

- Item A
- Item B
- Item C

Code Block###

<!-- ❌ 沒有指定語言，無法觸發 syntax highlighting -->

const x = 1;


<!-- ✅ 加上語言標識 -->
```javascript
const x = 1;


> [!TIP]
> 行內程式碼如果包含反引號，用雙反引號包裹：`` `code` `` 寫成 ``` `` `code` `` ```。

### Link & Image

```markdown
<!-- ❌ 裸網址不一定會被解析為連結 -->
https://example.com

<!-- ✅ 使用明確的連結語法 -->
[Example](https://example.com)

<!-- ❌ 圖片缺少 alt text -->
![](image.png)

<!-- ✅ 提供有意義的描述 -->
![系統架構圖](image.png)

對於重複使用的連結，建議使用 reference-style：

<!-- ✅ Reference link：將 URL 集中管理 -->

請參考 [CommonMark 規範][commonmark] 和 [MDN 文件][mdn]。

[commonmark]: https://commonmark.org/
[mdn]: https://developer.mozilla.org/

Blockquote###

<!-- ❌ 多段引用中斷 -->

> First paragraph.

> Second paragraph.

<!-- ✅ 連續引用用 > 空行銜接 -->

> First paragraph.
>
> Second paragraph.

Best Practices##

檔案結構建議###

一份好的 Markdown 文件應該遵循一致的結構：

# Document Title

Brief introduction paragraph.

## Section 1

Content with proper spacing.

### Subsection 1.1

Details here.

## Section 2

More content.

## References

- [Link 1](url)
- [Link 2](url)

Tip

每個 section 之間保持一個空行。檔案結尾保留一個空行（POSIX 慣例）。

語意化標記###

目的	推薦寫法	避免寫法
強調	`粗體`	`__粗體__`
斜體	`斜體`	`_斜體_`
程式碼	`code`	不標記
刪除線	`~~刪除~~`	HTML `<del>`
分隔線	`---`	`***` 或 `___`

選定一種風格後在整個專案中保持一致，比選哪一種更重要。

表格可讀性###

<!-- ❌ 難以閱讀的表格 -->

| Name | Type   | Required |
| ---- | ------ | -------- |
| id   | string | yes      |
| name | string | no       |

<!-- ✅ 對齊欄位，增加可讀性 -->

| Name | Type   | Required |
| ---- | ------ | -------- |
| id   | string | yes      |
| name | string | no       |

特殊字元跳脫###

Markdown 中的特殊字元需要反斜線跳脫：

<!-- 這些字元需要跳脫 -->

\* \# \[ \] \( \) \` \\ \- \. \! \| \> \_

<!-- 常見場景：版本號的星號 -->
<!-- ❌ -->

Version 2.0 supports \* wildcard matching.

<!-- ✅ -->

Version 2.0 supports \* wildcard matching.

Linting##

手動維護格式一致性不現實，推薦使用 markdownlint：

# 安裝
pnpm add -D markdownlint-cli2

# 執行檢查
pnpm markdownlint-cli2 "**/*.md"

常用規則配置 .markdownlint.yaml：

# 禁用行長限制（文件型內容通常不需要）
MD013: false

# 允許多個 heading 使用相同文字
MD024:
  siblings_only: true

# 強制使用 - 作為無序清單標記
MD004:
  style: dash

# 強制使用 ATX 風格 heading
MD003:
  style: atx

Note

大多數編輯器都有 markdownlint 插件，可以在撰寫時即時提示格式問題。VS Code 搜尋 markdownlint 即可安裝。

Quiz##

Multiple Select

在 CommonMark 中，以下哪種寫法可以正確產生換行？

Single Choice

Markdown heading 的正確使用方式是？

Multiple Select

以下哪些是 Markdown 最佳實踐？

Code Challengepython

寫一個函式 extract_headings(markdown)，從 Markdown 文字中提取所有 ATX 風格的 heading，回傳格式為 (level, text) 的 list。

Ctrl+Enter to run

Summary##

Heading 前後留空行、不跳級、使用 ATX 風格
換行用空行分段，避免依賴 trailing spaces
清單縮排統一，多段落內容需對齊縮排
Code block 一律標注語言，圖片一律填寫 alt text
重複連結使用 reference-style 集中管理
選定風格後保持一致——**粗體**、*斜體*、- 清單、--- 分隔線
導入 markdownlint 自動化格式檢查

留言 (0)

登入後即可留言