feat: 实现 Mermaid 代码块魔改支持
- 添加 convertMermaidCodeblocks() 函数，在代码高亮前拦截 mermaid 代码块 - 支持标准 Markdown 代码块 (\\\mermaid) 渲染 - 更新 detectMermaidBlocks() 添加 mermaid-from-codeblock 选择器 - 更新 extractMermaidCode() 支持新容器类型 - 创建测试文件 test-codeblock-magic.html - 更新用户文档、开发者文档和 FAQ - 完全绕过代码高亮和 WordPress 格式化 - 支持 PJAX 页面切换 - 特殊字符和换行符正确保留
This commit is contained in:
1230
docs/mermaid-developer-guide.md
Normal file
1230
docs/mermaid-developer-guide.md
Normal file
File diff suppressed because it is too large
Load Diff
712
docs/mermaid-faq.md
Normal file
712
docs/mermaid-faq.md
Normal file
@@ -0,0 +1,712 @@
|
||||
# Mermaid 图表常见问题解答 (FAQ)
|
||||
|
||||
## 目录
|
||||
|
||||
- [基础问题](#基础问题)
|
||||
- [配置问题](#配置问题)
|
||||
- [渲染问题](#渲染问题)
|
||||
- [兼容性问题](#兼容性问题)
|
||||
- [性能问题](#性能问题)
|
||||
- [高级问题](#高级问题)
|
||||
|
||||
---
|
||||
|
||||
## 基础问题
|
||||
|
||||
### Q1: 什么是 Mermaid？
|
||||
|
||||
**A:** Mermaid 是一个基于 JavaScript 的图表和图形工具，它使用类似 Markdown 的文本语法来创建和修改图表。您可以用简单的文本代码创建流程图、时序图、类图等多种专业图表。
|
||||
|
||||
**优势：**
|
||||
- 📝 文本即代码，易于版本控制
|
||||
- 🎨 自动布局，无需手动调整
|
||||
- 🔄 易于修改和维护
|
||||
- 📱 响应式设计，自适应屏幕
|
||||
|
||||
---
|
||||
|
||||
### Q2: Argon 主题支持哪些 Mermaid 图表类型？
|
||||
|
||||
**A:** Argon 主题支持 Mermaid 的所有主要图表类型：
|
||||
|
||||
1. **流程图 (Flowchart)** - 展示流程和决策
|
||||
2. **时序图 (Sequence Diagram)** - 描述对象交互
|
||||
3. **类图 (Class Diagram)** - 展示类结构
|
||||
4. **状态图 (State Diagram)** - 表示状态转换
|
||||
5. **饼图 (Pie Chart)** - 显示数据占比
|
||||
6. **甘特图 (Gantt Chart)** - 项目进度管理
|
||||
7. **用户旅程图 (User Journey)** - 用户体验流程
|
||||
8. **Git 图 (Git Graph)** - 版本控制可视化
|
||||
|
||||
详细示例请参考[用户指南](mermaid-user-guide.md#支持的图表类型)。
|
||||
|
||||
---
|
||||
|
||||
### Q3: 如何在文章中插入 Mermaid 图表？
|
||||
|
||||
**A:** 有三种方式：
|
||||
|
||||
**方式 1：标准 Markdown 代码块**（推荐）⭐
|
||||
````markdown
|
||||
三个反引号mermaid
|
||||
flowchart TD
|
||||
A[开始] --> B[结束]
|
||||
三个反引号
|
||||
````
|
||||
|
||||
**优点：**
|
||||
- ✅ 符合标准 Markdown 语法
|
||||
- ✅ 在所有 Markdown 编辑器中都能正确显示
|
||||
- ✅ 易于迁移到其他平台（GitHub、GitLab、Typora 等）
|
||||
- ✅ 主题自动拦截处理，避免代码高亮干扰
|
||||
|
||||
**方式 2：Markdown 容器语法**（备选）
|
||||
````markdown
|
||||
::: mermaid
|
||||
flowchart TD
|
||||
A[开始] --> B[结束]
|
||||
:::
|
||||
````
|
||||
|
||||
**优点：**
|
||||
- ✅ 符合 Markdown 扩展规范（VuePress、Docusaurus 等）
|
||||
- ✅ 不会被 WP-Markdown 当作代码块处理
|
||||
|
||||
**方式 3：Shortcode 格式**（兼容）
|
||||
```
|
||||
[mermaid]
|
||||
flowchart TD
|
||||
A[开始] --> B[结束]
|
||||
[/mermaid]
|
||||
```
|
||||
|
||||
**优点：**
|
||||
- ✅ WordPress 原生支持
|
||||
- ✅ 兼容性最好
|
||||
|
||||
**缺点：**
|
||||
- ❌ 不符合 Markdown 标准
|
||||
- ❌ 在其他平台无法使用
|
||||
|
||||
---
|
||||
|
||||
### Q4: 为什么推荐使用标准 Markdown 代码块？
|
||||
|
||||
**A:** 因为标准 Markdown 代码块 (` ```mermaid `) 是最通用的方式：
|
||||
|
||||
- **GitHub** 使用这种语法
|
||||
- **GitLab** 使用这种语法
|
||||
- **Typora** 使用这种语法
|
||||
- **VS Code** 使用这种语法
|
||||
- **符合 CommonMark 规范**
|
||||
|
||||
Argon 主题通过**代码块魔改**技术，在代码高亮之前拦截并转换 mermaid 代码块，因此：
|
||||
- ✅ 不会被代码高亮处理（无行号、无控制按钮）
|
||||
- ✅ 不会有字符转义问题（`-->` 保持不变）
|
||||
- ✅ 不会有嵌套结构问题
|
||||
- ✅ 完全符合标准 Markdown 语法
|
||||
- ✅ 易于迁移到其他平台
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A --> B
|
||||
```
|
||||
````
|
||||
|
||||
**方式 2：HTML 标签**
|
||||
```html
|
||||
<div class="mermaid">
|
||||
flowchart TD
|
||||
A --> B
|
||||
</div>
|
||||
```
|
||||
|
||||
**注意：** 使用前需要在主题设置中启用 Mermaid 支持。
|
||||
|
||||
---
|
||||
|
||||
### Q4: 需要安装额外的插件吗？
|
||||
|
||||
**A:** 不需要。Argon 主题内置了 Mermaid 支持，开箱即用。
|
||||
|
||||
**但是：**
|
||||
- 如果您已经安装了 Mermaid 相关插件（如 WP Githuber MD），主题会自动检测并避免重复加载
|
||||
- 主题会智能判断是否需要加载 Mermaid 库
|
||||
|
||||
---
|
||||
|
||||
## 配置问题
|
||||
|
||||
### Q5: 如何启用 Mermaid 支持？
|
||||
|
||||
**A:** 按照以下步骤操作：
|
||||
|
||||
1. 登录 WordPress 后台
|
||||
2. 进入 **外观 → Argon 主题设置**
|
||||
3. 找到 **Mermaid 图表** 分类
|
||||
4. 勾选 **"启用 Mermaid 支持"**
|
||||
5. 点击 **"保存设置"**
|
||||
|
||||
---
|
||||
|
||||
### Q6: 应该选择哪个 CDN 来源？
|
||||
|
||||
**A:** 推荐选择：
|
||||
|
||||
**首选：jsDelivr CDN**
|
||||
- ✅ 全球 CDN，速度快
|
||||
- ✅ 稳定性高
|
||||
- ✅ 免费使用
|
||||
|
||||
**备选：unpkg CDN**
|
||||
- 作为备用选项
|
||||
|
||||
**特殊情况：**
|
||||
- **内网环境** → 使用本地文件
|
||||
- **特定版本需求** → 使用自定义 CDN
|
||||
- **极致速度** → 下载本地文件
|
||||
|
||||
**主题优势：** 即使主 CDN 失败，主题会自动尝试备用 CDN，确保可用性。
|
||||
|
||||
---
|
||||
|
||||
### Q7: 如何使用自定义 CDN？
|
||||
|
||||
**A:** 步骤如下：
|
||||
|
||||
1. 在 **CDN 来源** 中选择 **"自定义 CDN 地址"**
|
||||
2. 在 **自定义 CDN 地址** 输入框中填入完整的 URL
|
||||
3. 保存设置
|
||||
|
||||
**URL 格式要求：**
|
||||
- 必须是有效的 URL
|
||||
- 必须以 `.js` 结尾
|
||||
- 必须使用 `http://` 或 `https://` 协议
|
||||
|
||||
**示例：**
|
||||
```
|
||||
https://cdn.example.com/mermaid@10.0.0/mermaid.min.js
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Q8: 图表主题应该选择哪个？
|
||||
|
||||
**A:** 推荐选择 **"自动切换"**。
|
||||
|
||||
**原因：**
|
||||
- 自动跟随页面的日间/夜间模式
|
||||
- 日间模式使用浅色主题
|
||||
- 夜间模式使用深色主题
|
||||
- 用户体验最佳
|
||||
|
||||
**其他选项：**
|
||||
- **默认主题** - 固定使用浅色
|
||||
- **深色主题** - 固定使用深色
|
||||
- **森林主题** - 绿色主题
|
||||
- **中性主题** - 灰色主题
|
||||
|
||||
---
|
||||
|
||||
### Q9: 什么时候需要启用调试模式？
|
||||
|
||||
**A:** 在以下情况下启用：
|
||||
|
||||
1. **图表不显示** - 查看是否有加载错误
|
||||
2. **渲染失败** - 查看详细的错误信息
|
||||
3. **主题切换异常** - 检查主题切换逻辑
|
||||
4. **CDN 加载问题** - 查看 CDN 加载状态
|
||||
5. **开发测试** - 开发新功能时调试
|
||||
|
||||
**如何使用：**
|
||||
1. 启用调试模式
|
||||
2. 打开浏览器开发者工具（F12）
|
||||
3. 切换到"控制台"标签
|
||||
4. 查看以 `[Argon Mermaid]` 开头的日志
|
||||
|
||||
**注意：** 生产环境建议关闭调试模式。
|
||||
|
||||
---
|
||||
|
||||
## 渲染问题
|
||||
|
||||
### Q10: 图表不显示，只显示代码怎么办？
|
||||
|
||||
**A:** 按以下步骤排查：
|
||||
|
||||
**步骤 1：检查是否启用**
|
||||
- 确认主题设置中已启用 Mermaid 支持
|
||||
|
||||
**步骤 2：检查代码格式**
|
||||
- 确认使用了正确的代码块格式
|
||||
- 检查是否有语法错误
|
||||
|
||||
**步骤 3：检查浏览器控制台**
|
||||
- 按 F12 打开开发者工具
|
||||
- 查看是否有 JavaScript 错误
|
||||
|
||||
**步骤 4：启用调试模式**
|
||||
- 在主题设置中启用调试模式
|
||||
- 查看详细的日志信息
|
||||
|
||||
**步骤 5：验证代码**
|
||||
- 访问 [Mermaid Live Editor](https://mermaid.live/)
|
||||
- 粘贴代码验证语法是否正确
|
||||
|
||||
---
|
||||
|
||||
### Q11: 图表显示"渲染失败"错误？
|
||||
|
||||
**A:** 这通常是代码语法错误导致的。
|
||||
|
||||
**解决方法：**
|
||||
|
||||
1. **查看错误详情**
|
||||
- 点击错误提示中的"查看原始代码"
|
||||
- 查看错误类型和错误信息
|
||||
|
||||
2. **常见语法错误：**
|
||||
- 缺少必要的关键字
|
||||
- 箭头符号错误
|
||||
- 节点 ID 重复
|
||||
- 引号不匹配
|
||||
- 缩进不正确
|
||||
|
||||
3. **使用在线编辑器验证**
|
||||
- 访问 [Mermaid Live Editor](https://mermaid.live/)
|
||||
- 粘贴代码并查看错误提示
|
||||
- 根据提示修正语法
|
||||
|
||||
4. **参考官方文档**
|
||||
- [Mermaid 语法参考](https://mermaid.js.org/intro/syntax-reference.html)
|
||||
- 查看对应图表类型的语法规则
|
||||
|
||||
---
|
||||
|
||||
### Q12: 图表在夜间模式下看不清？
|
||||
|
||||
**A:** 这是主题配置问题。
|
||||
|
||||
**解决方法：**
|
||||
|
||||
1. 进入 **主题设置 → Mermaid 图表 → 外观设置**
|
||||
2. 将 **图表主题** 设置为 **"自动切换"**
|
||||
3. 保存设置
|
||||
|
||||
**原理：**
|
||||
- 自动切换模式会检测页面主题
|
||||
- 日间模式使用浅色图表主题
|
||||
- 夜间模式使用深色图表主题
|
||||
|
||||
**如果仍有问题：**
|
||||
- 清除浏览器缓存
|
||||
- 刷新页面
|
||||
- 检查是否有其他 CSS 冲突
|
||||
|
||||
---
|
||||
|
||||
### Q13: 图表太大，超出容器怎么办？
|
||||
|
||||
**A:** Mermaid 图表会自动适应容器宽度，但如果图表过于复杂，可能会出现问题。
|
||||
|
||||
**解决方法：**
|
||||
|
||||
**方法 1：简化图表**
|
||||
- 减少节点数量
|
||||
- 拆分为多个小图表
|
||||
- 使用子图组织内容
|
||||
|
||||
**方法 2：自定义样式**
|
||||
```css
|
||||
.mermaid-container {
|
||||
max-width: 100%;
|
||||
overflow-x: auto;
|
||||
}
|
||||
|
||||
.mermaid-container svg {
|
||||
max-width: 100%;
|
||||
height: auto;
|
||||
}
|
||||
```
|
||||
|
||||
**方法 3：调整图表方向**
|
||||
```mermaid
|
||||
flowchart LR /* 横向布局 */
|
||||
A --> B
|
||||
```
|
||||
|
||||
```mermaid
|
||||
flowchart TD /* 纵向布局 */
|
||||
A --> B
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Q14: 如何在评论中使用 Mermaid？
|
||||
|
||||
**A:** 评论中需要使用 HTML 格式。
|
||||
|
||||
**步骤：**
|
||||
|
||||
1. **确保评论允许 HTML**
|
||||
- 检查 WordPress 评论设置
|
||||
- 确认允许使用 HTML 标签
|
||||
|
||||
2. **使用 HTML 格式**
|
||||
```html
|
||||
<div class="mermaid">
|
||||
flowchart LR
|
||||
A --> B
|
||||
</div>
|
||||
```
|
||||
|
||||
3. **提交评论**
|
||||
- 评论会在前台自动渲染为图表
|
||||
|
||||
**注意：**
|
||||
- 不能使用 Markdown 代码块格式
|
||||
- 必须使用 `<div class="mermaid">` 包裹
|
||||
- 代码需要正确的换行格式
|
||||
|
||||
---
|
||||
|
||||
## 兼容性问题
|
||||
|
||||
### Q15: 与其他插件冲突怎么办？
|
||||
|
||||
**A:** Argon 主题内置了智能兼容机制。
|
||||
|
||||
**自动检测的插件：**
|
||||
- WP Githuber MD
|
||||
- Markdown Block
|
||||
- Code Syntax Block
|
||||
|
||||
**兼容策略：**
|
||||
1. 主题会自动检测已安装的 Mermaid 插件
|
||||
2. 如果检测到插件，主题只提供样式增强
|
||||
3. 避免重复加载 Mermaid 库
|
||||
|
||||
**查看兼容性状态：**
|
||||
1. 进入 **主题设置 → Mermaid 图表 → 高级选项**
|
||||
2. 查看 **插件兼容性检测** 部分
|
||||
3. 查看检测结果和建议
|
||||
|
||||
**如果仍有冲突：**
|
||||
- 禁用主题的 Mermaid 支持，使用插件
|
||||
- 或禁用插件，使用主题的 Mermaid 支持
|
||||
- 不要同时启用多个 Mermaid 功能
|
||||
|
||||
---
|
||||
|
||||
### Q16: 检测到多个 Mermaid 插件怎么办？
|
||||
|
||||
**A:** 这会导致重复加载和冲突。
|
||||
|
||||
**建议：**
|
||||
1. **只保留一个** - 选择功能最完善的插件
|
||||
2. **或使用主题** - 禁用所有插件，使用主题的 Mermaid 支持
|
||||
|
||||
**如何选择：**
|
||||
- **插件功能更多** → 禁用主题支持，使用插件
|
||||
- **主题集成更好** → 禁用插件，使用主题支持
|
||||
- **性能优先** → 使用主题支持（按需加载）
|
||||
|
||||
---
|
||||
|
||||
### Q17: 在不同编辑器中如何使用？
|
||||
|
||||
**A:** 不同编辑器使用方法略有不同。
|
||||
|
||||
**Gutenberg 编辑器：**
|
||||
1. 添加"代码"块或"自定义 HTML"块
|
||||
2. 输入 Mermaid 代码
|
||||
3. 使用 `<div class="mermaid">` 包裹
|
||||
|
||||
**经典编辑器：**
|
||||
1. 切换到"文本"模式
|
||||
2. 使用 HTML 格式
|
||||
3. 使用 `<div class="mermaid">` 包裹
|
||||
|
||||
**Markdown 编辑器（如 WP-Markdown）：**
|
||||
1. 使用代码块语法
|
||||
2. 指定语言为 `mermaid`
|
||||
````markdown
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A --> B
|
||||
```
|
||||
````
|
||||
|
||||
**WP Githuber MD：**
|
||||
- 插件自带 Mermaid 支持
|
||||
- 主题会自动检测并避免冲突
|
||||
- 使用插件的 Mermaid 功能即可
|
||||
|
||||
---
|
||||
|
||||
## 性能问题
|
||||
|
||||
### Q18: Mermaid 会影响页面加载速度吗？
|
||||
|
||||
**A:** 主题已做了充分的性能优化。
|
||||
|
||||
**优化措施：**
|
||||
|
||||
1. **按需加载**
|
||||
- 只在包含 Mermaid 代码的页面加载库
|
||||
- 没有 Mermaid 代码的页面不加载
|
||||
|
||||
2. **异步加载**
|
||||
- Mermaid 库使用 async 属性异步加载
|
||||
- 不阻塞页面渲染
|
||||
|
||||
3. **CDN 加速**
|
||||
- 使用全球 CDN 加速加载
|
||||
- 浏览器缓存减少重复加载
|
||||
|
||||
4. **智能检测**
|
||||
- 检测插件是否已加载库
|
||||
- 避免重复加载
|
||||
|
||||
**实际影响：**
|
||||
- Mermaid 库大小约 300KB（gzip 后约 100KB）
|
||||
- 首次加载约 0.5-1 秒
|
||||
- 后续访问使用缓存，几乎无影响
|
||||
|
||||
---
|
||||
|
||||
### Q19: 一篇文章可以使用多少个图表？
|
||||
|
||||
**A:** 技术上没有限制，但建议控制数量。
|
||||
|
||||
**建议：**
|
||||
- **小型图表** - 不超过 10 个
|
||||
- **中型图表** - 不超过 5 个
|
||||
- **大型图表** - 不超过 3 个
|
||||
|
||||
**原因：**
|
||||
- 过多图表会增加渲染时间
|
||||
- 影响页面性能
|
||||
- 用户体验下降
|
||||
|
||||
**优化建议：**
|
||||
1. 合并相关图表
|
||||
2. 使用子图组织内容
|
||||
3. 复杂图表考虑使用图片替代
|
||||
4. 分页展示大量图表
|
||||
|
||||
---
|
||||
|
||||
### Q20: 如何优化 Mermaid 性能？
|
||||
|
||||
**A:** 以下是一些优化建议：
|
||||
|
||||
**1. 使用本地文件**
|
||||
- 下载 Mermaid 库到主题目录
|
||||
- 启用"使用本地镜像"
|
||||
- 减少网络请求
|
||||
|
||||
**2. 简化图表**
|
||||
- 减少节点数量
|
||||
- 避免过于复杂的关系
|
||||
- 使用简洁的文本
|
||||
|
||||
**3. 启用浏览器缓存**
|
||||
- CDN 文件会自动缓存
|
||||
- 减少重复加载
|
||||
|
||||
**4. 按需加载**
|
||||
- 主题已自动实现
|
||||
- 只在需要时加载库
|
||||
|
||||
**5. 使用 CDN**
|
||||
- 利用 CDN 的全球加速
|
||||
- 减少服务器负载
|
||||
|
||||
---
|
||||
|
||||
## 高级问题
|
||||
|
||||
### Q21: 如何自定义 Mermaid 样式？
|
||||
|
||||
**A:** 可以通过 CSS 自定义样式。
|
||||
|
||||
**方法 1：使用主题自定义 CSS**
|
||||
1. 进入 **外观 → 自定义 → 额外 CSS**
|
||||
2. 添加自定义样式
|
||||
|
||||
**示例：**
|
||||
```css
|
||||
/* 自定义图表容器样式 */
|
||||
.mermaid-container {
|
||||
background: #f5f5f5;
|
||||
padding: 20px;
|
||||
border-radius: 8px;
|
||||
box-shadow: 0 2px 8px rgba(0,0,0,0.1);
|
||||
}
|
||||
|
||||
/* 自定义错误提示样式 */
|
||||
.mermaid-error-container {
|
||||
background: #fff3cd;
|
||||
border-left: 4px solid #ffc107;
|
||||
}
|
||||
```
|
||||
|
||||
**方法 2：修改主题文件**
|
||||
- 编辑 `style.css`
|
||||
- 在 Mermaid 相关部分添加样式
|
||||
- 不推荐（主题更新会覆盖）
|
||||
|
||||
---
|
||||
|
||||
### Q22: 如何导出 Mermaid 图表为图片？
|
||||
|
||||
**A:** 有多种方法可以导出图表。
|
||||
|
||||
**方法 1：使用 Mermaid Live Editor**
|
||||
1. 访问 [Mermaid Live Editor](https://mermaid.live/)
|
||||
2. 粘贴代码
|
||||
3. 点击"Export"按钮
|
||||
4. 选择 PNG 或 SVG 格式
|
||||
|
||||
**方法 2：浏览器截图**
|
||||
1. 在浏览器中打开文章
|
||||
2. 使用截图工具截取图表
|
||||
3. Windows: Win + Shift + S
|
||||
4. Mac: Cmd + Shift + 4
|
||||
|
||||
**方法 3：开发者工具**
|
||||
1. 右键点击图表 → 检查元素
|
||||
2. 找到 SVG 元素
|
||||
3. 右键 → Copy → Copy outerHTML
|
||||
4. 保存为 .svg 文件
|
||||
5. 使用工具转换为 PNG
|
||||
|
||||
**方法 4：使用插件**
|
||||
- 安装浏览器截图插件
|
||||
- 如 Awesome Screenshot
|
||||
- 直接截取并保存
|
||||
|
||||
---
|
||||
|
||||
### Q23: 如何在 Mermaid 代码中使用中文？
|
||||
|
||||
**A:** Mermaid 完全支持中文，直接使用即可。
|
||||
|
||||
**示例：**
|
||||
```mermaid
|
||||
flowchart TD
|
||||
开始([开始]) --> 处理[处理数据]
|
||||
处理 --> 判断{是否成功?}
|
||||
判断 -->|是| 成功([成功])
|
||||
判断 -->|否| 失败([失败])
|
||||
```
|
||||
|
||||
**注意事项：**
|
||||
1. **引号问题**
|
||||
- 如果文本包含特殊字符，使用引号包裹
|
||||
- `A["包含特殊字符的文本"]`
|
||||
|
||||
2. **编码问题**
|
||||
- 确保文件编码为 UTF-8
|
||||
- WordPress 默认使用 UTF-8
|
||||
|
||||
3. **字体问题**
|
||||
- 确保浏览器支持中文字体
|
||||
- 现代浏览器都支持
|
||||
|
||||
---
|
||||
|
||||
### Q24: 如何在 Mermaid 中添加链接？
|
||||
|
||||
**A:** Mermaid 支持为节点添加链接。
|
||||
|
||||
**语法：**
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[节点 A]
|
||||
B[节点 B]
|
||||
A --> B
|
||||
click A "https://example.com" "点击访问"
|
||||
click B "https://example.com" _blank
|
||||
```
|
||||
|
||||
**参数说明：**
|
||||
- 第一个参数：节点 ID
|
||||
- 第二个参数：链接 URL
|
||||
- 第三个参数：提示文本或打开方式
|
||||
- `"提示文本"` - 鼠标悬停提示
|
||||
- `_blank` - 新标签页打开
|
||||
- `_self` - 当前标签页打开
|
||||
|
||||
---
|
||||
|
||||
### Q25: 如何使用 Mermaid 的高级功能？
|
||||
|
||||
**A:** Mermaid 支持许多高级功能。
|
||||
|
||||
**1. 子图 (Subgraph)**
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph 输入阶段
|
||||
A[接收] --> B[验证]
|
||||
end
|
||||
subgraph 处理阶段
|
||||
B --> C[处理]
|
||||
end
|
||||
```
|
||||
|
||||
**2. 样式定义**
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[节点 A]
|
||||
B[节点 B]
|
||||
A --> B
|
||||
style A fill:#f9f,stroke:#333,stroke-width:4px
|
||||
style B fill:#bbf,stroke:#333,stroke-width:2px
|
||||
```
|
||||
|
||||
**3. 类样式**
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[节点 A]:::someclass
|
||||
B[节点 B]:::someclass
|
||||
classDef someclass fill:#f96,stroke:#333
|
||||
```
|
||||
|
||||
**4. 注释**
|
||||
```mermaid
|
||||
%% 这是注释，不会显示
|
||||
flowchart TD
|
||||
A --> B %% 行尾注释
|
||||
```
|
||||
|
||||
**更多功能：**
|
||||
- 查看 [Mermaid 官方文档](https://mermaid.js.org/)
|
||||
- 参考各图表类型的详细语法
|
||||
|
||||
---
|
||||
|
||||
## 获取更多帮助
|
||||
|
||||
### 官方资源
|
||||
|
||||
- 📚 [Mermaid 官方文档](https://mermaid.js.org/)
|
||||
- 🎨 [Mermaid Live Editor](https://mermaid.live/)
|
||||
- 💬 [Mermaid GitHub](https://github.com/mermaid-js/mermaid)
|
||||
|
||||
### Argon 主题支持
|
||||
|
||||
- 🐛 [提交 Issue](https://github.com/solstice23/argon-theme/issues)
|
||||
- 📖 [主题文档](https://github.com/solstice23/argon-theme)
|
||||
- 💡 [用户指南](mermaid-user-guide.md)
|
||||
|
||||
### 社区资源
|
||||
|
||||
- 🌐 WordPress 论坛
|
||||
- 💬 主题用户群
|
||||
- 📝 技术博客和教程
|
||||
|
||||
---
|
||||
|
||||
**最后更新：** 2024-01-22
|
||||
**文档版本：** 1.0.0
|
||||
@@ -2,7 +2,30 @@
|
||||
|
||||
## 推荐的标记方式
|
||||
|
||||
### Markdown 容器语法（推荐）⭐
|
||||
### 1. 标准 Markdown 代码块（推荐）⭐
|
||||
|
||||
```markdown
|
||||
三个反引号mermaid
|
||||
flowchart TD
|
||||
A[开始] --> B[处理]
|
||||
B --> C[结束]
|
||||
三个反引号
|
||||
```
|
||||
|
||||
**优点**：
|
||||
- ✅ 符合标准 Markdown 语法
|
||||
- ✅ 在所有 Markdown 编辑器中都能正确显示
|
||||
- ✅ 支持语法高亮（编辑器层面）
|
||||
- ✅ 易于迁移到其他平台（GitHub、GitLab、Typora 等）
|
||||
- ✅ 主题自动拦截处理，避免代码高亮干扰
|
||||
- ✅ 支持所有 Mermaid 图表类型
|
||||
|
||||
**工作原理**：
|
||||
- 主题在代码高亮之前拦截 mermaid 代码块
|
||||
- 自动转换为 Mermaid 渲染容器
|
||||
- 完全绕过代码高亮和 WordPress 格式化
|
||||
|
||||
### 2. Markdown 容器语法（备选）
|
||||
|
||||
```markdown
|
||||
::: mermaid
|
||||
@@ -20,19 +43,41 @@ flowchart TD
|
||||
- ✅ 在纯文本编辑器中也很清晰
|
||||
- ✅ 易于迁移到其他平台
|
||||
|
||||
### 为什么使用容器语法？
|
||||
### 3. Shortcode 格式（兼容）
|
||||
|
||||
**Markdown 容器语法** (`::: mermaid ... :::`) 是现代 Markdown 扩展的标准方式：
|
||||
```
|
||||
[mermaid]
|
||||
flowchart TD
|
||||
A[开始] --> B[处理]
|
||||
B --> C[结束]
|
||||
[/mermaid]
|
||||
```
|
||||
|
||||
- **VuePress** 使用这种语法
|
||||
- **Docusaurus** 使用这种语法
|
||||
- **MkDocs** 使用类似语法
|
||||
- **符合 CommonMark 扩展规范**
|
||||
**优点**：
|
||||
- ✅ WordPress 原生支持
|
||||
- ✅ 不会被任何插件干扰
|
||||
- ✅ 兼容性最好
|
||||
|
||||
这种语法不会被 WP-Markdown 插件当作代码块处理，因此：
|
||||
- 不会被套上代码高亮窗口
|
||||
**缺点**：
|
||||
- ❌ 不符合 Markdown 标准
|
||||
- ❌ 在其他平台无法使用
|
||||
- ❌ 编辑器中不显示为代码块
|
||||
|
||||
### 为什么推荐标准 Markdown 代码块？
|
||||
|
||||
**标准 Markdown 代码块** (` ```mermaid `) 是最通用的方式：
|
||||
|
||||
- **GitHub** 使用这种语法
|
||||
- **GitLab** 使用这种语法
|
||||
- **Typora** 使用这种语法
|
||||
- **VS Code** 使用这种语法
|
||||
- **符合 CommonMark 规范**
|
||||
|
||||
Argon 主题通过**代码块魔改**技术，在代码高亮之前拦截并转换 mermaid 代码块，因此：
|
||||
- 不会被代码高亮处理（无行号、无控制按钮）
|
||||
- 不会有字符转义问题（`-->` 保持不变）
|
||||
- 不会有嵌套结构问题
|
||||
- 不会有字符转义问题
|
||||
- 完全符合标准 Markdown 语法
|
||||
|
||||
---
|
||||
|
||||
@@ -40,6 +85,17 @@ flowchart TD
|
||||
|
||||
### 流程图
|
||||
|
||||
**标准 Markdown 代码块：**
|
||||
```markdown
|
||||
三个反引号mermaid
|
||||
flowchart LR
|
||||
A[用户] --> B{登录?}
|
||||
B -->|是| C[显示首页]
|
||||
B -->|否| D[跳转登录页]
|
||||
三个反引号
|
||||
```
|
||||
|
||||
**容器语法：**
|
||||
```markdown
|
||||
::: mermaid
|
||||
flowchart LR
|
||||
@@ -52,18 +108,18 @@ flowchart LR
|
||||
### 时序图
|
||||
|
||||
```markdown
|
||||
::: mermaid
|
||||
三个反引号mermaid
|
||||
sequenceDiagram
|
||||
Alice->>Bob: Hello Bob!
|
||||
Bob-->>Alice: Hi Alice!
|
||||
Alice->>Bob: How are you?
|
||||
:::
|
||||
三个反引号
|
||||
```
|
||||
|
||||
### 类图
|
||||
|
||||
```markdown
|
||||
::: mermaid
|
||||
三个反引号mermaid
|
||||
classDiagram
|
||||
class Animal {
|
||||
+String name
|
||||
@@ -75,13 +131,13 @@ classDiagram
|
||||
+bark()
|
||||
}
|
||||
Animal <|-- Dog
|
||||
:::
|
||||
三个反引号
|
||||
```
|
||||
|
||||
### 甘特图
|
||||
|
||||
```markdown
|
||||
::: mermaid
|
||||
三个反引号mermaid
|
||||
gantt
|
||||
title 项目进度
|
||||
dateFormat YYYY-MM-DD
|
||||
@@ -91,31 +147,31 @@ gantt
|
||||
section 开发
|
||||
前端开发 :b1, after a2, 10d
|
||||
后端开发 :b2, after a2, 12d
|
||||
:::
|
||||
三个反引号
|
||||
```
|
||||
|
||||
### 状态图
|
||||
|
||||
```markdown
|
||||
::: mermaid
|
||||
三个反引号mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> 待审核
|
||||
待审核 --> 已通过: 审核通过
|
||||
待审核 --> 已拒绝: 审核拒绝
|
||||
已通过 --> [*]
|
||||
已拒绝 --> [*]
|
||||
:::
|
||||
三个反引号
|
||||
```
|
||||
|
||||
### 饼图
|
||||
|
||||
```markdown
|
||||
::: mermaid
|
||||
三个反引号mermaid
|
||||
pie title 宠物分布
|
||||
"狗" : 386
|
||||
"猫" : 85
|
||||
"兔子" : 15
|
||||
:::
|
||||
三个反引号
|
||||
```
|
||||
|
||||
---
|
||||
@@ -195,22 +251,30 @@ pie title 宠物分布
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 使用容器语法
|
||||
### 1. 使用标准 Markdown 代码块
|
||||
|
||||
**推荐：**
|
||||
```markdown
|
||||
三个反引号mermaid
|
||||
flowchart TD
|
||||
A --> B
|
||||
三个反引号
|
||||
```
|
||||
|
||||
**也可以使用容器语法：**
|
||||
```markdown
|
||||
::: mermaid
|
||||
flowchart TD
|
||||
A --> B
|
||||
:::
|
||||
```
|
||||
|
||||
**不推荐：**
|
||||
**不推荐（Shortcode）：**
|
||||
```
|
||||
三个反引号mermaid
|
||||
[mermaid]
|
||||
flowchart TD
|
||||
A --> B
|
||||
三个反引号
|
||||
[/mermaid]
|
||||
```
|
||||
|
||||
### 2. 避免特殊字符
|
||||
@@ -252,19 +316,48 @@ flowchart TD
|
||||
|
||||
Argon 主题支持以下格式（按优先级排序）：
|
||||
|
||||
1. `::: mermaid ... :::` - Markdown 容器语法 ⭐（推荐）
|
||||
2. `<div class="mermaid">` - 标准格式（WPMD 生成）
|
||||
3. `<pre><code class="language-mermaid">` - Markdown 格式
|
||||
4. `<pre data-lang="mermaid">` - 自定义属性格式
|
||||
5. `<code class="mermaid">` - 简化格式
|
||||
1. ` ```mermaid ... ``` ` - 标准 Markdown 代码块 ⭐（推荐）
|
||||
2. `::: mermaid ... :::` - Markdown 容器语法（备选）
|
||||
3. `[mermaid]...[/mermaid]` - Shortcode 格式（兼容）
|
||||
4. `<div class="mermaid">` - 标准格式（WPMD 生成）
|
||||
5. `<pre><code class="language-mermaid">` - Markdown 格式（降级）
|
||||
6. `<pre data-lang="mermaid">` - 自定义属性格式
|
||||
7. `<code class="mermaid">` - 简化格式
|
||||
|
||||
### 代码块魔改技术
|
||||
|
||||
**工作原理**：
|
||||
|
||||
1. **拦截阶段**（在代码高亮之前）
|
||||
- 查找所有 `<pre><code class="language-mermaid">` 元素
|
||||
- 提取纯文本代码（使用 `textContent`）
|
||||
- 创建 `<div class="mermaid-from-codeblock">` 容器
|
||||
- 替换原始代码块元素
|
||||
|
||||
2. **代码高亮阶段**
|
||||
- 处理其他代码块
|
||||
- 跳过 mermaid 相关的元素
|
||||
|
||||
3. **Mermaid 渲染阶段**
|
||||
- 检测所有 Mermaid 容器（包括新的 `mermaid-from-codeblock`）
|
||||
- 提取代码并渲染为 SVG 图表
|
||||
|
||||
**优势**：
|
||||
- ✅ 完全绕过代码高亮干扰
|
||||
- ✅ 特殊字符不被转换（`-->` 保持不变）
|
||||
- ✅ 换行符正确保留
|
||||
- ✅ 支持 PJAX 页面切换
|
||||
- ✅ 性能无明显影响
|
||||
|
||||
### 代码提取逻辑
|
||||
|
||||
1. **检测代码块**
|
||||
- CSS 选择器查找标准格式
|
||||
- TreeWalker 查找容器语法
|
||||
- 代码块魔改：在代码高亮前拦截
|
||||
|
||||
2. **提取代码**
|
||||
- 代码块魔改格式：直接提取 `textContent`
|
||||
- 容器语法：移除 `::: mermaid` 和 `:::`
|
||||
- WPMD 格式：正则提取 `document.write()` 内容
|
||||
- 标准格式：直接提取文本内容
|
||||
@@ -329,11 +422,16 @@ Argon 主题支持以下格式（按优先级排序）：
|
||||
## 更新日志
|
||||
|
||||
### 2026-01-24
|
||||
- ✅ **新增代码块魔改支持**：支持标准 Markdown 代码块 (` ```mermaid `)
|
||||
- ✅ 在代码高亮之前拦截并转换 mermaid 代码块
|
||||
- ✅ 完全绕过代码高亮和 WordPress 格式化
|
||||
- ✅ 特殊字符不被转换（`-->` 保持不变）
|
||||
- ✅ 换行符正确保留
|
||||
- ✅ 支持 PJAX 页面切换
|
||||
- ✅ 添加 Markdown 容器语法支持（`::: mermaid ... :::`）
|
||||
- ✅ 修复 WP-Markdown 格式的代码提取问题
|
||||
- ✅ 改进正则表达式，支持多行代码
|
||||
- ✅ 添加降级方案和详细日志
|
||||
- ✅ 简化标记方式，只保留容器语法作为推荐方式
|
||||
- ✅ 修复代码高亮干扰 mermaid 渲染的问题（排除 mermaid 代码块）
|
||||
- ✅ 修复容器语法中空行导致内容被截断的问题
|
||||
- ✅ 修复 WP-Markdown 的 document.write 重复输出问题
|
||||
|
||||
719
docs/mermaid-user-guide.md
Normal file
719
docs/mermaid-user-guide.md
Normal file
@@ -0,0 +1,719 @@
|
||||
# Argon 主题 Mermaid 图表使用指南
|
||||
|
||||
## 目录
|
||||
|
||||
1. [功能简介](#功能简介)
|
||||
2. [快速开始](#快速开始)
|
||||
3. [支持的图表类型](#支持的图表类型)
|
||||
4. [使用方法](#使用方法)
|
||||
5. [主题设置](#主题设置)
|
||||
6. [常见问题](#常见问题)
|
||||
7. [最佳实践](#最佳实践)
|
||||
8. [故障排除](#故障排除)
|
||||
|
||||
---
|
||||
|
||||
## 功能简介
|
||||
|
||||
Argon 主题内置了 Mermaid 图表支持，让您可以在文章中轻松创建各种专业的图表，包括：
|
||||
|
||||
- 📊 **流程图** - 展示业务流程和逻辑关系
|
||||
- 📈 **时序图** - 描述系统交互和时间顺序
|
||||
- 🏗️ **类图** - 展示面向对象的类结构
|
||||
- 📉 **状态图** - 表示状态机和状态转换
|
||||
- 🥧 **饼图** - 显示数据占比
|
||||
- 📅 **甘特图** - 项目进度管理
|
||||
- 🗺️ **用户旅程图** - 用户体验流程
|
||||
- 🌳 **Git 图** - 版本控制分支可视化
|
||||
|
||||
### 主要特性
|
||||
|
||||
✅ **零配置使用** - 开箱即用，无需额外插件
|
||||
✅ **自动主题切换** - 跟随页面日间/夜间模式
|
||||
✅ **智能加载** - 只在需要时加载库文件
|
||||
✅ **插件兼容** - 自动检测并避免重复加载
|
||||
✅ **错误提示** - 友好的错误信息和调试支持
|
||||
✅ **CDN 降级** - 多个 CDN 自动切换，确保可用性
|
||||
|
||||
---
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 启用 Mermaid 支持
|
||||
|
||||
进入 **WordPress 后台 → 外观 → Argon 主题设置 → Mermaid 图表**，勾选"启用 Mermaid 支持"。
|
||||
|
||||
### 2. 在文章中使用
|
||||
|
||||
在文章编辑器中，使用以下格式插入 Mermaid 代码：
|
||||
|
||||
````markdown
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始]) --> Process[处理数据]
|
||||
Process --> End([结束])
|
||||
```
|
||||
````
|
||||
|
||||
或使用 HTML 格式：
|
||||
|
||||
```html
|
||||
<div class="mermaid">
|
||||
flowchart TD
|
||||
Start([开始]) --> Process[处理数据]
|
||||
Process --> End([结束])
|
||||
</div>
|
||||
```
|
||||
|
||||
### 3. 发布并查看
|
||||
|
||||
保存文章后，在前台页面即可看到渲染后的图表。
|
||||
|
||||
---
|
||||
|
||||
## 支持的图表类型
|
||||
|
||||
### 1. 流程图 (Flowchart)
|
||||
|
||||
展示流程和决策逻辑。
|
||||
|
||||
````markdown
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[开始] --> B{判断条件}
|
||||
B -->|是| C[执行操作 A]
|
||||
B -->|否| D[执行操作 B]
|
||||
C --> E[结束]
|
||||
D --> E
|
||||
```
|
||||
````
|
||||
|
||||
**节点形状：**
|
||||
- `[文本]` - 矩形
|
||||
- `([文本])` - 圆角矩形
|
||||
- `{文本}` - 菱形（判断）
|
||||
- `((文本))` - 圆形
|
||||
- `[[文本]]` - 子程序
|
||||
|
||||
### 2. 时序图 (Sequence Diagram)
|
||||
|
||||
描述对象之间的交互顺序。
|
||||
|
||||
````markdown
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant 用户
|
||||
participant 服务器
|
||||
participant 数据库
|
||||
|
||||
用户->>服务器: 发送请求
|
||||
服务器->>数据库: 查询数据
|
||||
数据库-->>服务器: 返回结果
|
||||
服务器-->>用户: 响应数据
|
||||
```
|
||||
````
|
||||
|
||||
**箭头类型：**
|
||||
- `->` - 实线箭头
|
||||
- `-->` - 虚线箭头
|
||||
- `->>` - 实线箭头（带箭头）
|
||||
- `-->>` - 虚线箭头（带箭头）
|
||||
|
||||
### 3. 类图 (Class Diagram)
|
||||
|
||||
展示面向对象的类结构。
|
||||
|
||||
````markdown
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Animal {
|
||||
+String name
|
||||
+int age
|
||||
+makeSound()
|
||||
}
|
||||
class Dog {
|
||||
+String breed
|
||||
+bark()
|
||||
}
|
||||
class Cat {
|
||||
+meow()
|
||||
}
|
||||
Animal <|-- Dog
|
||||
Animal <|-- Cat
|
||||
```
|
||||
````
|
||||
|
||||
### 4. 状态图 (State Diagram)
|
||||
|
||||
表示状态机和状态转换。
|
||||
|
||||
````markdown
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> 待处理
|
||||
待处理 --> 处理中: 开始处理
|
||||
处理中 --> 已完成: 处理成功
|
||||
处理中 --> 失败: 处理失败
|
||||
失败 --> 待处理: 重试
|
||||
已完成 --> [*]
|
||||
```
|
||||
````
|
||||
|
||||
### 5. 饼图 (Pie Chart)
|
||||
|
||||
显示数据占比。
|
||||
|
||||
````markdown
|
||||
```mermaid
|
||||
pie title 浏览器市场份额
|
||||
"Chrome" : 65
|
||||
"Safari" : 15
|
||||
"Firefox" : 10
|
||||
"Edge" : 7
|
||||
"其他" : 3
|
||||
```
|
||||
````
|
||||
|
||||
### 6. 甘特图 (Gantt Chart)
|
||||
|
||||
项目进度管理。
|
||||
|
||||
````markdown
|
||||
```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
|
||||
```
|
||||
````
|
||||
|
||||
### 7. 用户旅程图 (User Journey)
|
||||
|
||||
描述用户体验流程。
|
||||
|
||||
````markdown
|
||||
```mermaid
|
||||
journey
|
||||
title 用户购物旅程
|
||||
section 浏览商品
|
||||
访问网站: 5: 用户
|
||||
搜索商品: 3: 用户
|
||||
查看详情: 4: 用户
|
||||
section 下单
|
||||
加入购物车: 4: 用户
|
||||
填写信息: 2: 用户
|
||||
支付: 3: 用户
|
||||
section 收货
|
||||
等待发货: 2: 用户
|
||||
收到商品: 5: 用户
|
||||
```
|
||||
````
|
||||
|
||||
### 8. Git 图 (Git Graph)
|
||||
|
||||
版本控制分支可视化。
|
||||
|
||||
````markdown
|
||||
```mermaid
|
||||
gitGraph
|
||||
commit
|
||||
commit
|
||||
branch develop
|
||||
checkout develop
|
||||
commit
|
||||
commit
|
||||
checkout main
|
||||
merge develop
|
||||
commit
|
||||
```
|
||||
````
|
||||
|
||||
---
|
||||
|
||||
## 使用方法
|
||||
|
||||
### 在 Markdown 编辑器中使用
|
||||
|
||||
如果您使用 Markdown 编辑器（如 WP-Markdown），直接使用代码块语法：
|
||||
|
||||
````markdown
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A --> B
|
||||
B --> C
|
||||
```
|
||||
````
|
||||
|
||||
### 在 Gutenberg 编辑器中使用
|
||||
|
||||
1. 添加"代码"块或"自定义 HTML"块
|
||||
2. 输入 Mermaid 代码
|
||||
3. 使用 `<div class="mermaid">` 包裹
|
||||
|
||||
```html
|
||||
<div class="mermaid">
|
||||
flowchart LR
|
||||
A --> B
|
||||
B --> C
|
||||
</div>
|
||||
```
|
||||
|
||||
### 在经典编辑器中使用
|
||||
|
||||
切换到"文本"模式，使用 HTML 格式：
|
||||
|
||||
```html
|
||||
<div class="mermaid">
|
||||
flowchart LR
|
||||
A --> B
|
||||
B --> C
|
||||
</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 主题设置
|
||||
|
||||
### 基本设置
|
||||
|
||||
#### 启用 Mermaid 支持
|
||||
|
||||
**位置：** Argon 主题设置 → Mermaid 图表 → 基本设置
|
||||
|
||||
勾选此选项以启用 Mermaid 图表渲染功能。
|
||||
|
||||
#### CDN 来源
|
||||
|
||||
选择 Mermaid 库的加载来源：
|
||||
|
||||
- **jsDelivr CDN** (推荐) - 全球 CDN，速度快，稳定性高
|
||||
- **unpkg CDN** - 备用 CDN
|
||||
- **自定义 CDN 地址** - 使用自己的 CDN 或镜像
|
||||
- **本地文件** - 使用主题目录中的本地文件
|
||||
|
||||
**建议：** 使用 jsDelivr CDN，主题会自动在多个 CDN 之间切换以确保可用性。
|
||||
|
||||
#### 自定义 CDN 地址
|
||||
|
||||
当选择"自定义 CDN 地址"时，输入完整的 Mermaid 库 URL。
|
||||
|
||||
**格式要求：**
|
||||
- 必须是有效的 URL
|
||||
- 必须以 `.js` 结尾
|
||||
- 必须使用 `http://` 或 `https://` 协议
|
||||
|
||||
**示例：**
|
||||
```
|
||||
https://cdn.example.com/mermaid@10.0.0/mermaid.min.js
|
||||
```
|
||||
|
||||
### 外观设置
|
||||
|
||||
#### 图表主题
|
||||
|
||||
选择 Mermaid 图表的配色主题：
|
||||
|
||||
- **自动切换** (推荐) - 跟随页面日间/夜间模式自动切换
|
||||
- **默认主题** - 浅色主题，适合日间模式
|
||||
- **深色主题** - 深色主题，适合夜间模式
|
||||
- **森林主题** - 绿色主题
|
||||
- **中性主题** - 灰色主题
|
||||
|
||||
**建议：** 使用"自动切换"，让图表主题与页面主题保持一致。
|
||||
|
||||
### 高级选项
|
||||
|
||||
#### 使用本地镜像
|
||||
|
||||
启用后，如果检测到主题目录中存在 Mermaid 库文件，将优先使用本地文件而不是 CDN。
|
||||
|
||||
**本地文件路径：**
|
||||
```
|
||||
wp-content/themes/argon/assets/vendor/mermaid/mermaid.min.js
|
||||
```
|
||||
|
||||
**适用场景：**
|
||||
- 内网环境无法访问外部 CDN
|
||||
- 需要使用特定版本的 Mermaid
|
||||
- 追求极致的加载速度
|
||||
|
||||
#### 调试模式
|
||||
|
||||
启用后，将在浏览器控制台输出详细的 Mermaid 渲染日志。
|
||||
|
||||
**日志内容包括：**
|
||||
- 初始化状态
|
||||
- 检测到的代码块数量
|
||||
- 渲染成功/失败信息
|
||||
- 主题切换记录
|
||||
- CDN 加载状态
|
||||
|
||||
**使用方法：**
|
||||
1. 启用调试模式
|
||||
2. 打开浏览器开发者工具（F12）
|
||||
3. 切换到"控制台"标签
|
||||
4. 查看以 `[Argon Mermaid]` 开头的日志
|
||||
|
||||
#### 插件兼容性检测
|
||||
|
||||
主题会自动检测已安装的 Mermaid 插件，避免重复加载库文件。
|
||||
|
||||
**支持的插件：**
|
||||
- WP Githuber MD
|
||||
- Markdown Block
|
||||
- Code Syntax Block
|
||||
|
||||
**兼容策略：**
|
||||
- 如果检测到插件，主题将只提供样式增强
|
||||
- 如果未检测到插件，主题将负责加载 Mermaid 库
|
||||
- 如果检测到多个插件，会显示警告信息
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q1: 图表不显示，只显示代码？
|
||||
|
||||
**可能原因：**
|
||||
1. 未启用 Mermaid 支持
|
||||
2. 代码格式不正确
|
||||
3. JavaScript 加载失败
|
||||
|
||||
**解决方法：**
|
||||
1. 检查主题设置中是否启用了 Mermaid 支持
|
||||
2. 确认代码格式正确（参考本文档示例）
|
||||
3. 打开浏览器控制台查看是否有错误信息
|
||||
4. 启用调试模式查看详细日志
|
||||
|
||||
### Q2: 图表显示"渲染失败"错误？
|
||||
|
||||
**可能原因：**
|
||||
1. Mermaid 代码语法错误
|
||||
2. 使用了不支持的图表类型
|
||||
3. 代码格式不符合规范
|
||||
|
||||
**解决方法：**
|
||||
1. 检查代码语法是否正确
|
||||
2. 使用 [Mermaid Live Editor](https://mermaid.live/) 验证代码
|
||||
3. 查看错误提示中的详细信息
|
||||
4. 参考本文档中的示例代码
|
||||
|
||||
### Q3: 图表在夜间模式下看不清？
|
||||
|
||||
**解决方法：**
|
||||
1. 进入主题设置 → Mermaid 图表 → 外观设置
|
||||
2. 将"图表主题"设置为"自动切换"
|
||||
3. 图表会自动跟随页面主题切换
|
||||
|
||||
### Q4: CDN 加载失败怎么办？
|
||||
|
||||
**主题已内置降级机制：**
|
||||
1. 主 CDN 失败时，自动尝试备用 CDN
|
||||
2. 所有 CDN 都失败时，显示友好的错误提示
|
||||
|
||||
**手动解决：**
|
||||
1. 切换到其他 CDN 来源
|
||||
2. 使用自定义 CDN 地址
|
||||
3. 下载本地文件并启用"使用本地镜像"
|
||||
|
||||
### Q5: 与其他插件冲突？
|
||||
|
||||
**主题已内置兼容机制：**
|
||||
- 自动检测已安装的 Mermaid 插件
|
||||
- 避免重复加载库文件
|
||||
- 只提供样式增强功能
|
||||
|
||||
**如果仍有冲突：**
|
||||
1. 查看插件兼容性检测结果
|
||||
2. 禁用主题的 Mermaid 支持，使用插件
|
||||
3. 或禁用插件，使用主题的 Mermaid 支持
|
||||
|
||||
### Q6: 如何在评论中使用 Mermaid？
|
||||
|
||||
**方法：**
|
||||
1. 评论中使用 HTML 格式
|
||||
2. 使用 `<div class="mermaid">` 包裹代码
|
||||
|
||||
**示例：**
|
||||
```html
|
||||
<div class="mermaid">
|
||||
flowchart LR
|
||||
A --> B
|
||||
</div>
|
||||
```
|
||||
|
||||
**注意：** 需要确保评论允许 HTML 标签。
|
||||
|
||||
### Q7: 图表太大，超出容器？
|
||||
|
||||
**解决方法：**
|
||||
1. Mermaid 图表会自动适应容器宽度
|
||||
2. 如果图表过于复杂，考虑简化或拆分
|
||||
3. 使用 CSS 自定义样式调整大小
|
||||
|
||||
**自定义样式示例：**
|
||||
```css
|
||||
.mermaid-container {
|
||||
max-width: 100%;
|
||||
overflow-x: auto;
|
||||
}
|
||||
```
|
||||
|
||||
### Q8: 如何导出图表为图片？
|
||||
|
||||
**方法 1：使用浏览器截图**
|
||||
1. 在浏览器中打开文章
|
||||
2. 使用截图工具截取图表部分
|
||||
|
||||
**方法 2：使用 Mermaid Live Editor**
|
||||
1. 访问 [Mermaid Live Editor](https://mermaid.live/)
|
||||
2. 粘贴代码
|
||||
3. 点击"Export"导出为 PNG/SVG
|
||||
|
||||
**方法 3：使用浏览器开发者工具**
|
||||
1. 右键点击图表 → 检查元素
|
||||
2. 找到 SVG 元素
|
||||
3. 复制 SVG 代码或导出为图片
|
||||
|
||||
---
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 代码格式规范
|
||||
|
||||
**推荐：**
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[开始] --> B[处理]
|
||||
B --> C[结束]
|
||||
```
|
||||
|
||||
**不推荐：**
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[开始]-->B[处理]
|
||||
B-->C[结束]
|
||||
```
|
||||
|
||||
**建议：**
|
||||
- 使用缩进保持代码可读性
|
||||
- 箭头两侧添加空格
|
||||
- 每行一个语句
|
||||
|
||||
### 2. 节点命名
|
||||
|
||||
**推荐：**
|
||||
```mermaid
|
||||
flowchart TD
|
||||
start([开始])
|
||||
process[处理数据]
|
||||
decision{是否成功?}
|
||||
```
|
||||
|
||||
**不推荐：**
|
||||
```mermaid
|
||||
flowchart TD
|
||||
a([开始])
|
||||
b[处理数据]
|
||||
c{是否成功?}
|
||||
```
|
||||
|
||||
**建议：**
|
||||
- 使用有意义的节点 ID
|
||||
- 节点文本简洁明了
|
||||
- 避免使用特殊字符
|
||||
|
||||
### 3. 图表复杂度
|
||||
|
||||
**建议：**
|
||||
- 单个图表不超过 20 个节点
|
||||
- 复杂流程拆分为多个图表
|
||||
- 使用子图组织相关节点
|
||||
|
||||
**示例：**
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph 输入阶段
|
||||
A[接收数据] --> B[验证数据]
|
||||
end
|
||||
subgraph 处理阶段
|
||||
B --> C[处理数据]
|
||||
C --> D[保存结果]
|
||||
end
|
||||
```
|
||||
|
||||
### 4. 性能优化
|
||||
|
||||
**建议：**
|
||||
- 避免在一篇文章中使用过多图表（建议不超过 10 个）
|
||||
- 复杂图表考虑使用图片替代
|
||||
- 启用 CDN 加速加载
|
||||
|
||||
### 5. 可访问性
|
||||
|
||||
**建议：**
|
||||
- 为图表添加文字说明
|
||||
- 使用清晰的节点文本
|
||||
- 避免仅依赖颜色传达信息
|
||||
|
||||
**示例：**
|
||||
```html
|
||||
<div class="mermaid-wrapper">
|
||||
<p>以下是用户注册流程图：</p>
|
||||
<div class="mermaid">
|
||||
flowchart TD
|
||||
Start([用户访问注册页]) --> Input[填写信息]
|
||||
Input --> Validate{验证信息}
|
||||
Validate -->|通过| Register[注册成功]
|
||||
Validate -->|失败| Input
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
### 6. 版本控制
|
||||
|
||||
**建议：**
|
||||
- 在文章中记录 Mermaid 代码版本
|
||||
- 复杂图表保存源代码备份
|
||||
- 使用注释说明图表用途
|
||||
|
||||
**示例：**
|
||||
```mermaid
|
||||
%% 用户注册流程图
|
||||
%% 版本: 1.0
|
||||
%% 更新日期: 2024-01-20
|
||||
flowchart TD
|
||||
Start --> End
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 调试步骤
|
||||
|
||||
1. **启用调试模式**
|
||||
- 进入主题设置 → Mermaid 图表 → 高级选项
|
||||
- 勾选"启用调试模式"
|
||||
|
||||
2. **打开浏览器控制台**
|
||||
- 按 F12 打开开发者工具
|
||||
- 切换到"控制台"标签
|
||||
|
||||
3. **查看日志信息**
|
||||
- 查找以 `[Argon Mermaid]` 开头的日志
|
||||
- 记录错误信息和警告
|
||||
|
||||
4. **验证代码语法**
|
||||
- 访问 [Mermaid Live Editor](https://mermaid.live/)
|
||||
- 粘贴代码并检查是否有语法错误
|
||||
|
||||
5. **检查网络请求**
|
||||
- 在开发者工具中切换到"网络"标签
|
||||
- 查看 Mermaid 库是否成功加载
|
||||
- 检查是否有 404 或其他错误
|
||||
|
||||
### 常见错误代码
|
||||
|
||||
#### 错误 1: Parse error on line X
|
||||
|
||||
**原因：** Mermaid 代码语法错误
|
||||
|
||||
**解决：**
|
||||
1. 检查代码语法是否正确
|
||||
2. 使用 Mermaid Live Editor 验证
|
||||
3. 参考官方文档修正语法
|
||||
|
||||
#### 错误 2: Mermaid 库未加载
|
||||
|
||||
**原因：** CDN 加载失败或被阻止
|
||||
|
||||
**解决：**
|
||||
1. 检查网络连接
|
||||
2. 切换到其他 CDN 来源
|
||||
3. 使用本地文件
|
||||
|
||||
#### 错误 3: 主题切换失败
|
||||
|
||||
**原因：** 配置错误或 JavaScript 冲突
|
||||
|
||||
**解决：**
|
||||
1. 检查主题设置是否正确
|
||||
2. 禁用其他可能冲突的插件
|
||||
3. 清除浏览器缓存
|
||||
|
||||
### 获取帮助
|
||||
|
||||
如果以上方法都无法解决问题，请：
|
||||
|
||||
1. **收集信息：**
|
||||
- WordPress 版本
|
||||
- Argon 主题版本
|
||||
- 浏览器类型和版本
|
||||
- 错误信息和日志
|
||||
- 问题复现步骤
|
||||
|
||||
2. **提交问题：**
|
||||
- 访问 [Argon 主题 GitHub](https://github.com/solstice23/argon-theme/issues)
|
||||
- 创建新 Issue
|
||||
- 提供详细的问题描述和信息
|
||||
|
||||
3. **社区支持：**
|
||||
- 访问主题官方论坛
|
||||
- 搜索类似问题
|
||||
- 向社区求助
|
||||
|
||||
---
|
||||
|
||||
## 相关资源
|
||||
|
||||
### 官方文档
|
||||
|
||||
- [Mermaid 官方文档](https://mermaid.js.org/)
|
||||
- [Mermaid 语法参考](https://mermaid.js.org/intro/syntax-reference.html)
|
||||
- [Mermaid Live Editor](https://mermaid.live/)
|
||||
|
||||
### 教程和示例
|
||||
|
||||
- [Mermaid 快速入门](https://mermaid.js.org/intro/getting-started.html)
|
||||
- [流程图教程](https://mermaid.js.org/syntax/flowchart.html)
|
||||
- [时序图教程](https://mermaid.js.org/syntax/sequenceDiagram.html)
|
||||
- [类图教程](https://mermaid.js.org/syntax/classDiagram.html)
|
||||
|
||||
### 工具和插件
|
||||
|
||||
- [Mermaid Chart](https://www.mermaidchart.com/) - 在线图表编辑器
|
||||
- [VS Code Mermaid 插件](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid)
|
||||
- [Chrome Mermaid 扩展](https://chrome.google.com/webstore/search/mermaid)
|
||||
|
||||
---
|
||||
|
||||
## 更新日志
|
||||
|
||||
### 版本 1.0.0 (2024-01-22)
|
||||
|
||||
- ✨ 初始版本发布
|
||||
- ✅ 支持所有主要图表类型
|
||||
- ✅ 自动主题切换
|
||||
- ✅ 插件兼容性检测
|
||||
- ✅ CDN 降级机制
|
||||
- ✅ 错误提示和调试支持
|
||||
|
||||
---
|
||||
|
||||
## 反馈与建议
|
||||
|
||||
如果您在使用过程中有任何问题或建议，欢迎：
|
||||
|
||||
- 📧 发送邮件至主题作者
|
||||
- 💬 在 GitHub 上提交 Issue
|
||||
- 🌟 为项目点赞支持
|
||||
|
||||
感谢您使用 Argon 主题！
|
||||
Reference in New Issue
Block a user