argon-theme/docs/mermaid-usage-guide.md

Argon 主题 Mermaid 图表使用指南

推荐的标记方式

Markdown 容器语法（推荐）⭐

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

优点：

• ✅ 符合 Markdown 扩展规范（VuePress、Docusaurus 等使用相同语法）
• ✅ 不会被 WP-Markdown 当作代码块处理，避免嵌套问题
• ✅ 语法简洁，易于编写和阅读
• ✅ 支持所有 Mermaid 图表类型
• ✅ 在纯文本编辑器中也很清晰
• ✅ 易于迁移到其他平台

为什么使用容器语法？

Markdown 容器语法 (::: mermaid ... :::) 是现代 Markdown 扩展的标准方式：

• VuePress 使用这种语法
• Docusaurus 使用这种语法
• MkDocs 使用类似语法
• 符合 CommonMark 扩展规范

这种语法不会被 WP-Markdown 插件当作代码块处理，因此：

• 不会被套上代码高亮窗口
• 不会有嵌套结构问题
• 不会有字符转义问题

---

使用示例

流程图

::: mermaid
flowchart LR
    A[用户] --> B{登录?}
    B -->|是| C[显示首页]
    B -->|否| D[跳转登录页]
:::

时序图

::: mermaid
sequenceDiagram
    Alice->>Bob: Hello Bob!
    Bob-->>Alice: Hi Alice!
    Alice->>Bob: How are you?
:::

类图

::: mermaid
classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }
    class Dog {
        +String breed
        +bark()
    }
    Animal <|-- Dog
:::

甘特图

::: mermaid
gantt
    title 项目进度
    dateFormat YYYY-MM-DD
    section 设计
    需求分析 :a1, 2024-01-01, 7d
    UI设计 :a2, after a1, 5d
    section 开发
    前端开发 :b1, after a2, 10d
    后端开发 :b2, after a2, 12d
:::

状态图

::: mermaid
stateDiagram-v2
    [*] --> 待审核
    待审核 --> 已通过: 审核通过
    待审核 --> 已拒绝: 审核拒绝
    已通过 --> [*]
    已拒绝 --> [*]
:::

饼图

::: mermaid
pie title 宠物分布
    "狗" : 386
    "猫" : 85
    "兔子" : 15
:::

---

常见问题

1. 如何在 WordPress 编辑器中使用？

在经典编辑器中：

1. 切换到"文本"模式（不是"可视化"模式）
2. 直接输入容器语法
3. 保存并预览

在 Gutenberg 编辑器中：

1. 添加"自定义 HTML"块或"代码"块
2. 输入容器语法
3. 保存并预览

2. 已有文章如何迁移？

如果你的文章使用了传统的 Markdown 代码块，可以批量替换：

查找：

三个反引号mermaid

替换为：

::: mermaid

查找：

三个反引号（代码块结束）

替换为：

:::

3. 容器语法不生效怎么办？

可能的原因：

• 其他插件或主题处理了容器语法
• WP-Markdown 插件版本过旧

解决方案：

1. 检查是否有其他 Markdown 插件冲突
2. 更新 WP-Markdown 插件到最新版本
3. 查看浏览器控制台的错误信息

4. 渲染失败怎么办？

排查步骤：

1. 检查语法

   • 访问 Mermaid Live Editor 验证语法
   • 确保图表类型正确

2. 查看控制台

   • 按 F12 打开开发者工具
   • 查看 Console 标签页
   • 搜索 [Argon Mermaid] 日志

3. 检查主题设置

   • WordPress 后台 → 外观 → Argon 主题选项
   • 找到"Mermaid 图表"分类
   • 确认"启用 Mermaid 支持"已开启

4. 测试 CDN 连接

   • 访问测试页面验证 CDN 是否可用
   • 如果 CDN 失败，尝试切换到其他 CDN

---

最佳实践

1. 使用容器语法

推荐：

::: mermaid
flowchart TD
    A --> B
:::

不推荐：

三个反引号mermaid
flowchart TD
    A --> B
三个反引号

2. 避免特殊字符

如果图表中包含特殊字符，使用引号包裹：

::: mermaid
flowchart TD
    A["包含 <特殊> 字符"] --> B["使用引号包裹"]
:::

3. 测试复杂图表

对于复杂的图表：

1. 先在 Mermaid Live Editor 中测试
2. 确认语法正确后再粘贴到文章中
3. 发布前预览文章

4. 启用调试模式

如果遇到问题：

1. 主题设置 → Mermaid 图表 → 基本设置
2. 开启"调试模式"
3. 刷新页面查看控制台日志

5. 保持代码简洁

• 使用有意义的节点 ID
• 添加适当的注释
• 保持图表结构清晰

---

技术细节

支持的标记格式

Argon 主题支持以下格式（按优先级排序）：

1. ::: mermaid ... ::: - Markdown 容器语法 ⭐（推荐）
2. <div class="mermaid"> - 标准格式（WPMD 生成）
3. <pre><code class="language-mermaid"> - Markdown 格式
4. <pre data-lang="mermaid"> - 自定义属性格式
5. <code class="mermaid"> - 简化格式

代码提取逻辑

1. 检测代码块

   • CSS 选择器查找标准格式
   • TreeWalker 查找容器语法

2. 提取代码

   • 容器语法：移除 ::: mermaid 和 :::
   • WPMD 格式：正则提取 document.write() 内容
   • 标准格式：直接提取文本内容

3. 解码处理

   • 先解码 HTML 实体（< → <）
   • 再解码转义字符（\n → 换行符）

4. 渲染图表

   • 使用 Mermaid.js 库渲染为 SVG
   • 应用主题样式（夜间模式适配）
   • 错误时显示友好提示

---

故障排除

问题：容器语法被显示为普通文本

症状：::: mermaid 被显示在页面上

原因：可能被其他插件或主题处理为普通文本

解决：

• 检查是否有其他 Markdown 插件冲突
• 确认 Argon 主题已更新到最新版本
• 查看浏览器控制台是否有 JavaScript 错误

问题：只显示第一个单词

症状：图表渲染失败，错误信息显示 "text": "flowchart"

原因：代码提取不完整

解决：

• 确保使用最新版本的 Argon 主题
• 使用容器语法而不是传统代码块
• 查看控制台日志确认提取到的完整代码

问题：HTML 实体未解码

症状：图表中显示 < 而不是 <

原因：HTML 实体解码失败

解决：

• Argon 主题会自动解码 HTML 实体
• 使用容器语法可避免此问题
• 在 Mermaid 代码中使用引号包裹特殊字符

---

相关资源

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

---

更新日志

2026-01-24

• ✅ 添加 Markdown 容器语法支持（::: mermaid ... :::）
• ✅ 修复 WP-Markdown 格式的代码提取问题
• ✅ 改进正则表达式，支持多行代码
• ✅ 添加降级方案和详细日志
• ✅ 简化标记方式，只保留容器语法作为推荐方式
• ✅ 修复代码高亮干扰 mermaid 渲染的问题（排除 mermaid 代码块）
• ✅ 修复容器语法中空行导致内容被截断的问题
• ✅ 修复 WP-Markdown 的 document.write 重复输出问题
• ✅ 改进容器语法检测，支持跨多个元素的内容收集
• ✅ 修复换行符丢失问题（将 <br> 标签正确转换为换行符）