feat: 移除 Mermaid 支持并创建需求文档

- 从 settings.php 移除 Mermaid 设置项和选项保存逻辑 - 从 functions.php 移除 Mermaid 代码块预处理函数 - 从 footer.php 移除 Mermaid 加载和渲染代码 - 从 style.css 移除 Mermaid 图表样式 - 删除本地镜像文件 assets/vendor/external/mermaid/ - 创建 mermaid-support-requirements.md 需求文档原因：WP-Markdown 编辑器保存的 Markdown 源文件中 Mermaid 代码是一整行，没有真正的换行符，导致 Mermaid 解析器持续报错。所有尝试的解决方案均失败。需求文档中详细说明了问题原因和推荐的替代方案。
2026-01-23 22:11:09 +08:00
parent 5704531a4d
commit 54cbb400b9
7 changed files with 275 additions and 2465 deletions
--- a/mermaid-support-requirements.md
+++ b/mermaid-support-requirements.md
@@ -0,0 +1,275 @@
+# Argon 主题 Mermaid 图表支持需求文档
+
+## 需求背景
+
+用户希望在 Argon WordPress 主题中添加 Mermaid 图表支持，以便在文章中使用流程图、时序图等可视化图表。
+
+## 技术环境
+
+- **WordPress 主题**: Argon
+- **Markdown 编辑器**: WP-Markdown (wdmd) - 注意：这是编辑器，不是插件
+- **Mermaid 版本**: 10.x 或更高
+
+## 核心问题
+
+### 1. WP-Markdown 渲染格式特殊
+
+WP-Markdown 编辑器渲染 Mermaid 代码块时，生成的 HTML 格式为：
+
+```html
+<div class="mermaid">
+    <script>document.write("flowchart TD\n Start --> End")</script>
+    flowchart TD Start --> End
+</div>
+```
+
+特点：
+- 使用 `<div class="mermaid">` 包裹
+- 内部包含 `<script>` 标签，使用 `document.write()` 输出转义后的代码
+- 转义字符包括：`\n`（换行）、`\"`（引号）、`\'`（单引号）
+- script 标签后还有原始文本（未转义）
+
+### 2. Markdown 源文件格式问题
+
+**关键问题**：用户在 WP-Markdown 编辑器中编辑时，虽然界面显示有换行（编辑器自动换行），但保存到 Markdown 源文件时，**整个 Mermaid 代码块是一整行，没有真正的换行符**。
+
+示例：
+```markdown
+```mermaid
+flowchart TD Start([用户提交评论]) --> PreProcess[preprocess_comment 钩子] PreProcess --> CheckEnabled{启用 AI 检测?} CheckEnabled -->|否| SaveComment[保存评论]
+```
+```
+
+这导致：
+- Mermaid 解析器要求代码有正确的换行格式
+- 持续报错：`Parse error on line 1: Expecting 'NEWLINE', 'SPACE', 'GRAPH'`
+- 所有尝试在 JavaScript 或 PHP 端添加换行的方案都失败
+
+### 3. 已尝试的解决方案（均失败）
+
+#### 方案 1: JavaScript 端解码
+- 从 script 标签提取代码
+- 解码 `\n` 为真正的换行符
+- **失败原因**：Markdown 源文件中就没有 `\n`，只是一整行
+
+#### 方案 2: 使用 mermaid.render()
+- 替代 `mermaid.init()` 方法
+- 手动渲染并插入 SVG
+- **失败原因**：解析器仍然要求正确的换行格式
+
+#### 方案 3: PHP 端预处理
+- 在 `functions.php` 中添加 `argon_format_mermaid_code()` 函数
+- 使用正则表达式在箭头、关键字前添加换行
+- **失败原因**：无法准确判断应该在哪里添加换行
+
+#### 方案 4: 智能检测单行代码
+- 检测前 100 个字符中的换行符数量
+- 如果少于 2 个，自动格式化
+- **失败原因**：格式化规则不完善，仍然解析失败
+
+## 需求分析
+
+### 必要条件
+
+要成功支持 Mermaid，需要满足以下条件之一：
+
+1. **修改 WP-Markdown 编辑器**
+   - 保存时保留真正的换行符
+   - 或者在保存前格式化 Mermaid 代码块
+   - **难度**：需要修改编辑器源码，可能影响其他功能
+
+2. **使用支持 Mermaid 的 WordPress 插件**
+   - 例如：WP Githuber MD、Markdown Block 等
+   - 这些插件原生支持 Mermaid
+   - **难度**：需要更换编辑器，用户可能不愿意
+
+3. **开发完整的 Mermaid 代码格式化器**
+   - 能够智能识别 Mermaid 语法
+   - 自动添加正确的换行符
+   - **难度**：需要深入理解 Mermaid 语法规则，工作量大
+
+### 功能需求
+
+如果要实现 Mermaid 支持，应包含以下功能：
+
+#### 1. 基础功能
+- [ ] 支持 Mermaid 所有图表类型（流程图、时序图、类图等）
+- [ ] 响应式设计，图表自适应容器宽度
+- [ ] 支持夜间模式，自动切换图表主题
+- [ ] 支持本地镜像和 CDN 两种加载方式
+
+#### 2. 设置选项
+- [ ] 启用/禁用 Mermaid 支持
+- [ ] 选择 CDN 地址（jsDelivr、unpkg、自定义）
+- [ ] 选择图表主题（default、dark、forest、neutral 等）
+- [ ] 是否使用本地镜像
+
+#### 3. 样式优化
+- [ ] 图表容器样式（背景、圆角、阴影）
+- [ ] 夜间模式适配
+- [ ] 移动端响应式
+- [ ] 横向滚动支持（超宽图表）
+
+#### 4. 错误处理
+- [ ] 解析失败时显示友好的错误信息
+- [ ] 在控制台输出详细的调试信息
+- [ ] 提供代码预览功能
+
+## 推荐方案
+
+### 方案 A: 使用支持 Mermaid 的插件（推荐）
+
+**优点**：
+- 开箱即用，无需开发
+- 插件维护者会持续更新
+- 兼容性好，经过大量用户测试
+
+**推荐插件**：
+1. **WP Githuber MD** - 功能强大的 Markdown 编辑器
+2. **Markdown Block** - Gutenberg 原生 Markdown 块
+3. **Code Syntax Block** - 支持 Mermaid 的代码块插件
+
+**实施步骤**：
+1. 安装并激活插件
+2. 在插件设置中启用 Mermaid 支持
+3. 测试各种图表类型
+4. 根据需要调整样式
+
+### 方案 B: 要求用户手动格式化代码
+
+**优点**：
+- 无需修改主题代码
+- 用户完全控制代码格式
+
+**缺点**：
+- 用户体验差
+- 容易出错
+
+**实施步骤**：
+1. 在主题文档中说明 Mermaid 代码必须有正确的换行
+2. 提供代码格式化工具或在线编辑器链接
+3. 用户在外部工具中编辑好后，复制到 WordPress
+
+### 方案 C: 开发完整的格式化器（不推荐）
+
+**优点**：
+- 用户体验好，自动处理
+
+**缺点**：
+- 开发工作量大
+- 需要维护 Mermaid 语法规则
+- 可能出现边缘情况无法处理
+
+**实施步骤**：
+1. 研究 Mermaid 完整语法规则
+2. 开发智能格式化算法
+3. 处理各种边缘情况
+4. 大量测试
+
+## 技术实现参考
+
+### 标准 Mermaid 集成方式
+
+```html
+<!-- 加载 Mermaid 库 -->
+<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
+
+<!-- 初始化 -->
+<script>
+mermaid.initialize({
+    startOnLoad: true,
+    theme: 'default',
+    securityLevel: 'loose'
+});
+</script>
+
+<!-- 使用 -->
+<div class="mermaid">
+flowchart TD
+    Start --> End
+</div>
+```
+
+### WordPress 插件集成方式
+
+```php
+// 注册 Mermaid 脚本
+function my_theme_enqueue_mermaid() {
+    if (is_single() || is_page()) {
+        wp_enqueue_script(
+            'mermaid',
+            'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js',
+            [],
+            '10.0.0',
+            true
+        );
+    }
+}
+add_action('wp_enqueue_scripts', 'my_theme_enqueue_mermaid');
+
+// 初始化脚本
+function my_theme_mermaid_init() {
+    ?>
+    <script>
+    document.addEventListener('DOMContentLoaded', function() {
+        mermaid.initialize({
+            startOnLoad: true,
+            theme: '<?php echo get_option('mermaid_theme', 'default'); ?>'
+        });
+    });
+    </script>
+    <?php
+}
+add_action('wp_footer', 'my_theme_mermaid_init');
+```
+
+## 测试用例
+
+### 测试 1: 基础流程图
+```mermaid
+flowchart TD
+    Start([开始]) --> Process[处理]
+    Process --> Decision{判断}
+    Decision -->|是| End1([结束1])
+    Decision -->|否| End2([结束2])
+```
+
+### 测试 2: 时序图
+```mermaid
+sequenceDiagram
+    participant A as 用户
+    participant B as 服务器
+    A->>B: 发送请求
+    B->>A: 返回响应
+```
+
+### 测试 3: 类图
+```mermaid
+classDiagram
+    class Animal {
+        +String name
+        +int age
+        +makeSound()
+    }
+    class Dog {
+        +bark()
+    }
+    Animal <|-- Dog
+```
+
+## 相关资源
+
+- [Mermaid 官方文档](https://mermaid.js.org/)
+- [Mermaid Live Editor](https://mermaid.live/) - 在线编辑器
+- [WP Githuber MD 插件](https://wordpress.org/plugins/wp-githuber-md/)
+- [Markdown Block 插件](https://wordpress.org/plugins/markdown-block/)
+
+## 结论
+
+由于 WP-Markdown 编辑器的特殊渲染方式和 Markdown 源文件格式问题，在 Argon 主题中直接支持 Mermaid 存在技术障碍。
+
+**建议**：
+1. **短期方案**：使用支持 Mermaid 的 WordPress 插件（如 WP Githuber MD）
+2. **长期方案**：等待 WP-Markdown 编辑器更新，或考虑更换为更现代的 Markdown 编辑器
+
+如果必须在当前环境下实现，需要投入大量时间开发完整的 Mermaid 代码格式化器，且无法保证 100% 兼容所有语法。