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