# Mermaid 渲染问题修复

## 修复时间
2026-01-27

## 问题描述

用户报告了以下 Mermaid 相关问题：

1. **代码块转换功能被禁用**：`convertMermaidCodeblocks()` 函数第一行有 `return;`，导致 ```mermaid 代码块无法转换
2. **检测选择器不完整**：`detectMermaidBlocks()` 只检测 `div.mermaid-shortcode`，缺少其他格式的检测
3. **首页预览显示原始代码**：点击首页文章预览时，显示无格式化的纯文字 Mermaid 代码

## 根本原因

### 1. 代码块转换被禁用
在 `argontheme.js` 第 4345 行，`convertMermaidCodeblocks()` 函数开头有一个 `return;` 语句，导致整个函数被跳过：

```javascript
function convertMermaidCodeblocks(){
	return;  // ← 这行导致函数直接返回
	// ... 后面的代码都不会执行
}
```

### 2. 检测选择器不完整
在 `MermaidRenderer.detectMermaidBlocks()` 中，选择器数组只包含一个元素：

```javascript
const selectors = [
	'div.mermaid-shortcode'  // 只检测 shortcode 格式
];
```

缺少对以下格式的检测：
- `div.mermaid-from-codeblock` - 代码块魔改格式
- `div.mermaid` - 标准格式
- `pre code.language-mermaid` - Markdown 格式
- `pre[data-lang="mermaid"]` - 自定义属性格式
- `code.mermaid` - 简化格式

### 3. 首页预览问题
在三个文章预览模板中，使用 `wp_trim_words()` 直接处理包含 `[mermaid]...[/mermaid]` shortcode 的内容：

```php
$preview = wp_trim_words(get_the_content('...'), $trim_words_count);
```

`wp_trim_words()` 会破坏 shortcode 结构，导致显示原始的 Mermaid 代码文本。

## 修复方案

### 1. 启用代码块转换功能

**文件**：`argontheme.js`

**修改**：移除 `convertMermaidCodeblocks()` 函数开头的 `return;` 语句

```javascript
// 修改前
function convertMermaidCodeblocks(){
	return;
	// ...
}

// 修改后
function convertMermaidCodeblocks(){
	// 支持多种代码块格式
	// ...
}
```

**效果**：
- ✅ ```mermaid 代码块可以正常转换为 `<div class="mermaid-from-codeblock">`
- ✅ 避免代码高亮干扰 Mermaid 渲染
- ✅ 支持标准 Markdown 格式

### 2. 添加完整的检测选择器

**文件**：`argontheme.js`

**修改**：在 `detectMermaidBlocks()` 中添加完整的选择器列表

```javascript
// 修改前
const selectors = [
	'div.mermaid-shortcode'
];

// 修改后
const selectors = [
	'div.mermaid-shortcode',                 // Shortcode 格式（推荐）
	'div.mermaid-from-codeblock',            // 代码块魔改格式
	'div.mermaid',                           // 标准格式
	'pre code.language-mermaid',             // Markdown 格式（降级）
	'pre[data-lang="mermaid"]',              // 自定义属性格式
	'code.mermaid'                           // 简化格式
];
```

**效果**：
- ✅ 支持多种 Mermaid 代码块格式
- ✅ 兼容不同的编辑器和插件
- ✅ 提供降级支持

### 3. 修复首页预览问题

**文件**：
- `functions.php`
- `template-parts/content-preview-1.php`
- `template-parts/content-preview-2.php`
- `template-parts/content-preview-3.php`

**修改 1**：在 `functions.php` 中添加辅助函数

```php
/**
 * 从内容中移除 Mermaid shortcode，用于文章预览
 * 避免在预览中显示原始 Mermaid 代码
 * 
 * @param string $content 文章内容
 * @return string 移除 Mermaid shortcode 后的内容
 */
function argon_remove_mermaid_from_preview($content) {
	// 移除 [mermaid]...[/mermaid] shortcode
	$content = preg_replace('/\[mermaid[^\]]*\].*?\[\/mermaid\]/is', '[Mermaid 图表]', $content);
	return $content;
}
```

**修改 2**：在三个预览模板中使用辅助函数

```php
// 修改前
if (get_option("argon_hide_shortcode_in_preview") == 'true'){
	$preview = wp_trim_words(do_shortcode(get_the_content('...')), $trim_words_count);
}else{
	$preview = wp_trim_words(get_the_content('...'), $trim_words_count);
}

// 修改后
$content_for_preview = get_the_content('...');
// 移除 Mermaid shortcode，避免在预览中显示原始代码
$content_for_preview = argon_remove_mermaid_from_preview($content_for_preview);

if (get_option("argon_hide_shortcode_in_preview") == 'true'){
	$preview = wp_trim_words(do_shortcode($content_for_preview), $trim_words_count);
}else{
	$preview = wp_trim_words($content_for_preview, $trim_words_count);
}
```

**效果**：
- ✅ 首页预览中不再显示原始 Mermaid 代码
- ✅ 用 `[Mermaid 图表]` 占位符替代
- ✅ 保持预览内容的可读性

## 技术细节

### 代码块转换流程

```
页面加载/PJAX切换
    ↓
highlightJsRender() 调用
    ↓
convertMermaidCodeblocks() 执行 ← 【拦截阶段】
    ↓
    查找 <pre><code class="language-mermaid">
    ↓
    提取纯文本代码
    ↓
    创建 <div class="mermaid-from-codeblock">
    ↓
    替换原始代码块
    ↓
代码高亮处理其他代码块
    ↓
MermaidRenderer.detectMermaidBlocks() ← 【检测阶段】
    ↓
MermaidRenderer.renderChart() ← 【渲染阶段】
```

### 支持的 Mermaid 格式

#### 1. Shortcode 格式（推荐）

```
[mermaid]
flowchart TD
    A --> B
[/mermaid]
```

**优势**：
- 最稳定的方式
- 不受代码高亮影响
- 支持参数配置

#### 2. Markdown 代码块格式

````markdown
```mermaid
flowchart TD
    A --> B
```
````

**优势**：
- 标准 Markdown 语法
- 编辑器支持好
- 可以拉起代码高亮

**注意**：需要代码块转换功能支持

#### 3. HTML 容器格式

```html
<div class="mermaid">
flowchart TD
    A --> B
</div>
```

**优势**：
- 直接渲染
- 兼容性好

## 测试验证

### 测试场景 1：Shortcode 格式

**测试步骤**：
1. 创建新文章
2. 使用 `[mermaid]...[/mermaid]` 格式插入图表
3. 发布文章
4. 查看文章页面
5. 查看首页预览

**预期结果**：
- ✅ 文章页面正确渲染 Mermaid 图表
- ✅ 首页预览显示 `[Mermaid 图表]` 占位符

### 测试场景 2：Markdown 代码块格式

**测试步骤**：
1. 创建新文章
2. 使用 ` ```mermaid ` 格式插入图表
3. 发布文章
4. 查看文章页面

**预期结果**：
- ✅ 代码块被转换为 `<div class="mermaid-from-codeblock">`
- ✅ 图表正确渲染
- ✅ 不显示代码高亮的行号和复制按钮

### 测试场景 3：PJAX 切换

**测试步骤**：
1. 在首页点击文章链接（PJAX 加载）
2. 查看 Mermaid 图表是否渲染
3. 返回首页（PJAX 加载）
4. 再次点击文章

**预期结果**：
- ✅ PJAX 切换后图表正常渲染
- ✅ 不会重复渲染
- ✅ 主题切换正常工作

## 相关文件

### 修改的文件
- `argontheme.js` - 启用代码块转换，添加完整选择器
- `functions.php` - 添加 `argon_remove_mermaid_from_preview()` 函数
- `template-parts/content-preview-1.php` - 修复预览显示
- `template-parts/content-preview-2.php` - 修复预览显示
- `template-parts/content-preview-3.php` - 修复预览显示

### 相关文档
- `docs/mermaid-user-guide.md` - 用户使用指南
- `docs/mermaid-developer-guide.md` - 开发者文档
- `docs/mermaid-troubleshooting.md` - 故障排查指南

## Git 提交

```bash
git commit -m "fix: 修复 Mermaid 渲染问题

- 启用代码块转换功能（移除 convertMermaidCodeblocks 中的 return 语句）
- 添加完整的 Mermaid 代码块检测选择器
- 修复首页预览中显示原始 Mermaid 代码的问题
- 添加 argon_remove_mermaid_from_preview 函数过滤预览内容
- 更新三个文章预览模板，在预览中用 [Mermaid 图表] 替代原始代码"
```

**提交哈希**：135c226

## 后续建议

### 1. 功能增强

- [ ] 添加预览中的 Mermaid 图表缩略图
- [ ] 支持更多 Mermaid 图表类型
- [ ] 添加图表导出功能

### 2. 性能优化

- [ ] 延迟加载 Mermaid 库
- [ ] 缓存渲染结果
- [ ] 优化大型图表的渲染

### 3. 用户体验

- [ ] 添加图表编辑器
- [ ] 提供图表模板
- [ ] 改进错误提示

## 常见问题

### Q1: 为什么代码块转换被禁用了？

A: 可能是在之前的某次修复中，为了临时解决某个问题而添加了 `return;` 语句，但忘记移除。

### Q2: 如何确保 PJAX 兼容性？

A: 代码块转换在 `highlightJsRender()` 中调用，该函数已在 PJAX 回调中注册，因此自动支持 PJAX。

### Q3: 为什么不在预览中渲染 Mermaid 图表？

A: 因为：
1. 预览内容会被 `wp_trim_words()` 截断，可能破坏图表代码
2. 在列表页渲染大量图表会影响性能
3. 使用占位符更简洁明了

### Q4: 如何添加新的 Mermaid 格式支持？

A: 在 `detectMermaidBlocks()` 的 `selectors` 数组中添加新的选择器，并在 `extractMermaidCode()` 中添加对应的提取逻辑。

## 总结

本次修复解决了 Mermaid 渲染的三个主要问题：

1. ✅ **启用代码块转换**：移除了阻止转换的 `return;` 语句
2. ✅ **完善检测机制**：添加了完整的选择器列表，支持多种格式
3. ✅ **修复预览显示**：在预览中用占位符替代原始代码

用户现在可以：
- 使用 `[mermaid]...[/mermaid]` shortcode 格式（推荐）
- 使用 ` ```mermaid ` Markdown 代码块格式
- 在首页预览中看到友好的占位符而不是原始代码
- 享受完整的 Mermaid 图表渲染功能

所有修改都遵循了 Argon 主题的代码规范，并保持了向后兼容性。