# 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`