feat: 添加 Mermaid Shortcode 支持（推荐方式）

- 新增 [mermaid]...[/mermaid] shortcode - 支持 theme、width、height、align 参数 - 不依赖 WP-Markdown 的处理方式 - 不会被 WordPress 自动格式化破坏 - 在原生编辑器中清晰可见 - 添加完整的使用指南和示例
2026-01-24 21:02:47 +08:00
parent bf8f973e91
commit 32c2a72d2b
5 changed files with 1102 additions and 2 deletions
--- a/docs/mermaid-shortcode-guide.md
+++ b/docs/mermaid-shortcode-guide.md
@@ -0,0 +1,505 @@
+# 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](https://mermaid.live/)
+   - 粘贴你的代码验证语法
+
+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](https://mermaid.live/) 中测试
+2. 确认语法正确后再粘贴到文章中
+3. 使用"预览"功能查看效果
+4. 确认无误后再发布
+
+---
+
+## 技术细节
+
+### Shortcode 实现
+
+Argon 主题在 `functions.php` 中注册了 `mermaid` shortcode：
+
+```php
+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` 元素：
+
+```javascript
+const selectors = [
+	'div.mermaid-shortcode',  // Shortcode 格式（推荐）
+	'div.mermaid',            // 标准格式
+	// ...
+];
+```
+
+### 安全性
+
+- 使用 `esc_html()` 转义输出，防止 XSS 攻击
+- 使用 `esc_attr()` 转义属性值
+- 不执行任何用户提供的 JavaScript 代码
+
+---
+
+## 相关资源
+
+- [Mermaid 官方文档](https://mermaid.js.org/)
+- [Mermaid Live Editor](https://mermaid.live/)
+- [WordPress Shortcode API](https://developer.wordpress.org/plugins/shortcodes/)
+- [Argon 主题文档](https://argon-docs.solstice23.top/)
+
+---
+
+## 更新日志
+
+### 2026-01-24
+- ✅ 添加 Mermaid Shortcode 支持
+- ✅ 支持 theme、width、height、align 参数
+- ✅ 自动检测和渲染
+- ✅ 完整的使用文档和示例
+
+---
+
+## 总结
+
+使用 Shortcode 是在 WP-Markdown 环境下最可靠的 Mermaid 图表标记方式：
+
+1. **简单易用**：`[mermaid]...[/mermaid]`
+2. **功能强大**：支持主题、尺寸、对齐等参数
+3. **完全兼容**：不需要额外插件或修改
+4. **易于维护**：在编辑器中清晰可见
+
+推荐所有用户使用 Shortcode 方式编写 Mermaid 图表！