argon-theme/docs/mermaid-fix-summary.md

Mermaid 容器语法修复总结

修复的问题

问题 1: 代码高亮干扰 Mermaid 渲染

• 症状: 使用 ```mermaid 标记时，代码高亮会处理 mermaid 代码块，导致渲染冲突
• 修复: 在 highlightJsRender() 函数中添加检查，跳过 language-mermaid 和 mermaid 类的代码块
• Commit: 0ac5794

问题 2: 容器语法空行导致内容截断

• 症状: 容器语法 ::: mermaid ... ::: 中的空行导致内容被截断
• 修复: 修改 extractContainerContent() 函数，不使用 trim() 删除空行
• Commit: 0ac5794

问题 3: WP-Markdown document.write 重复输出

• 症状: WP-Markdown 生成 <div class="mermaid"><script>document.write("...")</script>flowchart TD ...</div>，script 后面有重复代码
• 修复: 在 extractMermaidCode() 中提取完 script 内容后立即 scriptTag.remove()
• Commit: b6d9f8c

问题 4: 容器语法跨元素收集失败

• 症状: 容器语法遇到空行时，WP-Markdown 将内容分割成多个元素，只提取到第一个元素
• 修复: 重写 detectContainerBlocks() 和 extractContainerContent()，支持跨多个兄弟元素收集内容
• Commit: b6d9f8c

问题 5: 换行符丢失 ⭐（核心问题）

• 症状:
  • 流程图渲染失败，错误显示 flowchart TDStart（TD 和 Start 之间缺少换行）
  • 箭头符号被转换成全角 –> 而不是 -->
• 根本原因:
  • WP-Markdown 将每一行代码包裹在 <p> 标签中
  • 行内换行使用 <br> 标签表示
  • 使用 textContent 或 innerText 提取时，<br> 标签被忽略或转换为空格
  • 导致多行代码被合并成一行，Mermaid 语法解析失败
• 修复:
  • 新增 htmlToText() 辅助函数，将 <br> 标签转换为换行符
  • 改进 extractContainerContent() 函数，使用 innerHTML 而不是 textContent
  • 调用 htmlToText() 正确处理 HTML 结构
• Commit: b4ba37a

技术细节

WP-Markdown 生成的 HTML 结构

<p>::: mermaid<br>
flowchart TD<br>
    Start([用户提交评论]) --> PreProcess[预处理]<br>
    PreProcess --> CheckEnabled{启用 AI 检测?}<br>
:::</p>

htmlToText() 函数

htmlToText(html) {
	// 将 <br> 和 <br/> 转换为换行符
	let text = html.replace(/<br\s*\/?>/gi, '\n');
	// 移除其他 HTML 标签
	text = text.replace(/<[^>]+>/g, '');
	// 解码 HTML 实体
	text = text
		.replace(/&nbsp;/g, ' ')
		.replace(/&lt;/g, '<')
		.replace(/&gt;/g, '>')
		.replace(/&amp;/g, '&')
		.replace(/&quot;/g, '"')
		.replace(/&#039;/g, "'");
	return text;
}

提取流程

1. 检测到 ::: mermaid 开始标记
2. 提取 innerHTML（包含 <br> 标签）
   原始: "::: mermaid<br>flowchart TD<br>Start --> End<br>:::"
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. 简单流程图

::: mermaid
flowchart TD
    A[开始] --> B[处理]
    B --> C[结束]
:::

2. 复杂流程图（AI 评论审核）

• 包含 100+ 个节点
• 包含多行文本（<br/> 标签）
• 包含箭头符号（-->, -->）
• 包含样式定义（style 语句）

3. 带样式的流程图

::: 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 格式（<div class="mermaid"><script>document.write()</script></div>）
• ✅ 标准格式（<div class="mermaid">, <pre><code class="language-mermaid">）
• ✅ 代码高亮（排除 mermaid 代码块）

向后兼容性

• ✅ 完全向后兼容
• ✅ 不影响现有功能
• ✅ 支持所有现代浏览器

性能影响

• DOM 操作: 使用 innerHTML 和正则替换，性能影响可忽略
• 内存占用: 无显著增加
• 渲染速度: 无影响

安全性

• ✅ 只处理 Mermaid 代码块，不执行任何脚本
• ✅ HTML 实体正确解码
• ✅ 无 XSS 风险

调试支持

• 添加详细的 console.log 日志
• 支持调试模式（主题设置中开启）
• 错误时显示友好提示

后续优化建议

1. 支持更多容器语法

   • ::: warning - 警告框
   • ::: tip - 提示框
   • ::: danger - 危险框

2. 性能优化

   • 缓存已处理的代码块
   • 使用 IntersectionObserver 延迟渲染

3. 测试覆盖

   • 添加单元测试
   • 添加集成测试
   • 添加性能测试

4. 文档完善

   • 添加更多示例
   • 添加常见问题解答
   • 添加故障排除指南

相关资源

• Mermaid 官方文档
• Mermaid Live Editor
• VuePress 容器语法
• CommonMark 规范

总结

通过这次修复，Argon 主题的 Mermaid 支持已经非常完善：

1. ✅ 支持标准的 Markdown 容器语法
2. ✅ 兼容 WP-Markdown 插件的特殊格式
3. ✅ 正确处理换行符和特殊字符
4. ✅ 支持复杂的流程图和样式定义
5. ✅ 提供详细的调试信息
6. ✅ 完全向后兼容

用户现在可以放心使用容器语法编写 Mermaid 图表，无需担心格式问题。