argon-theme/docs/mermaid-troubleshooting.md

# 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
- ✅ 增强错误处理和调试日志
- ✅ 修复代码提取时的空格问题