折叠功能Bug修复总结

2026/9/13大约 5 分钟

折叠功能Bug修复总结

🐛 问题描述

症状

在 内容折叠功能使用示例.md 文章中，"API文档示例" 折叠块展开后，不仅显示预期的 API 文档内容，还将文章详情页底部的其他内容（甚至右侧栏的内容）都包含进来了。

具体表现

{{< collapse "API文档示例" >}}

#### getUserInfo 函数
...（预期内容）

{{< /collapse >}}

展开后显示的内容包括：

✅ 预期的 API 文档内容
❌ 文章底部的其他内容
❌ 右侧栏的组件内容（复制了一遍）
❌ 页脚等其他页面元素

🔍 问题原因

根本原因

collapse.html shortcode 模板中使用了 {{ .Inner }} 直接输出内容，而没有使用 {{ .Inner | markdownify }} 进行 Markdown 渲染。

技术分析

问题代码（修复前）

<div class="collapse-inner">
  {{ .Inner }}
</div>

为什么会出问题？

未经处理的原始内容：{{ .Inner }} 直接输出 shortcode 中间的原始文本，不进行任何 Markdown 解析。
HTML 标签解析错误：当内容中包含复杂的 Markdown 语法（如代码块、标题、列表等）时，Hugo 可能会错误地将后续的 HTML 内容也识别为 shortcode 的一部分。
标签匹配失败：由于没有正确的 Markdown → HTML 转换，浏览器在尝试匹配 HTML 标签时可能会产生混乱，导致将页面后续的内容也包含进折叠块。

具体触发条件

折叠块中包含多个代码块
折叠块中包含 Markdown 标题（####）
折叠块中混合了多种 Markdown 元素
内容较长且结构复杂

为什么其他折叠块正常？

在同一篇文章中，其他简单的折叠块（如只包含单个代码块或纯文本）没有出现问题，是因为：

内容相对简单
HTML 结构不复杂
没有多层嵌套的 Markdown 元素

但 "API文档示例" 这个折叠块包含了：

多个 Markdown 标题（####）
多个代码块（```）
列表
粗体文本
混合内容

这种复杂度触发了 Hugo 的解析问题。

✅ 修复方案

修改文件

themes/demius/layouts/shortcodes/collapse.html

修复代码

<div class="collapse-inner">
  {{ .Inner | markdownify }}
</div>

为什么这样修复？

markdownify 函数的作用：

正确解析 Markdown：将 Markdown 语法转换为 HTML
生成完整的 HTML 结构：确保标签正确闭合
防止内容溢出：明确内容边界，避免误包含页面其他部分

修复后的处理流程：

用户 Markdown 输入
    ↓
Hugo 解析 shortcode
    ↓
提取 .Inner 内容
    ↓
使用 markdownify 渲染 ← 关键步骤
    ↓
生成完整的 HTML
    ↓
插入到折叠块容器中
    ↓
正确显示

🔧 其他相关修复

检查其他 Shortcode

同时检查了其他可能有类似问题的 shortcode：

✅ 已正确使用 `markdownify` 的：

timeline-item.html：{{ .Inner | markdownify }}
tab.html：{{ .Inner | markdownify }}

✅ 不需要 `markdownify` 的（容器型）：

timeline.html：包含其他 shortcode，不是直接 Markdown
tabs.html：包含其他 shortcode，不是直接 Markdown

📝 文档更新

更新的文档

collapse-guide.md
- 添加 "完整的 Markdown 渲染支持" 特性说明
- 新增 "常见问题" 章节，包含此 bug 的说明
- 添加 "更新历史" 记录 v2.4.0 修复

更新历史条目

### v2.4.0 (2025-10-28)
- 🐛 修复：折叠块包含额外页面内容的问题
- ✨ 改进：使用 `markdownify` 正确渲染 Markdown 内容
- 📝 更新：完善文档和故障排查指南

🧪 验证方法

1. 清理并重新构建

hugo --cleanDestinationDir
hugo server

2. 测试场景

访问 内容折叠功能使用示例.md 文章，展开 "API文档示例" 折叠块，检查：

✅ 应该显示：

getUserInfo 函数说明
语法示例
参数说明
返回值说明
示例代码
错误处理说明

❌ 不应该显示：

文章底部的其他内容
页脚
侧边栏内容
其他折叠块的内容

3. 其他测试用例

测试其他包含复杂内容的折叠块：

"数据库配置" 折叠块（多个代码块）
"v2.0.0 更新日志" 折叠块（列表+Emoji）
嵌套折叠块

🎯 预期效果

修复前

┌─────────────────────────────┐
│ API文档示例 [展开]          │
├─────────────────────────────┤
│ #### getUserInfo 函数        │
│ 获取用户信息                │
│ **语法**：                  │
│ ```javascript               │
│ getUserInfo(userId)         │
│ ```                         │
│ ... (正常内容)              │
│                             │
│ === 意外包含的内容 ===      │
│ [文章评论区]                │
│ [相关文章]                  │
│ [侧边栏组件-复制]           │  ← 不应该出现
│ [页脚]                      │  ← 不应该出现
└─────────────────────────────┘

修复后

┌─────────────────────────────┐
│ API文档示例 [展开]          │
├─────────────────────────────┤
│ #### getUserInfo 函数        │
│ 获取用户信息                │
│ **语法**：                  │
│ ```javascript               │
│ getUserInfo(userId)         │
│ ```                         │
│ **参数**：                  │
│ - userId: 用户ID            │
│ **返回值**：                │
│ - Promise<Object>           │
│ **示例**：                  │
│ ```javascript               │
│ const user = ...            │
│ ```                         │
│ **错误处理**：              │
│ - 用户不存在: 返回null      │
│ - 网络错误: 抛出Error       │
└─────────────────────────────┘

💡 技术要点

Hugo Shortcode 最佳实践

直接包含 Markdown 内容的 shortcode：
```
{{ .Inner | markdownify }}
```
- 用于：内容折叠、提示框、引用块等
包含其他 shortcode 的容器型 shortcode：
```
{{ .Inner }}
```
- 用于：选项卡容器、时间线容器等
需要原始 HTML 的 shortcode：
```
{{ .Inner | safeHTML }}
```
- 用于：自定义 HTML 组件、嵌入代码等