nanhaoluo
29bfd284e0
- 添加 convertMermaidCodeblocks() 函数，在代码高亮前拦截 mermaid 代码块 - 支持标准 Markdown 代码块 (\\\mermaid) 渲染 - 更新 detectMermaidBlocks() 添加 mermaid-from-codeblock 选择器 - 更新 extractMermaidCode() 支持新容器类型 - 创建测试文件 test-codeblock-magic.html - 更新用户文档、开发者文档和 FAQ - 完全绕过代码高亮和 WordPress 格式化 - 支持 PJAX 页面切换 - 特殊字符和换行符正确保留
9.9 KiB
9.9 KiB
Argon 主题 Mermaid 图表使用指南
推荐的标记方式
1. 标准 Markdown 代码块（推荐）⭐
三个反引号mermaid
flowchart TD
A[开始] --> B[处理]
B --> C[结束]
三个反引号
优点：
- ✅ 符合标准 Markdown 语法
- ✅ 在所有 Markdown 编辑器中都能正确显示
- ✅ 支持语法高亮（编辑器层面）
- ✅ 易于迁移到其他平台（GitHub、GitLab、Typora 等）
- ✅ 主题自动拦截处理，避免代码高亮干扰
- ✅ 支持所有 Mermaid 图表类型
工作原理：
- 主题在代码高亮之前拦截 mermaid 代码块
- 自动转换为 Mermaid 渲染容器
- 完全绕过代码高亮和 WordPress 格式化
2. Markdown 容器语法（备选）
::: mermaid
flowchart TD
A[开始] --> B[处理]
B --> C[结束]
:::
优点：
- ✅ 符合 Markdown 扩展规范（VuePress、Docusaurus 等使用相同语法）
- ✅ 不会被 WP-Markdown 当作代码块处理，避免嵌套问题
- ✅ 语法简洁，易于编写和阅读
- ✅ 支持所有 Mermaid 图表类型
- ✅ 在纯文本编辑器中也很清晰
- ✅ 易于迁移到其他平台
3. Shortcode 格式（兼容）
[mermaid]
flowchart TD
A[开始] --> B[处理]
B --> C[结束]
[/mermaid]
优点：
- ✅ WordPress 原生支持
- ✅ 不会被任何插件干扰
- ✅ 兼容性最好
缺点：
- ❌ 不符合 Markdown 标准
- ❌ 在其他平台无法使用
- ❌ 编辑器中不显示为代码块
为什么推荐标准 Markdown 代码块？
标准 Markdown 代码块 (```mermaid) 是最通用的方式：
- GitHub 使用这种语法
- GitLab 使用这种语法
- Typora 使用这种语法
- VS Code 使用这种语法
- 符合 CommonMark 规范
Argon 主题通过代码块魔改技术，在代码高亮之前拦截并转换 mermaid 代码块，因此：
- 不会被代码高亮处理（无行号、无控制按钮）
- 不会有字符转义问题（
-->保持不变） - 不会有嵌套结构问题
- 完全符合标准 Markdown 语法
使用示例
流程图
标准 Markdown 代码块：
三个反引号mermaid
flowchart LR
A[用户] --> B{登录?}
B -->|是| C[显示首页]
B -->|否| D[跳转登录页]
三个反引号
容器语法：
::: mermaid
flowchart LR
A[用户] --> B{登录?}
B -->|是| C[显示首页]
B -->|否| D[跳转登录页]
:::
时序图
三个反引号mermaid
sequenceDiagram
Alice->>Bob: Hello Bob!
Bob-->>Alice: Hi Alice!
Alice->>Bob: How are you?
三个反引号
类图
三个反引号mermaid
classDiagram
class Animal {
+String name
+int age
+makeSound()
}
class Dog {
+String breed
+bark()
}
Animal <|-- Dog
三个反引号
甘特图
三个反引号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
三个反引号
状态图
三个反引号mermaid
stateDiagram-v2
[*] --> 待审核
待审核 --> 已通过: 审核通过
待审核 --> 已拒绝: 审核拒绝
已通过 --> [*]
已拒绝 --> [*]
三个反引号
饼图
三个反引号mermaid
pie title 宠物分布
"狗" : 386
"猫" : 85
"兔子" : 15
三个反引号
常见问题
1. 如何在 WordPress 编辑器中使用？
在经典编辑器中：
- 切换到"文本"模式（不是"可视化"模式）
- 直接输入容器语法
- 保存并预览
在 Gutenberg 编辑器中：
- 添加"自定义 HTML"块或"代码"块
- 输入容器语法
- 保存并预览
2. 已有文章如何迁移？
如果你的文章使用了传统的 Markdown 代码块，可以批量替换：
查找：
三个反引号mermaid
替换为：
::: mermaid
查找：
三个反引号（代码块结束）
替换为：
:::
3. 容器语法不生效怎么办？
可能的原因：
- 其他插件或主题处理了容器语法
- WP-Markdown 插件版本过旧
解决方案：
- 检查是否有其他 Markdown 插件冲突
- 更新 WP-Markdown 插件到最新版本
- 查看浏览器控制台的错误信息
4. 渲染失败怎么办？
排查步骤：
-
检查语法
- 访问 Mermaid Live Editor 验证语法
- 确保图表类型正确
-
查看控制台
- 按 F12 打开开发者工具
- 查看 Console 标签页
- 搜索
[Argon Mermaid]日志
-
检查主题设置
- WordPress 后台 → 外观 → Argon 主题选项
- 找到"Mermaid 图表"分类
- 确认"启用 Mermaid 支持"已开启
-
测试 CDN 连接
- 访问测试页面验证 CDN 是否可用
- 如果 CDN 失败，尝试切换到其他 CDN
最佳实践
1. 使用标准 Markdown 代码块
推荐：
三个反引号mermaid
flowchart TD
A --> B
三个反引号
也可以使用容器语法：
::: mermaid
flowchart TD
A --> B
:::
不推荐（Shortcode）：
[mermaid]
flowchart TD
A --> B
[/mermaid]
2. 避免特殊字符
如果图表中包含特殊字符，使用引号包裹：
::: mermaid
flowchart TD
A["包含 <特殊> 字符"] --> B["使用引号包裹"]
:::
3. 测试复杂图表
对于复杂的图表：
- 先在 Mermaid Live Editor 中测试
- 确认语法正确后再粘贴到文章中
- 发布前预览文章
4. 启用调试模式
如果遇到问题：
- 主题设置 → Mermaid 图表 → 基本设置
- 开启"调试模式"
- 刷新页面查看控制台日志
5. 保持代码简洁
- 使用有意义的节点 ID
- 添加适当的注释
- 保持图表结构清晰
技术细节
支持的标记格式
Argon 主题支持以下格式（按优先级排序）：
```mermaid ... ```- 标准 Markdown 代码块 ⭐（推荐）::: mermaid ... :::- Markdown 容器语法（备选）[mermaid]...[/mermaid]- Shortcode 格式（兼容）<div class="mermaid">- 标准格式（WPMD 生成）<pre><code class="language-mermaid">- Markdown 格式（降级）<pre data-lang="mermaid">- 自定义属性格式<code class="mermaid">- 简化格式
代码块魔改技术
工作原理：
-
拦截阶段（在代码高亮之前）
- 查找所有
<pre><code class="language-mermaid">元素 - 提取纯文本代码（使用
textContent） - 创建
<div class="mermaid-from-codeblock">容器 - 替换原始代码块元素
- 查找所有
-
代码高亮阶段
- 处理其他代码块
- 跳过 mermaid 相关的元素
-
Mermaid 渲染阶段
- 检测所有 Mermaid 容器（包括新的
mermaid-from-codeblock） - 提取代码并渲染为 SVG 图表
- 检测所有 Mermaid 容器（包括新的
优势：
- ✅ 完全绕过代码高亮干扰
- ✅ 特殊字符不被转换（
-->保持不变） - ✅ 换行符正确保留
- ✅ 支持 PJAX 页面切换
- ✅ 性能无明显影响
代码提取逻辑
-
检测代码块
- CSS 选择器查找标准格式
- TreeWalker 查找容器语法
- 代码块魔改：在代码高亮前拦截
-
提取代码
- 代码块魔改格式：直接提取
textContent - 容器语法：移除
::: mermaid和::: - WPMD 格式：正则提取
document.write()内容 - 标准格式：直接提取文本内容
- 代码块魔改格式：直接提取
-
解码处理
- 先解码 HTML 实体（
<→<） - 再解码转义字符（
\n→ 换行符）
- 先解码 HTML 实体（
-
渲染图表
- 使用 Mermaid.js 库渲染为 SVG
- 应用主题样式（夜间模式适配）
- 错误时显示友好提示
故障排除
问题：容器语法被显示为普通文本
症状：::: mermaid 被显示在页面上
原因：可能被其他插件或主题处理为普通文本
解决：
- 检查是否有其他 Markdown 插件冲突
- 确认 Argon 主题已更新到最新版本
- 查看浏览器控制台是否有 JavaScript 错误
问题：只显示第一个单词
症状：图表渲染失败，错误信息显示 "text": "flowchart"
原因：代码提取不完整
解决：
- 确保使用最新版本的 Argon 主题
- 使用容器语法而不是传统代码块
- 查看控制台日志确认提取到的完整代码
问题：HTML 实体未解码
症状：图表中显示 < 而不是 <
原因：HTML 实体解码失败
解决：
- Argon 主题会自动解码 HTML 实体
- 使用容器语法可避免此问题
- 在 Mermaid 代码中使用引号包裹特殊字符
相关资源
更新日志
2026-01-24
- ✅ 新增代码块魔改支持：支持标准 Markdown 代码块 (
```mermaid) - ✅ 在代码高亮之前拦截并转换 mermaid 代码块
- ✅ 完全绕过代码高亮和 WordPress 格式化
- ✅ 特殊字符不被转换（
-->保持不变） - ✅ 换行符正确保留
- ✅ 支持 PJAX 页面切换
- ✅ 添加 Markdown 容器语法支持（
::: mermaid ... :::） - ✅ 修复 WP-Markdown 格式的代码提取问题
- ✅ 改进正则表达式，支持多行代码
- ✅ 添加降级方案和详细日志
- ✅ 修复代码高亮干扰 mermaid 渲染的问题（排除 mermaid 代码块）
- ✅ 修复容器语法中空行导致内容被截断的问题
- ✅ 修复 WP-Markdown 的 document.write 重复输出问题
- ✅ 改进容器语法检测，支持跨多个元素的内容收集
- ✅ 修复换行符丢失问题（将
<br>标签正确转换为换行符）