nanhaoluo
54cbb400b9
- 从 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 解析器持续报错。所有尝试的解决方案均失败。 需求文档中详细说明了问题原因和推荐的替代方案。
276 lines
7.6 KiB
Markdown
276 lines
7.6 KiB
Markdown
# 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% 兼容所有语法。
|