如何在 Markdown 做摺疊區段：details 與 summary 標籤。

語法

可摺疊區段就是一個普通的 HTML 元素：<details> 是容器，<summary> 是可點選的那一行，summary 之後的所有內容會一直隱藏，直到讀者點選。開合由瀏覽器（或 Markdown 應用程式的網頁檢視）完成，所以不需要指令碼，也沒有額外的語法要學。

<details>
<summary>Click to expand</summary>

Hidden text goes here.

</details>

收合時，讀者會看到一個小三角形和 Click to expand 這幾個字。點選後三角形會轉向並顯示文字。GitHub 的 README、issue 與 pull request 留言，也是用同樣的做法放長篇記錄和選用的備註。

空行規則

<details> 區塊中的 Markdown，只有在與 HTML 標籤之間隔著空行時才會被處理。這是 CommonMark 讀取 HTML 區塊的方式：它會持續到下一個空行，並以原始 HTML 傳遞。沒有空行的話，你的 **bold** 和清單會以原樣字元顯示。

<details>
<summary>Broken</summary>
- this list is not turned into a list
</details>

<details>
<summary>Works</summary>

- this one is a list

</details>

在 </summary> 之後與 </details> 之前各留一個空行。summary 那一行本身也是 HTML，所以在那裡請用 <b>bold</b> 或 <code>code</code>，不要用 Markdown。

預設展開

加上 open 屬性，區段就會以展開狀態開始。讀者仍然可以把它收合。

<details open>
<summary>Prerequisites</summary>

Node 20 or later.

</details>

請節制使用：一個全部預設展開的頁面沒有理由做成可摺疊，而全部預設收合的頁面則會藏起有用的部分。好的原則是讓答案保持可見，把佐證收起來，例如長長的輸出、完整的設定檔或邊界情況清單。

範例：程式碼、巢狀與長清單

區段中的程式碼區塊和其他 Markdown 一樣需要空行：

<details>
<summary>Full config</summary>

```json
{ "retries": 3, "timeout": 30 }
```

</details>

區段可以巢狀。要的話可以縮排內層，但重點是空行：

<details>
<summary>Troubleshooting</summary>

<details>
<summary>The app does not start</summary>

Check the log in the console.

</details>

</details>

以下是讀者看到的區段，點選之前保持收合：

Show the full log

Everything here is hidden until the title is clicked.

何時使用可摺疊區段

當讀者不需要打開區段就能完成任務時，摺疊才有價值。適合的內容包括長長的指令輸出、完整的設定檔、選項表、舊版本的變更記錄，或罕見問題的疑難排解步驟。多數讀者需要的簡短備註則應該放在明處。

區段也是把長篇貼上的記錄放進 bug 回報或 pull request 描述的整齊做法：讀者先看到出了什麼問題的摘要，需要時才打開記錄。請給 summary 一個明確的標題，例如 Build log (412 lines)，讓讀者在點選前就知道裡面是什麼。

常見錯誤

• 沒有空行。裡面的文字會顯示原始的 Markdown。請在 summary 之後與結尾標籤之前加上空行。
• 在 summary 中使用 Markdown。請改用 HTML 標籤。
• 漏了結尾標籤。下面的所有內容都會留在區段裡面。
• 會移除 HTML 的應用程式。有些渲染器會移除不信任的標籤，這時文字就只是直接顯示。如果區段必須到處都能用，請在實際閱讀的地方測試。
• 在 summary 中放標題。多數應用程式的大綱不會顯示該標題。請把標題放在區段上方。

收合的文字仍在檔案中，所以搜尋與 diff 看得到，但從不點選的讀者看不到。請不要隱藏任何重要的內容，例如警告。

看它運作

想檢查區段，請在能渲染 HTML 的閱讀器中開啟檔案。DotMD 會把 <details> 顯示為點選即可展開的區段，裡面的 Markdown 也會被格式化；在 DotMD Editor 中，Insert → Collapsible Section 會替你寫好標籤。閱讀免費。

關於 Markdown 摺疊區段的常見問題

更多問題