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 生成 `<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 结构
+
+```html
+<p>::: mermaid<br>
+flowchart TD<br>
+    Start([用户提交评论]) --> PreProcess[预处理]<br>
+    PreProcess --> CheckEnabled{启用 AI 检测?}<br>
+:::</p>
+```
+
+### htmlToText() 函数
+
+```javascript
+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. 简单流程图
+```markdown
+::: mermaid
+flowchart TD
+    A[开始] --> B[处理]
+    B --> C[结束]
+:::
+```
+
+#### 2. 复杂流程图（AI 评论审核）
+- 包含 100+ 个节点
+- 包含多行文本（`<br/>` 标签）
+- 包含箭头符号（`-->`, `-->`）
+- 包含样式定义（`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 格式（`<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 官方文档](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 图表，无需担心格式问题。