From 8a74a3b3f69a2ab7407d4bf44b8bdd299f3f5fae Mon Sep 17 00:00:00 2001 From: nanhaoluo <3075912108@qq.com> Date: Tue, 27 Jan 2026 00:30:13 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20Mermaid=20?= =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .kiro/steering/mermaid-fix-2026-01-27.md | 353 +++++++++++++++++++++++ 1 file changed, 353 insertions(+) create mode 100644 .kiro/steering/mermaid-fix-2026-01-27.md diff --git a/.kiro/steering/mermaid-fix-2026-01-27.md b/.kiro/steering/mermaid-fix-2026-01-27.md new file mode 100644 index 0000000..06c193d --- /dev/null +++ b/.kiro/steering/mermaid-fix-2026-01-27.md @@ -0,0 +1,353 @@ +# 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 代码块可以正常转换为 `
` +- ✅ 避免代码高亮干扰 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() 执行 ← 【拦截阶段】 + ↓ + 查找 

+    ↓
+    提取纯文本代码
+    ↓
+    创建 

+    ↓
+    替换原始代码块
+    ↓
+代码高亮处理其他代码块
+    ↓
+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
+

+flowchart TD
+    A --> B
+

+```
+
+**优势**：
+- 直接渲染
+- 兼容性好
+
+## 测试验证
+
+### 测试场景 1：Shortcode 格式
+
+**测试步骤**：
+1. 创建新文章
+2. 使用 `[mermaid]...[/mermaid]` 格式插入图表
+3. 发布文章
+4. 查看文章页面
+5. 查看首页预览
+
+**预期结果**：
+- ✅ 文章页面正确渲染 Mermaid 图表
+- ✅ 首页预览显示 `[Mermaid 图表]` 占位符
+
+### 测试场景 2：Markdown 代码块格式
+
+**测试步骤**：
+1. 创建新文章
+2. 使用 ` ```mermaid ` 格式插入图表
+3. 发布文章
+4. 查看文章页面
+
+**预期结果**：
+- ✅ 代码块被转换为 `
`
+- ✅ 图表正确渲染
+- ✅ 不显示代码高亮的行号和复制按钮
+
+### 测试场景 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 主题的代码规范，并保持了向后兼容性。