Markdown 折疊內容教學

Markdown 本身沒有原生的折疊語法。但幾乎所有主流 Markdown 渲染器都支援內嵌 HTML，我們可以用 HTML5 的 <details> 和 <summary> 標籤來建立可折疊的內容區域。這個方法在 GitHub README、GitLab Wiki、Obsidian 等平台上廣泛使用，效果穩定可靠。

基本語法：`<details>` + `<summary>`

<details> 是 HTML5 的原生標籤，用來建立一個可折疊的部件。<summary> 是它的子元素，顯示為可點擊的標題列。點擊後會展開或收起 <details> 內的其他內容。

<details>
  <summary>點擊展開查看詳情</summary>

  這裡是隱藏的內容。展開後才能看到。

</details>

渲染效果：點擊「點擊展開查看詳情」這個標題列，下方的內容就會出現；再點一次就會收回去。

關鍵要點

<details> 是外層容器，定義折疊區域
<summary> 是點擊的標題文字，始終可見
<summary> 之後、</details> 之前的所有內容預設隱藏
<summary> 標籤後面必須空一行，否則裡面的 Markdown 格式（標題、列表、程式碼區塊等）不會被正確渲染

預設展開狀態

給 <details> 標籤加上 open 屬性，折疊區域在頁面載入時就會預設展開：

<details open>
  <summary>這段內容預設展開</summary>

  頁面載入時就能看到這些文字。
  點擊標題列可以收起來。

</details>

open 是一個布林屬性——寫上就生效，不需要賦值。這在 FAQ 頁面或者需要「先展示再收起」的場景中很實用。

在折疊區域中使用 Markdown 格式

折疊區域內可以正常使用 Markdown 語法，但有一個前提條件：<summary> 標籤後面必須空一行。這行空白告訴 Markdown 渲染器「從這裡開始解析 Markdown 格式」。

<details>
  <summary><b>安裝步驟</b></summary>

  ## 前置要求

  - Node.js 18 或更高版本
  - Git

  ## 安裝命令

  ```bash
  git clone https://github.com/example/repo.git
  cd repo
  npm install


支援的 Markdown 格式包括：

| 格式 | 是否支援 | 範例 |
|------|----------|------|
| 標題 `##` | 支援 | `## 子標題` |
| 列表 `-` | 支援 | `- 列表項` |
| 粗體 `**` | 支援 | `**粗體文字**` |
| 程式碼區塊 `` ``` `` | 支援 | 三反引號包裹 |
| 圖片 `![]()` | 支援 | `![截圖](url)` |
| 連結 `[]()` | 支援 | `[文件](url)` |
| 表格 | 支援 | 標準表格語法 |
| 任務列表 `- [ ]` | 支援 | GitHub 風格任務列表 |

如果發現折疊區內的 Markdown 沒有被渲染（顯示為原始文字），99% 的情況是忘了在 `<summary>` 後面空一行。

## 巢狀折疊

`<details>` 標籤支援巢狀，可以在一個折疊區域內再放一個折疊區域：

```markdown
<details>
  <summary>第一章：入門</summary>

  這是第一章的概述內容。

  <details>
    <summary>1.1 環境搭建</summary>

    Node.js 安裝步驟...

  </details>

  <details>
    <summary>1.2 第一個專案</summary>

    建立專案的詳細步驟...

  </details>

</details>

巢狀折疊在技術文件中特別好用——把大章節折疊起來，每個章節裡再折疊子章節，讀者可以按需展開感興趣的部分，不用在長文件中來回捲動。

注意：巢狀層數建議不要超過 3 層。層數太多會讓縮排變得很深，程式碼可讀性下降，讀者操作也不方便。

`<summary>` 中使用格式

<summary> 標籤內可以使用 HTML 格式來增強標題的顯示效果：

<!-- 加粗標題 -->
<details>
  <summary><b>重要提示</b></summary>
  內容...
</details>

<!-- 帶圖示的標題 -->
<details>
  <summary>💡 實用技巧</summary>
  內容...
</details>

<!-- 帶程式碼的標題 -->
<details>
  <summary><code>npm install</code> 安裝說明</summary>
  內容...
</details>

純 Markdown 格式（如 **粗體**）在 <summary> 標籤內不一定被所有渲染器支援，所以建議用 HTML 標籤（<b>、<code> 等）來格式化 summary 的文字。

實際應用場景

折疊內容在以下場景中特別有用：

README 中的詳細說明

## 快速開始

一行命令安裝：`npm install my-lib`

<details>
  <summary>完整安裝選項</summary>

  | 參數 | 說明 | 預設值 |
  |------|------|--------|
  | `--global` | 全域安裝 | false |
  | `--save-dev` | 作為開發依賴 | false |
  | `--registry` | 指定鏡像來源 | npm 官方 |

</details>

FAQ 常見問題

## 常見問題

<details>
  <summary>如何重設密碼？</summary>

  1. 點擊登入頁面的「忘記密碼」
  2. 輸入註冊信箱
  3. 查收重設郵件
  4. 點擊郵件中的連結設定新密碼

</details>

<details>
  <summary>支援哪些付款方式？</summary>

  目前支援：信用卡、PayPal、銀行轉帳。

</details>

長程式碼和日誌

<details>
  <summary>查看完整日誌輸出</summary>

  ```log
  2024-01-15 10:00:01 [INFO] Server started on port 3000
  2024-01-15 10:00:02 [INFO] Database connected
  2024-01-15 10:00:03 [WARN] Cache miss for key: user_settings
  ...（數百行日誌）


### Changelog 更新日誌

```markdown
## 更新日誌

<details>
  <summary>v2.0.0 (2024-01-15)</summary>

  ### 新功能
  - 新增暗色模式
  - 支援多語言

  ### 修復
  - 修復登入頁面閃爍問題

</details>

<details>
  <summary>v1.9.0 (2024-01-01)</summary>

  ### 新功能
  - 新增匯出功能

</details>

不同平台的相容性

<details> / <summary> 是 HTML5 標準標籤，在支援內嵌 HTML 的 Markdown 渲染器上基本都能正常運作：

平台	支援情況	說明
GitHub	完全支援	README、Issue、PR、Wiki 均支援，官方文件推薦此用法
GitLab	完全支援	基於 CommonMark 渲染器，支援內嵌 HTML
Obsidian	完全支援	原生支援 details/summary
Typora	完全支援	基於 Chromium 渲染，完全支援 HTML5
VS Code 預覽	完全支援	內建預覽基於 WebView
Notion	不支援	不接受自訂 HTML
Discord	不支援	不支援 HTML 標籤
Slack	不支援	不支援 HTML 標籤
Hugo	需設定	預設可能過濾 HTML，需設定 `markup.goldmark.renderer.unsafe = true`
Jekyll	支援	透過 Kramdown 解析器支援
MkDocs	支援	基於 Python-Markdown，支援 HTML

GitHub 的特殊說明

GitHub 是 <details> + <summary> 在 Markdown 中使用最廣泛的平台。GitHub 官方文件專門介紹了這個用法，稱之為 "collapsed sections"。在 GitHub 的 README.md、Issue 留言、Pull Request 描述、GitHub Wiki 中都可以使用。

Hugo 靜態網站的處理

Hugo 預設使用的 Goldmark 渲染器會過濾掉原始 HTML。要讓 <details> 標籤生效，需要在設定檔中開啟：

[markup.goldmark.renderer]
unsafe = true

或者使用 Hugo shortcode 來封裝 <details> 標籤：

<!-- layouts/shortcodes/details.html -->
<details{{ with .Get "open" }} open{{ end }}>
  <summary>{{ .Get "title" }}</summary>
  {{ .Inner | markdownify }}
</details>

然後在 Markdown 中使用：

{{</* details title="點擊展開" */>}}

隱藏的內容

{{</* /details */>}}

樣式自訂

在支援自訂 CSS 的環境（Obsidian、Typora、靜態網站）中，可以給 <details> 新增樣式：

<details style="border: 1px solid #ddd; border-radius: 4px; padding: 8px;">
  <summary><b>帶樣式的折疊區域</b></summary>

  這個折疊區域有邊框和圓角。

</details>

或者在 CSS 中統一設定：

details {
  border: 1px solid #e0e0e0;
  border-radius: 6px;
  padding: 12px;
  margin: 16px 0;
  background: #fafafa;
}

details summary {
  cursor: pointer;
  font-weight: bold;
  color: #333;
}

details summary:hover {
  color: #0066cc;
}

注意：GitHub 會過濾掉 style 屬性，所以在 GitHub 上無法自訂折疊區域的樣式。

常見問題

Markdown 有原生的折疊語法嗎？

沒有。Markdown 的設計理念是關注內容結構，不提供互動功能。折疊內容屬於互動行為，需要用 HTML 來實現。

為什麼折疊區內的 Markdown 沒有被渲染？

最常見的原因是 <summary> 標籤後面沒有空一行。在 <summary>...</summary> 之後、實際內容之前，必須有一個空行，Markdown 渲染器才能正確解析後續的格式。

GitHub 上能用折疊功能嗎？

完全可以。GitHub 官方推薦使用 <details> 和 <summary> 標籤來建立折疊區域，在 README、Issue、PR 描述中都能正常使用。但 GitHub 不支援自訂折疊區域的樣式（style 屬性會被過濾）。

可以無限巢狀折疊嗎？

技術上可以，但不建議超過 3 層。過多的巢狀會導致縮排過深、程式碼難以維護，讀者也不方便操作。大多數場景 1-2 層就足夠了。

`<details>` 和 `<summary>` 是標準 HTML 嗎？

是的。它們是 HTML5 規範中的標準元素，所有現代瀏覽器都支援。MDN 文件中有完整的 details 元素和 summary 元素的規範說明。

基本語法：<details> + <summary>