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

Mermaid Shortcode 使用指南

为什么使用 Shortcode？

在 WP-Markdown 环境下，使用 Shortcode 是最可靠的 Mermaid 图表标记方式：

优点 ✅

1. 不依赖 WP-Markdown 的处理方式

   • 不会被 WordPress 自动格式化破坏
   • 不会将 --> 转换为 –>
   • 不会丢失换行符

2. 在原生编辑器中清晰可见

   • 经典编辑器：文本模式下直接可见
   • Gutenberg 编辑器：使用"短代码"块
   • 易于编辑和维护

3. 支持参数配置

   • 可以设置主题（theme）
   • 可以设置宽度（width）
   • 可以设置高度（height）
   • 可以设置对齐方式（align）

4. 完全兼容

   • 与其他 Shortcode 一样使用
   • 不需要额外插件
   • 不需要修改 WP-Markdown

对比其他方式

方式	优点	缺点
Shortcode ⭐	可靠、易用、支持参数	需要记住语法
容器语法 ::: mermaid	符合 Markdown 规范	被 WP 格式化破坏
代码块 ```mermaid	通用	被代码高亮干扰
HTML <div class="mermaid">	灵活	编辑不便

---

基本用法

语法

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

在经典编辑器中使用

1. 切换到"文本"模式（不是"可视化"模式）
2. 输入 Shortcode：

   [mermaid]
   你的 Mermaid 代码
   [/mermaid]
   

3. 保存并预览

在 Gutenberg 编辑器中使用

1. 添加"短代码"块（Shortcode Block）
2. 输入 Shortcode：

   [mermaid]
   你的 Mermaid 代码
   [/mermaid]
   

3. 保存并预览

---

参数说明

theme - 主题

设置图表主题，支持以下值：

• default - 默认主题（浅色）
• dark - 深色主题
• forest - 森林主题
• neutral - 中性主题

示例：

[mermaid theme="dark"]
flowchart TD
    A --> B
[/mermaid]

width - 宽度

设置图表容器宽度，支持：

• 百分比：100%, 80%, 50%
• 像素值：800px, 600px
• 自动：auto

示例：

[mermaid width="80%"]
flowchart TD
    A --> B
[/mermaid]

height - 高度

设置图表容器高度，支持：

• 像素值：600px, 400px
• 自动：auto（默认）

示例：

[mermaid height="500px"]
flowchart TD
    A --> B
[/mermaid]

align - 对齐方式

设置图表对齐方式，支持：

• left - 左对齐
• center - 居中（默认）
• right - 右对齐

示例：

[mermaid align="left"]
flowchart TD
    A --> B
[/mermaid]

组合使用

[mermaid theme="dark" width="80%" height="500px" align="center"]
flowchart TD
    A[开始] --> B[处理]
    B --> C[结束]
[/mermaid]

---

使用示例

示例 1: 简单流程图

[mermaid]
flowchart TD
    Start([开始]) --> Process[处理数据]
    Process --> Decision{是否成功?}
    Decision -->|是| Success[显示成功]
    Decision -->|否| Error[显示错误]
    Success --> End([结束])
    Error --> End
[/mermaid]

示例 2: 时序图

[mermaid]
sequenceDiagram
    participant User as 用户
    participant Server as 服务器
    participant DB as 数据库
    
    User->>Server: 发送请求
    Server->>DB: 查询数据
    DB-->>Server: 返回数据
    Server-->>User: 返回响应
[/mermaid]

示例 3: 类图

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

示例 4: 甘特图

[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
    性能测试 :c2, after b2, 3d
[/mermaid]

示例 5: 状态图

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

示例 6: 饼图

[mermaid]
pie title 编程语言使用占比
    "JavaScript" : 386
    "Python" : 285
    "Java" : 215
    "C++" : 115
    "其他" : 85
[/mermaid]

示例 7: ER 图

[mermaid]
erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains
    PRODUCT ||--o{ ORDER_ITEM : "ordered in"
    
    USER {
        int id PK
        string name
        string email
    }
    ORDER {
        int id PK
        int user_id FK
        date created_at
    }
    PRODUCT {
        int id PK
        string name
        decimal price
    }
[/mermaid]

示例 8: 带样式的流程图

[mermaid]
flowchart TD
    Start([用户提交评论]) --> PreProcess[预处理]
    PreProcess --> CheckEnabled{启用 AI 检测?}
    CheckEnabled -->|是| AICheck[AI 检测]
    CheckEnabled -->|否| Save[保存评论]
    AICheck --> Result{检测结果?}
    Result -->|垃圾评论| Trash[移入回收站]
    Result -->|正常评论| Save
    
    style Start fill:#e1f5e1,stroke:#2e7d32,stroke-width:2px
    style Trash fill:#ff6b6b,stroke:#c62828,stroke-width:2px
    style Save fill:#95e1d3,stroke:#2e7d32,stroke-width:2px
[/mermaid]

---

常见问题

1. Shortcode 不生效怎么办？

可能原因：

• 主题未更新到最新版本
• 使用了"可视化"模式编辑

解决方案：

1. 更新 Argon 主题到最新版本
2. 切换到"文本"模式编辑
3. 检查 Shortcode 语法是否正确

2. 图表渲染失败怎么办？

排查步骤：

1. 检查 Mermaid 语法

   • 访问 Mermaid Live Editor
   • 粘贴你的代码验证语法

2. 查看浏览器控制台

   • 按 F12 打开开发者工具
   • 查看 Console 标签页
   • 搜索错误信息

3. 检查主题设置

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

3. 如何迁移现有的容器语法？

如果你之前使用了 ::: mermaid ... ::: 语法，可以批量替换：

查找：

::: mermaid

替换为：

[mermaid]

查找：

:::

替换为：

[/mermaid]

4. 可以在评论中使用吗？

不可以。Shortcode 只能在文章和页面中使用，评论中不支持。

5. 可以嵌套使用吗？

不可以。Shortcode 不支持嵌套，每个图表需要独立的 [mermaid]...[/mermaid] 标签。

---

最佳实践

1. 使用有意义的节点 ID

推荐：

[mermaid]
flowchart TD
    UserSubmit([用户提交]) --> Validate[验证数据]
    Validate --> Save[保存数据]
[/mermaid]

不推荐：

[mermaid]
flowchart TD
    A --> B
    B --> C
[/mermaid]

2. 添加适当的注释

[mermaid]
flowchart TD
    %% 用户流程
    Start([开始]) --> Login[登录]
    
    %% 验证流程
    Login --> Check{验证成功?}
    Check -->|是| Dashboard[进入控制台]
    Check -->|否| Error[显示错误]
[/mermaid]

3. 使用样式定义

[mermaid]
flowchart TD
    Success[成功] --> End
    Error[错误] --> End
    
    style Success fill:#95e1d3,stroke:#2e7d32
    style Error fill:#ff6b6b,stroke:#c62828
[/mermaid]

4. 保持图表简洁

• 避免过多的节点（建议 < 20 个）
• 使用子图（subgraph）组织复杂流程
• 考虑拆分为多个图表

5. 测试后再发布

1. 先在 Mermaid Live Editor 中测试
2. 确认语法正确后再粘贴到文章中
3. 使用"预览"功能查看效果
4. 确认无误后再发布

---

技术细节

Shortcode 实现

Argon 主题在 functions.php 中注册了 mermaid shortcode：

add_shortcode('mermaid','shortcode_mermaid');
function shortcode_mermaid($attr,$content=""){
	// 预处理内容
	$content = shortcode_content_preprocess($attr, $content);
	
	// 获取参数
	$theme = isset( $attr['theme'] ) ? $attr['theme'] : 'default';
	$width = isset( $attr['width'] ) ? $attr['width'] : '100%';
	$height = isset( $attr['height'] ) ? $attr['height'] : 'auto';
	$align = isset( $attr['align'] ) ? $attr['align'] : 'center';
	
	// 生成 HTML
	$out = '<div class="mermaid-shortcode-container">';
	$out .= '<div class="mermaid-shortcode" ...>';
	$out .= esc_html($content);
	$out .= '</div></div>';
	
	return $out;
}

JavaScript 检测

在 argontheme.js 中，Mermaid 渲染器会自动检测 div.mermaid-shortcode 元素：

const selectors = [
	'div.mermaid-shortcode',  // Shortcode 格式（推荐）
	'div.mermaid',            // 标准格式
	// ...
];

安全性

• 使用 esc_html() 转义输出，防止 XSS 攻击
• 使用 esc_attr() 转义属性值
• 不执行任何用户提供的 JavaScript 代码

---

相关资源

• Mermaid 官方文档
• Mermaid Live Editor
• WordPress Shortcode API
• Argon 主题文档

---

更新日志

2026-01-24

• ✅ 添加 Mermaid Shortcode 支持
• ✅ 支持 theme、width、height、align 参数
• ✅ 自动检测和渲染
• ✅ 完整的使用文档和示例

---

总结

使用 Shortcode 是在 WP-Markdown 环境下最可靠的 Mermaid 图表标记方式：

1. 简单易用：[mermaid]...[/mermaid]
2. 功能强大：支持主题、尺寸、对齐等参数
3. 完全兼容：不需要额外插件或修改
4. 易于维护：在编辑器中清晰可见

推荐所有用户使用 Shortcode 方式编写 Mermaid 图表！