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>

  目前支持：支付宝、微信支付、银行卡。

</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>