From 20f24832572cd5b142db7fe342117e2193585236 Mon Sep 17 00:00:00 2001
From: nanhaoluo <3075912108@qq.com>
Date: Sat, 24 Jan 2026 20:52:20 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20Mermaid=20?=
=?UTF-8?q?=E4=BF=AE=E5=A4=8D=E6=80=BB=E7=BB=93=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
docs/mermaid-fix-summary.md | 213 ++++++++++++++++++++++++++++++++++++
1 file changed, 213 insertions(+)
create mode 100644 docs/mermaid-fix-summary.md
diff --git a/docs/mermaid-fix-summary.md b/docs/mermaid-fix-summary.md
new file mode 100644
index 0000000..e8a662d
--- /dev/null
+++ b/docs/mermaid-fix-summary.md
@@ -0,0 +1,213 @@
+# Mermaid 容器语法修复总结
+
+## 修复的问题
+
+### 问题 1: 代码高亮干扰 Mermaid 渲染
+- **症状**: 使用 ` ```mermaid ` 标记时，代码高亮会处理 mermaid 代码块，导致渲染冲突
+- **修复**: 在 `highlightJsRender()` 函数中添加检查，跳过 `language-mermaid` 和 `mermaid` 类的代码块
+- **Commit**: 0ac5794
+
+### 问题 2: 容器语法空行导致内容截断
+- **症状**: 容器语法 `::: mermaid ... :::` 中的空行导致内容被截断
+- **修复**: 修改 `extractContainerContent()` 函数，不使用 `trim()` 删除空行
+- **Commit**: 0ac5794
+
+### 问题 3: WP-Markdown document.write 重复输出
+- **症状**: WP-Markdown 生成 `flowchart TD ...
`，script 后面有重复代码
+- **修复**: 在 `extractMermaidCode()` 中提取完 script 内容后立即 `scriptTag.remove()`
+- **Commit**: b6d9f8c
+
+### 问题 4: 容器语法跨元素收集失败
+- **症状**: 容器语法遇到空行时，WP-Markdown 将内容分割成多个元素，只提取到第一个元素
+- **修复**: 重写 `detectContainerBlocks()` 和 `extractContainerContent()`，支持跨多个兄弟元素收集内容
+- **Commit**: b6d9f8c
+
+### 问题 5: 换行符丢失 ⭐（核心问题）
+- **症状**:
+ - 流程图渲染失败，错误显示 `flowchart TDStart`（`TD` 和 `Start` 之间缺少换行）
+ - 箭头符号被转换成全角 `–>` 而不是 `-->`
+- **根本原因**:
+ - WP-Markdown 将每一行代码包裹在 `` 标签中
+ - 行内换行使用 `
` 标签表示
+ - 使用 `textContent` 或 `innerText` 提取时，`
` 标签被忽略或转换为空格
+ - 导致多行代码被合并成一行，Mermaid 语法解析失败
+- **修复**:
+ - 新增 `htmlToText()` 辅助函数，将 `
` 标签转换为换行符
+ - 改进 `extractContainerContent()` 函数，使用 `innerHTML` 而不是 `textContent`
+ - 调用 `htmlToText()` 正确处理 HTML 结构
+- **Commit**: b4ba37a
+
+## 技术细节
+
+### WP-Markdown 生成的 HTML 结构
+
+```html
+
::: mermaid
+flowchart TD
+ Start([用户提交评论]) --> PreProcess[预处理]
+ PreProcess --> CheckEnabled{启用 AI 检测?}
+:::
+```
+
+### htmlToText() 函数
+
+```javascript
+htmlToText(html) {
+ // 将
和
转换为换行符
+ let text = html.replace(//gi, '\n');
+ // 移除其他 HTML 标签
+ text = text.replace(/<[^>]+>/g, '');
+ // 解码 HTML 实体
+ text = text
+ .replace(/ /g, ' ')
+ .replace(/</g, '<')
+ .replace(/>/g, '>')
+ .replace(/&/g, '&')
+ .replace(/"/g, '"')
+ .replace(/'/g, "'");
+ return text;
+}
+```
+
+### 提取流程
+
+```
+1. 检测到 ::: mermaid 开始标记
+2. 提取 innerHTML（包含
标签）
+ 原始: "::: mermaid
flowchart TD
Start --> End
:::"
+3. 使用 htmlToText() 转换
+ 结果: "::: mermaid\nflowchart TD\nStart --> End\n:::"
+4. 移除开始和结束标记
+ 结果: "flowchart TD\nStart --> End"
+5. 创建容器元素存储完整代码
+```
+
+## 测试验证
+
+### 测试文件
+- `tests/test-mermaid-fixes.html` - 基础功能测试
+- `tests/test-mermaid-newline.html` - 换行符测试
+- `tests/test-ai-comment-flow.md` - 复杂流程图测试（100+ 节点）
+
+### 测试用例
+
+#### 1. 简单流程图
+```markdown
+::: mermaid
+flowchart TD
+ A[开始] --> B[处理]
+ B --> C[结束]
+:::
+```
+
+#### 2. 复杂流程图（AI 评论审核）
+- 包含 100+ 个节点
+- 包含多行文本（`
` 标签）
+- 包含箭头符号（`-->`, `-->`）
+- 包含样式定义（`style` 语句）
+
+#### 3. 带样式的流程图
+```markdown
+::: mermaid
+flowchart LR
+ A[开始] --> B[处理]
+ B --> C[结束]
+ style A fill:#e1f5e1,stroke:#2e7d32
+ style C fill:#ffe1e1,stroke:#c62828
+:::
+```
+
+### 预期结果
+- ✅ 所有换行符正确保留
+- ✅ 箭头符号不被转换
+- ✅ 多行文本正确显示
+- ✅ 样式定义正确应用
+- ✅ 复杂流程图正确渲染
+
+## Git 提交历史
+
+```
+0ac5794 - fix: 修复代码高亮和容器语法的两个关键问题
+b6d9f8c - fix: 修复容器语法和 WP-Markdown 的两个关键问题
+b4ba37a - fix: 修复 Mermaid 容器语法换行符丢失问题
+759804d - docs: 更新 Mermaid 使用指南和添加换行符测试页面
+```
+
+## 影响范围
+
+### 修改的文件
+- `argontheme.js` - 核心修复代码
+- `docs/mermaid-usage-guide.md` - 使用指南
+- `tests/test-mermaid-fixes.html` - 测试页面
+- `tests/test-mermaid-newline.html` - 换行符测试
+- `tests/test-ai-comment-flow.md` - 复杂流程图测试
+
+### 影响的功能
+- ✅ Markdown 容器语法（`::: mermaid ... :::`）
+- ✅ WP-Markdown 格式（``）
+- ✅ 标准格式（``, `
`）
+- ✅ 代码高亮（排除 mermaid 代码块）
+
+### 向后兼容性
+- ✅ 完全向后兼容
+- ✅ 不影响现有功能
+- ✅ 支持所有现代浏览器
+
+## 性能影响
+
+- **DOM 操作**: 使用 `innerHTML` 和正则替换，性能影响可忽略
+- **内存占用**: 无显著增加
+- **渲染速度**: 无影响
+
+## 安全性
+
+- ✅ 只处理 Mermaid 代码块，不执行任何脚本
+- ✅ HTML 实体正确解码
+- ✅ 无 XSS 风险
+
+## 调试支持
+
+- 添加详细的 `console.log` 日志
+- 支持调试模式（主题设置中开启）
+- 错误时显示友好提示
+
+## 后续优化建议
+
+1. **支持更多容器语法**
+ - `::: warning` - 警告框
+ - `::: tip` - 提示框
+ - `::: danger` - 危险框
+
+2. **性能优化**
+ - 缓存已处理的代码块
+ - 使用 IntersectionObserver 延迟渲染
+
+3. **测试覆盖**
+ - 添加单元测试
+ - 添加集成测试
+ - 添加性能测试
+
+4. **文档完善**
+ - 添加更多示例
+ - 添加常见问题解答
+ - 添加故障排除指南
+
+## 相关资源
+
+- [Mermaid 官方文档](https://mermaid.js.org/)
+- [Mermaid Live Editor](https://mermaid.live/)
+- [VuePress 容器语法](https://vuepress.vuejs.org/guide/markdown.html#custom-containers)
+- [CommonMark 规范](https://commonmark.org/)
+
+## 总结
+
+通过这次修复，Argon 主题的 Mermaid 支持已经非常完善：
+
+1. ✅ 支持标准的 Markdown 容器语法
+2. ✅ 兼容 WP-Markdown 插件的特殊格式
+3. ✅ 正确处理换行符和特殊字符
+4. ✅ 支持复杂的流程图和样式定义
+5. ✅ 提供详细的调试信息
+6. ✅ 完全向后兼容
+
+用户现在可以放心使用容器语法编写 Mermaid 图表，无需担心格式问题。