7.9 KiB
7.9 KiB
Mermaid 支持方案对比
概述
Argon 主题现在支持多种 Mermaid 图表标记方式，每种方式都有其优缺点和适用场景。
方案对比表
| 方案 | 语法 | 优点 | 缺点 | 推荐度 | 适用场景 |
|---|---|---|---|---|---|
| Shortcode | [mermaid]...[/mermaid] |
✅ 最可靠 ✅ 支持参数 ✅ 不被格式化 ✅ 易于编辑 |
❌ 需要记住语法 | ⭐⭐⭐⭐⭐ | 所有场景（推荐） |
| 容器语法 | ::: mermaid ... ::: |
✅ 符合 Markdown 规范 ✅ 易于迁移 |
❌ 被 WP 格式化 ❌ 换行符问题 ❌ 特殊字符转换 |
⭐⭐⭐ | 简单图表 |
| 代码块 | ```mermaid ... ``` |
✅ 通用语法 ✅ 编辑器高亮 |
❌ 被代码高亮干扰 ❌ 嵌套问题 |
⭐⭐ | 不推荐 |
| HTML | <div class="mermaid">...</div> |
✅ 灵活 ✅ 完全控制 |
❌ 编辑不便 ❌ 可读性差 |
⭐⭐ | 特殊需求 |
详细对比
1. Shortcode 方式 ⭐⭐⭐⭐⭐（推荐）
语法
[mermaid theme="default" width="100%" align="center"]
flowchart TD
A[开始] --> B[处理]
B --> C[结束]
[/mermaid]
优点
- ✅ 最可靠：不依赖 WP-Markdown 的处理方式
- ✅ 不被破坏：不会被 WordPress 自动格式化
- ✅ 支持参数：theme、width、height、align
- ✅ 易于编辑：在编辑器中清晰可见
- ✅ 完全兼容：与其他 Shortcode 一样使用
缺点
- ❌ 需要记住 Shortcode 语法
- ❌ 不是标准 Markdown 语法
适用场景
- ✅ 所有场景（强烈推荐）
- ✅ 复杂流程图
- ✅ 需要自定义样式
- ✅ 长期维护的文档
示例
[mermaid theme="dark" width="80%"]
sequenceDiagram
Alice->>Bob: Hello
Bob-->>Alice: Hi
[/mermaid]
2. 容器语法 ⭐⭐⭐
语法
::: mermaid
flowchart TD
A --> B
:::
优点
- ✅ 符合 Markdown 扩展规范
- ✅ VuePress、Docusaurus 等使用相同语法
- ✅ 易于迁移到其他平台
缺点
- ❌ 被 WordPress 格式化破坏
-->转换为–>- 换行符可能丢失
- 需要复杂的 JavaScript 处理
- ❌ 不支持参数配置
- ❌ 依赖 WP-Markdown 的处理方式
适用场景
- ✅ 简单的流程图
- ✅ 不包含特殊字符
- ✅ 需要跨平台兼容
注意事项
- ⚠️ 避免使用
-->箭头（可能被转换） - ⚠️ 避免复杂的多行文本
- ⚠️ 需要开启主题的 Mermaid 支持
3. 代码块方式 ⭐⭐
语法
```mermaid
flowchart TD
A --> B
```
优点
- ✅ 通用的 Markdown 语法
- ✅ 编辑器可能提供语法高亮
缺点
- ❌ 被代码高亮干扰
- Prism.js 会处理代码块
- 可能出现嵌套问题
- ❌ 被 WP-Markdown 包裹在
document.write()中 - ❌ 需要特殊处理排除
适用场景
- ⚠️ 不推荐使用
- 仅在其他方式不可用时考虑
注意事项
- ⚠️ 需要在代码高亮中排除 mermaid
- ⚠️ 可能出现渲染冲突
4. HTML 方式 ⭐⭐
语法
<div class="mermaid">
flowchart TD
A --> B
</div>
优点
- ✅ 完全控制 HTML 结构
- ✅ 可以添加自定义属性
缺点
- ❌ 编辑不便
- ❌ 可读性差
- ❌ 不符合 Markdown 风格
适用场景
- ✅ 需要特殊的 HTML 结构
- ✅ 需要自定义 CSS 类
- ✅ 程序生成的内容
使用建议
新项目
强烈推荐使用 Shortcode 方式：
[mermaid]
flowchart TD
A --> B
[/mermaid]
理由：
- 最可靠，不会被破坏
- 支持参数配置
- 易于维护
- 长期稳定
现有项目迁移
如果你已经使用了容器语法 ::: mermaid ... :::：
选项 1：保持不变（简单图表）
- 如果图表简单，没有特殊字符
- 如果渲染正常，无需修改
选项 2：迁移到 Shortcode（推荐）
- 批量替换：
::: mermaid→[mermaid] - 批量替换：
:::→[/mermaid] - 测试验证
不同场景的选择
场景 1：技术文档
推荐：Shortcode
- 需要长期维护
- 图表复杂
- 需要自定义样式
场景 2：博客文章
推荐：Shortcode
- 简单易用
- 不需要记住复杂语法
- 稳定可靠
场景 3：跨平台内容
推荐：容器语法（如果目标平台支持）
- 需要在多个平台发布
- 目标平台支持容器语法
- 可以接受一些限制
场景 4：程序生成
推荐：HTML 或 Shortcode
- 由程序自动生成
- 需要批量处理
- 可以使用模板
性能对比
| 方案 | 渲染速度 | 内存占用 | 兼容性 | 稳定性 |
|---|---|---|---|---|
| Shortcode | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| 容器语法 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
| 代码块 | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ | ⭐⭐ |
| HTML | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
常见问题
Q1: 为什么推荐 Shortcode 而不是容器语法？
A: 容器语法虽然符合 Markdown 规范，但在 WordPress 环境下会遇到以下问题：
- WordPress 的
wptexturize()会转换特殊字符 - WP-Markdown 的处理方式不一致
- 需要复杂的 JavaScript 来修复这些问题
Shortcode 方式完全避免了这些问题，更加可靠。
Q2: 可以混用多种方式吗？
A: 可以，但不推荐。建议统一使用一种方式，便于维护。
Q3: 如何批量迁移到 Shortcode？
A: 使用 WordPress 的搜索替换功能：
- 安装 "Better Search Replace" 插件
- 搜索：
::: mermaid，替换为：[mermaid] - 搜索：
:::（在 mermaid 代码块后），替换为：[/mermaid] - 测试验证
Q4: Shortcode 支持哪些参数？
A:
theme: 主题（default, dark, forest, neutral）width: 宽度（100%, 80%, 600px 等）height: 高度（auto, 500px 等）align: 对齐（left, center, right）
Q5: 容器语法还会继续支持吗？
A: 会继续支持，但不推荐新项目使用。我们会持续修复容器语法的问题，但 Shortcode 是更好的选择。
技术实现对比
Shortcode 实现
PHP 端（functions.php）：
add_shortcode('mermaid','shortcode_mermaid');
function shortcode_mermaid($attr,$content=""){
$content = shortcode_content_preprocess($attr, $content);
$theme = isset( $attr['theme'] ) ? $attr['theme'] : 'default';
// ... 生成 HTML
return $out;
}
JavaScript 端（argontheme.js）：
const selectors = [
'div.mermaid-shortcode', // 直接检测
// ...
];
优点：
- ✅ 简单直接
- ✅ 不需要复杂的解析
- ✅ 性能最优
容器语法实现
JavaScript 端（argontheme.js）：
// 1. 检测容器语法
detectContainerBlocks(blocks);
// 2. 提取内容
extractContainerContent(startElement, processedElements);
// 3. 转换 HTML
htmlToText(html);
// 4. 修复特殊字符
text.replace(/–/g, '-');
缺点：
- ❌ 需要复杂的 DOM 遍历
- ❌ 需要处理多种 HTML 结构
- ❌ 需要修复 WordPress 的格式化
- ❌ 性能开销较大
总结
推荐方案
-
首选：Shortcode 方式
[mermaid]...[/mermaid]- 最可靠、最稳定
- 支持参数配置
- 易于维护
-
备选：容器语法
::: mermaid ... :::- 简单图表可用
- 跨平台兼容
- 需要注意限制
-
不推荐：代码块和 HTML 方式
- 仅在特殊情况下使用
迁移建议
- ✅ 新项目：直接使用 Shortcode
- ✅ 现有项目：逐步迁移到 Shortcode
- ✅ 简单图表：可以保持容器语法
文档链接
最后更新：2026-01-24
版本：Argon v2.x