nanhaoluo
29bfd284e0
- 添加 convertMermaidCodeblocks() 函数，在代码高亮前拦截 mermaid 代码块 - 支持标准 Markdown 代码块 (\\\mermaid) 渲染 - 更新 detectMermaidBlocks() 添加 mermaid-from-codeblock 选择器 - 更新 extractMermaidCode() 支持新容器类型 - 创建测试文件 test-codeblock-magic.html - 更新用户文档、开发者文档和 FAQ - 完全绕过代码高亮和 WordPress 格式化 - 支持 PJAX 页面切换 - 特殊字符和换行符正确保留
6.9 KiB
6.9 KiB
Mermaid 代码块魔改支持 - 任务列表
概述
实现标准 Markdown 代码块 (```mermaid) 的 Mermaid 图表渲染，通过在代码高亮之前拦截并转换代码块，完全绕过 WordPress 和代码高亮的干扰。
任务列表
1. 核心功能实现
-
1.1 实现
convertMermaidCodeblocks()函数- 需求: 3.1 代码块拦截（核心功能）
- 位置:
argontheme.js第 3942 行之前（highlightJsRender()函数开始处） - 功能:
- 使用多个选择器查找 mermaid 代码块
- 支持
pre > code.language-mermaid、pre > code.mermaid、code.language-mermaid、pre[data-lang="mermaid"]格式 - 提取纯文本代码（使用
textContent） - 创建
<div class="mermaid-from-codeblock">容器 - 替换原始代码块元素
- 添加
data-processed="true"标记防止重复处理
- 参考: 设计文档 3.1 节
-
1.2 集成到
highlightJsRender()函数- 需求: 3.1 代码块拦截（核心功能）
- 位置:
argontheme.js第 3942 行 - 修改: 在函数开始处调用
convertMermaidCodeblocks() - 执行顺序: 转换 → 代码高亮 → Mermaid 渲染
- 参考: 设计文档 3.2 节（集成点 1）
2. Mermaid 检测适配
-
2.1 更新
detectMermaidBlocks()函数- 需求: 3.4 渲染检测
- 位置:
argontheme.js第 4430 行 - 修改: 在 selectors 数组中添加
'div.mermaid-from-codeblock' - 优先级: 放在
'div.mermaid-shortcode'之后，'div.mermaid'之前 - 参考: 设计文档 3.2 节（集成点 2）
-
2.2 更新
extractMermaidCode()函数- 需求: 3.5 代码提取适配
- 位置:
argontheme.js第 4650 行 - 修改: 添加对
mermaid-from-codeblock类的处理分支 - 提取方式: 使用
element.textContent直接获取 - 参考: 设计文档 3.2 节（集成点 3）
3. 测试与验证
-
3.1 创建测试文件
- 需求: 6.4 测试用例
- 文件:
tests/test-codeblock-magic.html - 内容:
- 标准 Markdown 代码块 (
pre > code.language-mermaid) - 多个代码块（测试批量处理）
- 特殊字符代码块（
-->,--,==等） - 空代码块（测试边界情况）
- 多行代码块（测试换行符保留）
- 标准 Markdown 代码块 (
- 参考: 设计文档 7.4 节
-
3.2 功能测试
- 需求: 6.1 单元测试、6.2 集成测试
- 测试项:
- 代码块正确转换为容器
- 代码块不被代码高亮处理
- Mermaid 图表正确渲染
- 特殊字符不被转换（
-->保持不变） - 换行符正确保留
- 重复处理防护生效
- 参考: 设计文档 7.1 节、7.2 节
-
3.3 PJAX 兼容性测试
- 需求: 3.6 PJAX 兼容
- 测试项:
- 初始页面加载，代码块正确转换和渲染
- PJAX 切换到新页面，新页面的代码块正确转换和渲染
- 已转换的代码块不被重复处理
- 无 JavaScript 错误
- 参考: 设计文档 3.3 节
-
3.4 浏览器兼容性测试
- 需求: 6.3 浏览器测试
- 测试浏览器: Chrome、Firefox、Safari、Edge（最新版）
- 测试项: 代码块转换、图表渲染、PJAX 切换、性能表现
- 参考: 设计文档 7.3 节
4. 文档更新
-
4.1 更新用户文档
- 需求: 7.1 用户文档
- 文件:
docs/mermaid-usage-guide.md - 内容:
- 添加代码块魔改方式的说明
- 提供使用示例（标准 Markdown 语法）
- 说明优缺点（优点：标准语法；缺点：需要主题支持）
- 与其他方式的对比
- 参考: 需求文档 7.1 节
-
4.2 更新开发者文档
- 需求: 7.2 开发者文档
- 文件:
docs/mermaid-developer-guide.md - 内容:
- 说明实现原理（提前拦截、转换容器）
- 提供代码示例（
convertMermaidCodeblocks()函数） - 说明扩展方式（如何添加新的选择器）
- 执行顺序说明
- 参考: 需求文档 7.2 节
-
4.3 更新 FAQ 文档
- 需求: 7.3 FAQ 文档
- 文件:
docs/mermaid-faq.md - 内容:
- 添加常见问题（如何使用标准 Markdown 语法？）
- 提供解决方案（启用代码块魔改功能）
- 说明注意事项（需要主题版本 >= X.X.X）
- 故障排查指南
- 参考: 需求文档 7.3 节
5. 性能优化（可选）
-
5.1* 添加性能监控
- 需求: 4.1 性能要求
- 功能:
- 使用
performance.now()记录转换耗时 - 使用
console.log()输出性能数据（仅调试模式） - 记录处理的代码块数量
- 使用
- 目标: 单个代码块处理时间 < 10ms
- 参考: 设计文档 5.3 节
-
5.2* 优化选择器性能
- 需求: 4.1 性能要求
- 优化:
- 使用更精确的选择器（减少匹配范围）
- 批量处理元素（减少 DOM 查询次数）
- 提前返回（跳过已处理的元素）
- 参考: 设计文档 5.2 节
6. 错误处理增强（可选）
-
6.1* 添加错误日志
- 需求: 5.3 错误处理
- 功能:
- 使用 try-catch 包裹关键代码
- 捕获异常后记录日志（
console.error()） - 不中断其他代码块的处理
- 参考: 设计文档 3.4 节
-
6.2* 提供降级方案
- 需求: 5.3 错误处理
- 功能:
- 如果转换失败，保留原始代码块
- 原始代码块仍可通过降级选择器检测（
pre code.language-mermaid） - 确保即使转换失败，仍能渲染
- 参考: 设计文档 3.4 节
任务说明
优先级
- 必须完成: 1.1 - 2.2（核心功能）、3.1 - 3.3（测试验证）、4.1 - 4.3（文档更新）
- 可选任务: 5.1 - 5.2（性能优化）、6.1 - 6.2（错误处理增强）
执行顺序
- 先完成核心功能（1.1 - 1.2）
- 再完成 Mermaid 检测适配（2.1 - 2.2）
- 然后进行测试验证（3.1 - 3.4）
- 最后更新文档（4.1 - 4.3）
- 可选任务可在主要功能完成后进行
验收标准
- ✅ 可以使用
```mermaid代码块编写图表 - ✅ 代码块不会被代码高亮处理
- ✅ 图表正确渲染
- ✅ 特殊字符不被转换
- ✅ 换行符正确保留
- ✅ PJAX 切换正常工作
- ✅ 性能无明显影响
- ✅ 兼容所有主流浏览器
注意事项
- 执行顺序约束: 必须严格遵守"转换 → 代码高亮 → Mermaid 渲染"的执行顺序
- 代码风格: 使用 Tab 缩进、单引号、严格相等（
===） - 安全性: 使用
textContent而非innerHTML，防止 XSS - 兼容性: 保持与现有功能的兼容，不影响 Shortcode 和容器语法
- 调试: 添加详细的调试日志，便于追踪问题
参考文档
- 需求文档:
.kiro/specs/mermaid-codeblock-magic/requirements.md - 设计文档:
.kiro/specs/mermaid-codeblock-magic/design.md - 代码规范:
.kiro/steering/code-style.md