nanhaoluo
32c2a72d2b
- 新增 [mermaid]...[/mermaid] shortcode - 支持 theme、width、height、align 参数 - 不依赖 WP-Markdown 的处理方式 - 不会被 WordPress 自动格式化破坏 - 在原生编辑器中清晰可见 - 添加完整的使用指南和示例
506 lines
9.7 KiB
Markdown
506 lines
9.7 KiB
Markdown
# 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 图表！
|