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

353
.kiro/steering/mermaid-fix-2026-01-27.md
View File

@@ -1,353 +0,0 @@
# 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 主题的代码规范，并保持了向后兼容性。