nanhaoluo
29bfd284e0
- 添加 convertMermaidCodeblocks() 函数，在代码高亮前拦截 mermaid 代码块 - 支持标准 Markdown 代码块 (\\\mermaid) 渲染 - 更新 detectMermaidBlocks() 添加 mermaid-from-codeblock 选择器 - 更新 extractMermaidCode() 支持新容器类型 - 创建测试文件 test-codeblock-magic.html - 更新用户文档、开发者文档和 FAQ - 完全绕过代码高亮和 WordPress 格式化 - 支持 PJAX 页面切换 - 特殊字符和换行符正确保留
189 lines
6.9 KiB
Markdown
189 lines
6.9 KiB
Markdown
# 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`)
|
||
- 多个代码块（测试批量处理）
|
||
- 特殊字符代码块（`-->`, `--`, `==` 等）
|
||
- 空代码块（测试边界情况）
|
||
- 多行代码块（测试换行符保留）
|
||
- **参考**: 设计文档 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 - 1.2）
|
||
2. 再完成 Mermaid 检测适配（2.1 - 2.2）
|
||
3. 然后进行测试验证（3.1 - 3.4）
|
||
4. 最后更新文档（4.1 - 4.3）
|
||
5. 可选任务可在主要功能完成后进行
|
||
|
||
### 验收标准
|
||
- ✅ 可以使用 ` ```mermaid ` 代码块编写图表
|
||
- ✅ 代码块不会被代码高亮处理
|
||
- ✅ 图表正确渲染
|
||
- ✅ 特殊字符不被转换
|
||
- ✅ 换行符正确保留
|
||
- ✅ PJAX 切换正常工作
|
||
- ✅ 性能无明显影响
|
||
- ✅ 兼容所有主流浏览器
|
||
|
||
## 注意事项
|
||
|
||
1. **执行顺序约束**: 必须严格遵守"转换 → 代码高亮 → Mermaid 渲染"的执行顺序
|
||
2. **代码风格**: 使用 Tab 缩进、单引号、严格相等（`===`）
|
||
3. **安全性**: 使用 `textContent` 而非 `innerHTML`，防止 XSS
|
||
4. **兼容性**: 保持与现有功能的兼容，不影响 Shortcode 和容器语法
|
||
5. **调试**: 添加详细的调试日志，便于追踪问题
|
||
|
||
## 参考文档
|
||
|
||
- **需求文档**: `.kiro/specs/mermaid-codeblock-magic/requirements.md`
|
||
- **设计文档**: `.kiro/specs/mermaid-codeblock-magic/design.md`
|
||
- **代码规范**: `.kiro/steering/code-style.md`
|