nanhaoluo/argon-theme
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: 彻底移除所有 Mermaid 支持

Browse Source 
- 从 argontheme.js 移除所有 Mermaid 相关代码和注释
- 从 style.css 移除所有 Mermaid 样式（约 300 行）
- 移除代码高亮中跳过 mermaid 容器的逻辑
- 移除 PJAX 清理函数中的 Mermaid 引用
- 删除临时清理脚本和空文档
This commit is contained in:
nanhaoluo
2026-01-27 10:42:08 +08:00
parent 8a74a3b3f6
commit 0a8bb3a453
26 changed files with 542 additions and 11418 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1230
docs/mermaid-developer-guide.md
View File

File diff suppressed because it is too large Load Diff

712
docs/mermaid-faq.md
View File

@@ -1,712 +0,0 @@
# 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

505
docs/mermaid-shortcode-guide.md
View File

@@ -1,505 +0,0 @@
# 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 图表！

360
docs/mermaid-troubleshooting.md
View File

@@ -1,360 +0,0 @@
# Mermaid 图表故障排查指南
## 常见错误及解决方案
### 1. 语法错误：`Parse error on line 1`
#### 错误示例
```
Parse error on line 1: flowchart TD Sta
^
Expecting 'NEWLINE', 'SPACE', 'GRAPH', got 'ALPHA'
```
#### 原因分析
- 代码块中有多余的空格或缩进
- WordPress 或插件添加了额外的格式
- 代码提取不完整
#### 解决方案
**方案 1：检查代码格式**
确保 Mermaid 代码格式正确：
```markdown
三个反引号mermaid
flowchart TD
A[开始] --> B[结束]
三个反引号
```
**注意**：
- 第一行只有 `flowchart TD`，后面不要有其他内容
- 每行开头不要有多余的空格（除了必要的缩进）
- 使用 Tab 或 4 个空格作为缩进
**方案 2：使用容器语法**
如果代码块格式有问题，尝试使用容器语法：
```markdown
::: mermaid
flowchart TD
A[开始] --> B[结束]
:::
```
**方案 3：使用 Shortcode**
最稳定的方式是使用 Shortcode：
```
[mermaid]
flowchart TD
A[开始] --> B[结束]
[/mermaid]
```
### 2. API 错误：`window.mermaid.render(...).then is not a function`
#### 错误示例
```
window.mermaid.render(...).then is not a function
```
#### 原因分析
- Mermaid 库版本过旧（< 10.0）
- Mermaid 库未正确加载
- CDN 加载失败
#### 解决方案
**方案 1：检查 Mermaid 版本**
在浏览器控制台中运行：
```javascript
console.log(mermaid.version);
```
如果版本 < 10.0，需要更新 CDN 或使用兼容模式。
**方案 2：检查 CDN 加载**
在浏览器控制台中运行：
```javascript
console.log(typeof window.mermaid);
console.log(typeof window.mermaid.render);
```
如果输出 `undefined`，说明 Mermaid 库未加载。
**解决步骤**：
1. WordPress 后台 → 外观 → Argon 主题选项
2. 找到"Mermaid 图表"设置
3. 检查"启用 Mermaid 支持"是否开启
4. 尝试切换不同的 CDN 源
5. 清除浏览器缓存后刷新
**方案 3：使用兼容模式**
主题已内置 Mermaid 8.x 和 10.x 的兼容代码，会自动检测并使用合适的 API。
如果仍然报错，在浏览器控制台查看详细日志：
```javascript
// 启用调试模式
localStorage.setItem('argon_mermaid_debug', 'true');
location.reload();
```
### 3. 渲染错误：图表显示不完整或错位
#### 原因分析
- CSS 样式冲突
- 容器宽度限制
- 主题切换问题
#### 解决方案
**方案 1：检查容器宽度**
在浏览器开发者工具中检查 `.mermaid-container` 的宽度。
如果宽度过小，添加自定义 CSS：
```css
.mermaid-container {
max-width: 100%;
overflow-x: auto;
}
```
**方案 2：检查主题模式**
Mermaid 图表会根据主题模式（日间/夜间）自动切换颜色。
如果颜色不正确：
1. 切换主题模式（日间 ↔ 夜间）
2. 刷新页面
3. 检查主题设置中的 Mermaid 主题配置
**方案 3：强制重新渲染**
在浏览器控制台中运行：
```javascript
// 清除已渲染标记
document.querySelectorAll('.mermaid-container').forEach(el => {
el.remove();
});
// 重新渲染
if (typeof MermaidRenderer !== 'undefined') {
MermaidRenderer.renderAllCharts();
}
```
### 4. PJAX 切换后图表消失
#### 原因分析
- PJAX 切换后未重新渲染
- 代码块转换未执行
#### 解决方案
**方案 1：检查 PJAX 配置**
确保主题的 PJAX 功能已启用：
1. WordPress 后台 → 外观 → Argon 主题选项
2. 找到"PJAX"设置
3. 确认已启用
**方案 2：手动触发渲染**
在浏览器控制台中运行：
```javascript
// 监听 PJAX 完成事件
$(document).on('pjax:complete', function() {
console.log('[调试] PJAX 完成，重新渲染 Mermaid');
if (typeof MermaidRenderer !== 'undefined') {
MermaidRenderer.renderAllCharts();
}
});
```
### 5. 代码块被代码高亮处理
#### 错误表现
- Mermaid 代码块显示为普通代码
- 有行号和复制按钮
- 无法渲染为图表
#### 原因分析
- 代码块转换未执行
- 代码高亮在转换之前执行
#### 解决方案
**方案 1：检查执行顺序**
在浏览器控制台中查看日志：
```
[Mermaid] 转换了 X 个代码块 ← 应该在代码高亮之前
```
如果没有看到这条日志，说明转换函数未执行。
**方案 2：手动转换**
在浏览器控制台中运行：
```javascript
// 手动执行转换
if (typeof convertMermaidCodeblocks === 'function') {
convertMermaidCodeblocks();
console.log('[调试] 手动转换完成');
}
```
**方案 3：使用其他标记方式**
如果代码块转换不生效，使用容器语法或 Shortcode：
```markdown
::: mermaid
flowchart TD
A --> B
:::
```
或
```
[mermaid]
flowchart TD
A --> B
[/mermaid]
```
## 调试工具
### 1. 启用调试模式
在浏览器控制台中运行：
```javascript
// 启用 Mermaid 调试
localStorage.setItem('argon_mermaid_debug', 'true');
location.reload();
```
### 2. 查看转换结果
在浏览器控制台中运行：
```javascript
// 查看所有转换后的容器
document.querySelectorAll('.mermaid-from-codeblock').forEach((el, i) => {
console.log(`容器 ${i + 1}:`, el);
console.log(`代码内容:`, el.textContent);
});
```
### 3. 查看 Mermaid 配置
在浏览器控制台中运行：
```javascript
// 查看 Mermaid 配置
console.log('Mermaid 版本:', mermaid.version);
console.log('Mermaid 配置:', mermaid.getConfig());
console.log('主题配置:', window.argonMermaidConfig);
```
### 4. 测试代码语法
访问 [Mermaid Live Editor](https://mermaid.live/) 测试你的 Mermaid 代码是否正确。
### 5. 检查网络请求
在浏览器开发者工具的 Network 标签中：
1. 刷新页面
2. 搜索 `mermaid`
3. 检查 Mermaid 库是否成功加载
4. 查看 HTTP 状态码（应该是 200）
## 常见问题 FAQ
### Q: 为什么有些图表能渲染，有些不能？
A: 可能原因：
1. 代码语法错误（使用 Mermaid Live Editor 验证）
2. 代码块格式不一致（检查缩进和空格）
3. 特殊字符被转义（使用容器语法或 Shortcode）
### Q: 如何查看详细的错误信息？
A: 打开浏览器控制台（F12），查看 Console 标签页，搜索 `[Mermaid]` 或 `[Argon Mermaid]`。
### Q: 代码块魔改功能如何工作？
A:
1. 页面加载时，`convertMermaidCodeblocks()` 函数在代码高亮之前执行
2. 查找所有 `<pre><code class="language-mermaid">` 元素
3. 提取纯文本代码并清理缩进
4. 创建 `<div class="mermaid-from-codeblock">` 容器
5. 替换原始代码块元素
6. Mermaid 渲染引擎检测并渲染容器
### Q: 如何禁用代码块魔改功能？
A: 如果代码块魔改导致问题，可以使用容器语法或 Shortcode 代替。
### Q: 支持哪些 Mermaid 图表类型？
A: 支持所有 Mermaid 官方图表类型：
- flowchart / graph（流程图）
- sequenceDiagram（时序图）
- classDiagram（类图）
- stateDiagram（状态图）
- erDiagram（实体关系图）
- gantt（甘特图）
- pie（饼图）
- journey（用户旅程图）
- gitGraph（Git 图）
## 获取帮助
如果以上方法都无法解决问题：
1. **收集信息**：
- 浏览器类型和版本
- WordPress 版本
- Argon 主题版本
- 使用的插件列表
- 完整的错误信息（控制台截图）
- Mermaid 代码示例
2. **检查文档**：
- [用户指南](mermaid-usage-guide.md)
- [开发者指南](mermaid-developer-guide.md)
- [FAQ](mermaid-faq.md)
3. **联系支持**：
- GitHub Issues
- 主题论坛
- 技术支持邮箱
## 更新日志
### 2026-01-24
- ✅ 添加智能缩进清理功能
- ✅ 添加 Mermaid API 版本检测
- ✅ 支持 Mermaid 8.x 和 10.x
- ✅ 增强错误处理和调试日志
- ✅ 修复代码提取时的空格问题

439
docs/mermaid-usage-guide.md
View File

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

719
docs/mermaid-user-guide.md
View File

@@ -1,719 +0,0 @@
# 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 主题！