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

Argon 主题 Mermaid 图表使用指南

目录

1. 功能简介
2. 快速开始
3. 支持的图表类型
4. 使用方法
5. 主题设置
6. 常见问题
7. 最佳实践
8. 故障排除

---

功能简介

Argon 主题内置了 Mermaid 图表支持，让您可以在文章中轻松创建各种专业的图表，包括：

• 📊 流程图 - 展示业务流程和逻辑关系
• 📈 时序图 - 描述系统交互和时间顺序
• 🏗️ 类图 - 展示面向对象的类结构
• 📉 状态图 - 表示状态机和状态转换
• 🥧 饼图 - 显示数据占比
• 📅 甘特图 - 项目进度管理
• 🗺️ 用户旅程图 - 用户体验流程
• 🌳 Git 图 - 版本控制分支可视化

主要特性

✅ 零配置使用 - 开箱即用，无需额外插件
✅ 自动主题切换 - 跟随页面日间/夜间模式
✅ 智能加载 - 只在需要时加载库文件
✅ 插件兼容 - 自动检测并避免重复加载
✅ 错误提示 - 友好的错误信息和调试支持
✅ CDN 降级 - 多个 CDN 自动切换，确保可用性

---

快速开始

1. 启用 Mermaid 支持

进入 WordPress 后台 → 外观 → Argon 主题设置 → Mermaid 图表，勾选"启用 Mermaid 支持"。

2. 在文章中使用

在文章编辑器中，使用以下格式插入 Mermaid 代码：

```mermaid
flowchart TD
    Start([开始]) --> Process[处理数据]
    Process --> End([结束])
```

或使用 HTML 格式：

<div class="mermaid">
flowchart TD
    Start([开始]) --> Process[处理数据]
    Process --> End([结束])
</div>

3. 发布并查看

保存文章后，在前台页面即可看到渲染后的图表。

---

支持的图表类型

1. 流程图 (Flowchart)

展示流程和决策逻辑。

```mermaid
flowchart TD
    A[开始] --> B{判断条件}
    B -->|是| C[执行操作 A]
    B -->|否| D[执行操作 B]
    C --> E[结束]
    D --> E
```

节点形状：

• [文本] - 矩形
• ([文本]) - 圆角矩形
• {文本} - 菱形（判断）
• ((文本)) - 圆形
• [[文本]] - 子程序

2. 时序图 (Sequence Diagram)

描述对象之间的交互顺序。

```mermaid
sequenceDiagram
    participant 用户
    participant 服务器
    participant 数据库
    
    用户->>服务器: 发送请求
    服务器->>数据库: 查询数据
    数据库-->>服务器: 返回结果
    服务器-->>用户: 响应数据
```

箭头类型：

• -> - 实线箭头
• --> - 虚线箭头
• ->> - 实线箭头（带箭头）
• -->> - 虚线箭头（带箭头）

3. 类图 (Class Diagram)

展示面向对象的类结构。

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

4. 状态图 (State Diagram)

表示状态机和状态转换。

```mermaid
stateDiagram-v2
    [*] --> 待处理
    待处理 --> 处理中: 开始处理
    处理中 --> 已完成: 处理成功
    处理中 --> 失败: 处理失败
    失败 --> 待处理: 重试
    已完成 --> [*]
```

5. 饼图 (Pie Chart)

显示数据占比。

```mermaid
pie title 浏览器市场份额
    "Chrome" : 65
    "Safari" : 15
    "Firefox" : 10
    "Edge" : 7
    "其他" : 3
```

6. 甘特图 (Gantt Chart)

项目进度管理。

```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
    section 测试阶段
    功能测试           :c1, after b1, 5d
```

7. 用户旅程图 (User Journey)

描述用户体验流程。

```mermaid
journey
    title 用户购物旅程
    section 浏览商品
      访问网站: 5: 用户
      搜索商品: 3: 用户
      查看详情: 4: 用户
    section 下单
      加入购物车: 4: 用户
      填写信息: 2: 用户
      支付: 3: 用户
    section 收货
      等待发货: 2: 用户
      收到商品: 5: 用户
```

8. Git 图 (Git Graph)

版本控制分支可视化。

```mermaid
gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit
```

---

使用方法

在 Markdown 编辑器中使用

如果您使用 Markdown 编辑器（如 WP-Markdown），直接使用代码块语法：

```mermaid
flowchart LR
    A --> B
    B --> C
```

在 Gutenberg 编辑器中使用

1. 添加"代码"块或"自定义 HTML"块
2. 输入 Mermaid 代码
3. 使用 <div class="mermaid"> 包裹

<div class="mermaid">
flowchart LR
    A --> B
    B --> C
</div>

在经典编辑器中使用

切换到"文本"模式，使用 HTML 格式：

<div class="mermaid">
flowchart LR
    A --> B
    B --> C
</div>

---

主题设置

基本设置

启用 Mermaid 支持

位置： Argon 主题设置 → Mermaid 图表 → 基本设置

勾选此选项以启用 Mermaid 图表渲染功能。

CDN 来源

选择 Mermaid 库的加载来源：

• jsDelivr CDN (推荐) - 全球 CDN，速度快，稳定性高
• unpkg CDN - 备用 CDN
• 自定义 CDN 地址 - 使用自己的 CDN 或镜像
• 本地文件 - 使用主题目录中的本地文件

建议： 使用 jsDelivr CDN，主题会自动在多个 CDN 之间切换以确保可用性。

自定义 CDN 地址

当选择"自定义 CDN 地址"时，输入完整的 Mermaid 库 URL。

格式要求：

• 必须是有效的 URL
• 必须以 .js 结尾
• 必须使用 http:// 或 https:// 协议

示例：

https://cdn.example.com/mermaid@10.0.0/mermaid.min.js

外观设置

图表主题

选择 Mermaid 图表的配色主题：

• 自动切换 (推荐) - 跟随页面日间/夜间模式自动切换
• 默认主题 - 浅色主题，适合日间模式
• 深色主题 - 深色主题，适合夜间模式
• 森林主题 - 绿色主题
• 中性主题 - 灰色主题

建议： 使用"自动切换"，让图表主题与页面主题保持一致。

高级选项

使用本地镜像

启用后，如果检测到主题目录中存在 Mermaid 库文件，将优先使用本地文件而不是 CDN。

本地文件路径：

wp-content/themes/argon/assets/vendor/mermaid/mermaid.min.js

适用场景：

• 内网环境无法访问外部 CDN
• 需要使用特定版本的 Mermaid
• 追求极致的加载速度

调试模式

启用后，将在浏览器控制台输出详细的 Mermaid 渲染日志。

日志内容包括：

• 初始化状态
• 检测到的代码块数量
• 渲染成功/失败信息
• 主题切换记录
• CDN 加载状态

使用方法：

1. 启用调试模式
2. 打开浏览器开发者工具（F12）
3. 切换到"控制台"标签
4. 查看以 [Argon Mermaid] 开头的日志

插件兼容性检测

主题会自动检测已安装的 Mermaid 插件，避免重复加载库文件。

支持的插件：

• WP Githuber MD
• Markdown Block
• Code Syntax Block

兼容策略：

• 如果检测到插件，主题将只提供样式增强
• 如果未检测到插件，主题将负责加载 Mermaid 库
• 如果检测到多个插件，会显示警告信息

---

常见问题

Q1: 图表不显示，只显示代码？

可能原因：

1. 未启用 Mermaid 支持
2. 代码格式不正确
3. JavaScript 加载失败

解决方法：

1. 检查主题设置中是否启用了 Mermaid 支持
2. 确认代码格式正确（参考本文档示例）
3. 打开浏览器控制台查看是否有错误信息
4. 启用调试模式查看详细日志

Q2: 图表显示"渲染失败"错误？

可能原因：

1. Mermaid 代码语法错误
2. 使用了不支持的图表类型
3. 代码格式不符合规范

解决方法：

1. 检查代码语法是否正确
2. 使用 Mermaid Live Editor 验证代码
3. 查看错误提示中的详细信息
4. 参考本文档中的示例代码

Q3: 图表在夜间模式下看不清？

解决方法：

1. 进入主题设置 → Mermaid 图表 → 外观设置
2. 将"图表主题"设置为"自动切换"
3. 图表会自动跟随页面主题切换

Q4: CDN 加载失败怎么办？

主题已内置降级机制：

1. 主 CDN 失败时，自动尝试备用 CDN
2. 所有 CDN 都失败时，显示友好的错误提示

手动解决：

1. 切换到其他 CDN 来源
2. 使用自定义 CDN 地址
3. 下载本地文件并启用"使用本地镜像"

Q5: 与其他插件冲突？

主题已内置兼容机制：

• 自动检测已安装的 Mermaid 插件
• 避免重复加载库文件
• 只提供样式增强功能

如果仍有冲突：

1. 查看插件兼容性检测结果
2. 禁用主题的 Mermaid 支持，使用插件
3. 或禁用插件，使用主题的 Mermaid 支持

Q6: 如何在评论中使用 Mermaid？

方法：

1. 评论中使用 HTML 格式
2. 使用 <div class="mermaid"> 包裹代码

示例：

<div class="mermaid">
flowchart LR
    A --> B
</div>

注意： 需要确保评论允许 HTML 标签。

Q7: 图表太大，超出容器？

解决方法：

1. Mermaid 图表会自动适应容器宽度
2. 如果图表过于复杂，考虑简化或拆分
3. 使用 CSS 自定义样式调整大小

自定义样式示例：

.mermaid-container {
    max-width: 100%;
    overflow-x: auto;
}

Q8: 如何导出图表为图片？

方法 1：使用浏览器截图

1. 在浏览器中打开文章
2. 使用截图工具截取图表部分

方法 2：使用 Mermaid Live Editor

1. 访问 Mermaid Live Editor
2. 粘贴代码
3. 点击"Export"导出为 PNG/SVG

方法 3：使用浏览器开发者工具

1. 右键点击图表 → 检查元素
2. 找到 SVG 元素
3. 复制 SVG 代码或导出为图片

---

最佳实践

1. 代码格式规范

推荐：

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

不推荐：

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

建议：

• 使用缩进保持代码可读性
• 箭头两侧添加空格
• 每行一个语句

2. 节点命名

推荐：

flowchart TD
    start([开始])
    process[处理数据]
    decision{是否成功?}

不推荐：

flowchart TD
    a([开始])
    b[处理数据]
    c{是否成功?}

建议：

• 使用有意义的节点 ID
• 节点文本简洁明了
• 避免使用特殊字符

3. 图表复杂度

建议：

• 单个图表不超过 20 个节点
• 复杂流程拆分为多个图表
• 使用子图组织相关节点

示例：

flowchart TD
    subgraph 输入阶段
        A[接收数据] --> B[验证数据]
    end
    subgraph 处理阶段
        B --> C[处理数据]
        C --> D[保存结果]
    end

4. 性能优化

建议：

• 避免在一篇文章中使用过多图表（建议不超过 10 个）
• 复杂图表考虑使用图片替代
• 启用 CDN 加速加载

5. 可访问性

建议：

• 为图表添加文字说明
• 使用清晰的节点文本
• 避免仅依赖颜色传达信息

示例：

<div class="mermaid-wrapper">
    <p>以下是用户注册流程图：</p>
    <div class="mermaid">
    flowchart TD
        Start([用户访问注册页]) --> Input[填写信息]
        Input --> Validate{验证信息}
        Validate -->|通过| Register[注册成功]
        Validate -->|失败| Input
    </div>
</div>

6. 版本控制

建议：

• 在文章中记录 Mermaid 代码版本
• 复杂图表保存源代码备份
• 使用注释说明图表用途

示例：

%% 用户注册流程图
%% 版本: 1.0
%% 更新日期: 2024-01-20
flowchart TD
    Start --> End

---

故障排除

调试步骤

1. 启用调试模式

   • 进入主题设置 → Mermaid 图表 → 高级选项
   • 勾选"启用调试模式"

2. 打开浏览器控制台

   • 按 F12 打开开发者工具
   • 切换到"控制台"标签

3. 查看日志信息

   • 查找以 [Argon Mermaid] 开头的日志
   • 记录错误信息和警告

4. 验证代码语法

   • 访问 Mermaid Live Editor
   • 粘贴代码并检查是否有语法错误

5. 检查网络请求

   • 在开发者工具中切换到"网络"标签
   • 查看 Mermaid 库是否成功加载
   • 检查是否有 404 或其他错误

常见错误代码

错误 1: Parse error on line X

原因： Mermaid 代码语法错误

解决：

1. 检查代码语法是否正确
2. 使用 Mermaid Live Editor 验证
3. 参考官方文档修正语法

错误 2: Mermaid 库未加载

原因： CDN 加载失败或被阻止

解决：

1. 检查网络连接
2. 切换到其他 CDN 来源
3. 使用本地文件

错误 3: 主题切换失败

原因： 配置错误或 JavaScript 冲突

解决：

1. 检查主题设置是否正确
2. 禁用其他可能冲突的插件
3. 清除浏览器缓存

获取帮助

如果以上方法都无法解决问题，请：

1. 收集信息：

   • WordPress 版本
   • Argon 主题版本
   • 浏览器类型和版本
   • 错误信息和日志
   • 问题复现步骤

2. 提交问题：

   • 访问 Argon 主题 GitHub
   • 创建新 Issue
   • 提供详细的问题描述和信息

3. 社区支持：

   • 访问主题官方论坛
   • 搜索类似问题
   • 向社区求助

---

相关资源

官方文档

• Mermaid 官方文档
• Mermaid 语法参考
• Mermaid Live Editor

教程和示例

• Mermaid 快速入门
• 流程图教程
• 时序图教程
• 类图教程

工具和插件

• Mermaid Chart - 在线图表编辑器
• VS Code Mermaid 插件
• Chrome Mermaid 扩展

---

更新日志

版本 1.0.0 (2024-01-22)

• ✨ 初始版本发布
• ✅ 支持所有主要图表类型
• ✅ 自动主题切换
• ✅ 插件兼容性检测
• ✅ CDN 降级机制
• ✅ 错误提示和调试支持

---

反馈与建议

如果您在使用过程中有任何问题或建议，欢迎：

• 📧 发送邮件至主题作者
• 💬 在 GitHub 上提交 Issue
• 🌟 为项目点赞支持

感谢您使用 Argon 主题！