chore: 清理非必要的测试文件和文档
This commit is contained in:
@@ -1,213 +0,0 @@
|
||||
# Mermaid 容器语法修复总结
|
||||
|
||||
## 修复的问题
|
||||
|
||||
### 问题 1: 代码高亮干扰 Mermaid 渲染
|
||||
- **症状**: 使用 ` ```mermaid ` 标记时，代码高亮会处理 mermaid 代码块，导致渲染冲突
|
||||
- **修复**: 在 `highlightJsRender()` 函数中添加检查，跳过 `language-mermaid` 和 `mermaid` 类的代码块
|
||||
- **Commit**: 0ac5794
|
||||
|
||||
### 问题 2: 容器语法空行导致内容截断
|
||||
- **症状**: 容器语法 `::: mermaid ... :::` 中的空行导致内容被截断
|
||||
- **修复**: 修改 `extractContainerContent()` 函数，不使用 `trim()` 删除空行
|
||||
- **Commit**: 0ac5794
|
||||
|
||||
### 问题 3: WP-Markdown document.write 重复输出
|
||||
- **症状**: WP-Markdown 生成 `<div class="mermaid"><script>document.write("...")</script>flowchart TD ...</div>`，script 后面有重复代码
|
||||
- **修复**: 在 `extractMermaidCode()` 中提取完 script 内容后立即 `scriptTag.remove()`
|
||||
- **Commit**: b6d9f8c
|
||||
|
||||
### 问题 4: 容器语法跨元素收集失败
|
||||
- **症状**: 容器语法遇到空行时，WP-Markdown 将内容分割成多个元素，只提取到第一个元素
|
||||
- **修复**: 重写 `detectContainerBlocks()` 和 `extractContainerContent()`，支持跨多个兄弟元素收集内容
|
||||
- **Commit**: b6d9f8c
|
||||
|
||||
### 问题 5: 换行符丢失 ⭐（核心问题）
|
||||
- **症状**:
|
||||
- 流程图渲染失败，错误显示 `flowchart TDStart`（`TD` 和 `Start` 之间缺少换行）
|
||||
- 箭头符号被转换成全角 `–>` 而不是 `-->`
|
||||
- **根本原因**:
|
||||
- WP-Markdown 将每一行代码包裹在 `<p>` 标签中
|
||||
- 行内换行使用 `<br>` 标签表示
|
||||
- 使用 `textContent` 或 `innerText` 提取时，`<br>` 标签被忽略或转换为空格
|
||||
- 导致多行代码被合并成一行，Mermaid 语法解析失败
|
||||
- **修复**:
|
||||
- 新增 `htmlToText()` 辅助函数，将 `<br>` 标签转换为换行符
|
||||
- 改进 `extractContainerContent()` 函数，使用 `innerHTML` 而不是 `textContent`
|
||||
- 调用 `htmlToText()` 正确处理 HTML 结构
|
||||
- **Commit**: b4ba37a
|
||||
|
||||
## 技术细节
|
||||
|
||||
### WP-Markdown 生成的 HTML 结构
|
||||
|
||||
```html
|
||||
<p>::: mermaid<br>
|
||||
flowchart TD<br>
|
||||
Start([用户提交评论]) --> PreProcess[预处理]<br>
|
||||
PreProcess --> CheckEnabled{启用 AI 检测?}<br>
|
||||
:::</p>
|
||||
```
|
||||
|
||||
### htmlToText() 函数
|
||||
|
||||
```javascript
|
||||
htmlToText(html) {
|
||||
// 将 <br> 和 <br/> 转换为换行符
|
||||
let text = html.replace(/<br\s*\/?>/gi, '\n');
|
||||
// 移除其他 HTML 标签
|
||||
text = text.replace(/<[^>]+>/g, '');
|
||||
// 解码 HTML 实体
|
||||
text = text
|
||||
.replace(/ /g, ' ')
|
||||
.replace(/</g, '<')
|
||||
.replace(/>/g, '>')
|
||||
.replace(/&/g, '&')
|
||||
.replace(/"/g, '"')
|
||||
.replace(/'/g, "'");
|
||||
return text;
|
||||
}
|
||||
```
|
||||
|
||||
### 提取流程
|
||||
|
||||
```
|
||||
1. 检测到 ::: mermaid 开始标记
|
||||
2. 提取 innerHTML（包含 <br> 标签）
|
||||
原始: "::: mermaid<br>flowchart TD<br>Start --> End<br>:::"
|
||||
3. 使用 htmlToText() 转换
|
||||
结果: "::: mermaid\nflowchart TD\nStart --> End\n:::"
|
||||
4. 移除开始和结束标记
|
||||
结果: "flowchart TD\nStart --> End"
|
||||
5. 创建容器元素存储完整代码
|
||||
```
|
||||
|
||||
## 测试验证
|
||||
|
||||
### 测试文件
|
||||
- `tests/test-mermaid-fixes.html` - 基础功能测试
|
||||
- `tests/test-mermaid-newline.html` - 换行符测试
|
||||
- `tests/test-ai-comment-flow.md` - 复杂流程图测试（100+ 节点）
|
||||
|
||||
### 测试用例
|
||||
|
||||
#### 1. 简单流程图
|
||||
```markdown
|
||||
::: mermaid
|
||||
flowchart TD
|
||||
A[开始] --> B[处理]
|
||||
B --> C[结束]
|
||||
:::
|
||||
```
|
||||
|
||||
#### 2. 复杂流程图（AI 评论审核）
|
||||
- 包含 100+ 个节点
|
||||
- 包含多行文本（`<br/>` 标签）
|
||||
- 包含箭头符号（`-->`, `-->`）
|
||||
- 包含样式定义（`style` 语句）
|
||||
|
||||
#### 3. 带样式的流程图
|
||||
```markdown
|
||||
::: mermaid
|
||||
flowchart LR
|
||||
A[开始] --> B[处理]
|
||||
B --> C[结束]
|
||||
style A fill:#e1f5e1,stroke:#2e7d32
|
||||
style C fill:#ffe1e1,stroke:#c62828
|
||||
:::
|
||||
```
|
||||
|
||||
### 预期结果
|
||||
- ✅ 所有换行符正确保留
|
||||
- ✅ 箭头符号不被转换
|
||||
- ✅ 多行文本正确显示
|
||||
- ✅ 样式定义正确应用
|
||||
- ✅ 复杂流程图正确渲染
|
||||
|
||||
## Git 提交历史
|
||||
|
||||
```
|
||||
0ac5794 - fix: 修复代码高亮和容器语法的两个关键问题
|
||||
b6d9f8c - fix: 修复容器语法和 WP-Markdown 的两个关键问题
|
||||
b4ba37a - fix: 修复 Mermaid 容器语法换行符丢失问题
|
||||
759804d - docs: 更新 Mermaid 使用指南和添加换行符测试页面
|
||||
```
|
||||
|
||||
## 影响范围
|
||||
|
||||
### 修改的文件
|
||||
- `argontheme.js` - 核心修复代码
|
||||
- `docs/mermaid-usage-guide.md` - 使用指南
|
||||
- `tests/test-mermaid-fixes.html` - 测试页面
|
||||
- `tests/test-mermaid-newline.html` - 换行符测试
|
||||
- `tests/test-ai-comment-flow.md` - 复杂流程图测试
|
||||
|
||||
### 影响的功能
|
||||
- ✅ Markdown 容器语法（`::: mermaid ... :::`）
|
||||
- ✅ WP-Markdown 格式（`<div class="mermaid"><script>document.write()</script></div>`）
|
||||
- ✅ 标准格式（`<div class="mermaid">`, `<pre><code class="language-mermaid">`）
|
||||
- ✅ 代码高亮（排除 mermaid 代码块）
|
||||
|
||||
### 向后兼容性
|
||||
- ✅ 完全向后兼容
|
||||
- ✅ 不影响现有功能
|
||||
- ✅ 支持所有现代浏览器
|
||||
|
||||
## 性能影响
|
||||
|
||||
- **DOM 操作**: 使用 `innerHTML` 和正则替换，性能影响可忽略
|
||||
- **内存占用**: 无显著增加
|
||||
- **渲染速度**: 无影响
|
||||
|
||||
## 安全性
|
||||
|
||||
- ✅ 只处理 Mermaid 代码块，不执行任何脚本
|
||||
- ✅ HTML 实体正确解码
|
||||
- ✅ 无 XSS 风险
|
||||
|
||||
## 调试支持
|
||||
|
||||
- 添加详细的 `console.log` 日志
|
||||
- 支持调试模式（主题设置中开启）
|
||||
- 错误时显示友好提示
|
||||
|
||||
## 后续优化建议
|
||||
|
||||
1. **支持更多容器语法**
|
||||
- `::: warning` - 警告框
|
||||
- `::: tip` - 提示框
|
||||
- `::: danger` - 危险框
|
||||
|
||||
2. **性能优化**
|
||||
- 缓存已处理的代码块
|
||||
- 使用 IntersectionObserver 延迟渲染
|
||||
|
||||
3. **测试覆盖**
|
||||
- 添加单元测试
|
||||
- 添加集成测试
|
||||
- 添加性能测试
|
||||
|
||||
4. **文档完善**
|
||||
- 添加更多示例
|
||||
- 添加常见问题解答
|
||||
- 添加故障排除指南
|
||||
|
||||
## 相关资源
|
||||
|
||||
- [Mermaid 官方文档](https://mermaid.js.org/)
|
||||
- [Mermaid Live Editor](https://mermaid.live/)
|
||||
- [VuePress 容器语法](https://vuepress.vuejs.org/guide/markdown.html#custom-containers)
|
||||
- [CommonMark 规范](https://commonmark.org/)
|
||||
|
||||
## 总结
|
||||
|
||||
通过这次修复，Argon 主题的 Mermaid 支持已经非常完善：
|
||||
|
||||
1. ✅ 支持标准的 Markdown 容器语法
|
||||
2. ✅ 兼容 WP-Markdown 插件的特殊格式
|
||||
3. ✅ 正确处理换行符和特殊字符
|
||||
4. ✅ 支持复杂的流程图和样式定义
|
||||
5. ✅ 提供详细的调试信息
|
||||
6. ✅ 完全向后兼容
|
||||
|
||||
用户现在可以放心使用容器语法编写 Mermaid 图表，无需担心格式问题。
|
||||
@@ -1,184 +0,0 @@
|
||||
# Mermaid 图表尺寸优化
|
||||
|
||||
## 问题描述
|
||||
|
||||
在之前的实现中，Mermaid 图表容器没有对 SVG 的高度进行限制，导致：
|
||||
|
||||
1. **低内容图表显示过大**：只有 2-3 个节点的简单流程图可能被渲染得非常大，占据整个屏幕
|
||||
2. **用户体验不佳**：需要大量滚动才能看到后续内容
|
||||
3. **视觉不协调**：简单图表与复杂图表的尺寸差异过大
|
||||
|
||||
## 优化方案
|
||||
|
||||
### 1. 最大高度限制
|
||||
|
||||
为 SVG 元素设置最大高度，避免图表显示过大：
|
||||
|
||||
```css
|
||||
.mermaid-container svg {
|
||||
max-height: 600px; /* 桌面端 */
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 居中显示
|
||||
|
||||
使用 Flexbox 让图表在容器中居中显示：
|
||||
|
||||
```css
|
||||
.mermaid-container {
|
||||
display: flex;
|
||||
justify-content: center;
|
||||
align-items: center;
|
||||
min-height: 100px;
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 宽度自适应
|
||||
|
||||
使用 `width: auto !important` 让图表保持原始宽高比：
|
||||
|
||||
```css
|
||||
.mermaid-container svg {
|
||||
max-width: 100%;
|
||||
width: auto !important;
|
||||
height: auto;
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 响应式适配
|
||||
|
||||
针对不同屏幕尺寸设置不同的最大高度：
|
||||
|
||||
```css
|
||||
/* 桌面端 */
|
||||
.mermaid-container svg {
|
||||
max-height: 600px;
|
||||
}
|
||||
|
||||
/* 平板（<768px） */
|
||||
@media screen and (max-width: 768px) {
|
||||
.mermaid-container svg {
|
||||
max-height: 500px;
|
||||
}
|
||||
}
|
||||
|
||||
/* 手机（<480px） */
|
||||
@media screen and (max-width: 480px) {
|
||||
.mermaid-container svg {
|
||||
max-height: 400px;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 优化效果
|
||||
|
||||
### 优化前
|
||||
|
||||
- ❌ 简单图表（2-3 节点）可能显示超大，占据整个屏幕
|
||||
- ❌ 图表尺寸不可控，用户体验差
|
||||
- ❌ 需要大量滚动才能看到后续内容
|
||||
|
||||
### 优化后
|
||||
|
||||
- ✅ 简单图表显示合理大小，不会过大
|
||||
- ✅ 图表在容器中居中显示，视觉协调
|
||||
- ✅ 复杂图表高度限制在 600px，出现滚动条
|
||||
- ✅ 响应式适配，移动端体验更好
|
||||
|
||||
## 测试方法
|
||||
|
||||
使用测试文件验证优化效果：
|
||||
|
||||
```bash
|
||||
# 在浏览器中打开测试文件
|
||||
tests/test-mermaid-size-optimization.html
|
||||
```
|
||||
|
||||
### 测试检查清单
|
||||
|
||||
- [ ] 极简图表（2-3 节点）不会显示过大
|
||||
- [ ] 图表在容器中居中显示
|
||||
- [ ] 中等复杂度图表显示正常
|
||||
- [ ] 复杂图表高度限制在 600px
|
||||
- [ ] 横向图表宽度自适应
|
||||
- [ ] 夜间模式下图表显示正常
|
||||
- [ ] 移动端响应式适配正常
|
||||
|
||||
## 技术细节
|
||||
|
||||
### CSS 关键属性
|
||||
|
||||
```css
|
||||
.mermaid-container {
|
||||
/* 使用 Flexbox 居中 */
|
||||
display: flex;
|
||||
justify-content: center;
|
||||
align-items: center;
|
||||
|
||||
/* 最小高度，避免空白过小 */
|
||||
min-height: 100px;
|
||||
|
||||
/* 其他样式 */
|
||||
background: var(--card-background);
|
||||
border-radius: var(--card-radius);
|
||||
padding: 20px;
|
||||
margin: 20px 0;
|
||||
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
|
||||
overflow-x: auto;
|
||||
max-width: 100%;
|
||||
transition: opacity 0.3s ease-in;
|
||||
}
|
||||
|
||||
.mermaid-container svg {
|
||||
/* 宽度限制 */
|
||||
max-width: 100%;
|
||||
width: auto !important;
|
||||
|
||||
/* 高度限制 */
|
||||
max-height: 600px;
|
||||
height: auto;
|
||||
|
||||
/* 居中显示 */
|
||||
display: block;
|
||||
margin: 0 auto;
|
||||
}
|
||||
```
|
||||
|
||||
### 为什么使用 `width: auto !important`
|
||||
|
||||
Mermaid 会自动设置 SVG 的 `width` 属性，可能导致图表过大。使用 `!important` 强制覆盖，让浏览器根据 `max-width` 和 `max-height` 自动计算宽度，保持原始宽高比。
|
||||
|
||||
### 为什么使用 Flexbox
|
||||
|
||||
使用 Flexbox 可以轻松实现图表在容器中的居中显示，无论图表大小如何变化，都能保持居中对齐。
|
||||
|
||||
## 兼容性
|
||||
|
||||
- ✅ 现代浏览器（Chrome, Firefox, Safari, Edge）
|
||||
- ✅ 移动端浏览器
|
||||
- ✅ 夜间模式
|
||||
- ✅ 响应式布局
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **滚动条**：当图表高度超过最大高度时，容器会出现垂直滚动条
|
||||
2. **宽高比**：图表会保持原始宽高比，不会变形
|
||||
3. **性能**：优化不会影响 Mermaid 的渲染性能
|
||||
4. **兼容性**：与现有的 Mermaid 功能完全兼容
|
||||
|
||||
## 相关文件
|
||||
|
||||
- `style.css` - Mermaid 容器样式定义
|
||||
- `tests/test-mermaid-size-optimization.html` - 尺寸优化测试文件
|
||||
- `docs/mermaid-usage-guide.md` - Mermaid 使用指南
|
||||
- `docs/mermaid-troubleshooting.md` - Mermaid 故障排除
|
||||
|
||||
## 更新日志
|
||||
|
||||
### 2026-01-24
|
||||
|
||||
- ✅ 添加 SVG 最大高度限制（600px）
|
||||
- ✅ 使用 Flexbox 实现图表居中
|
||||
- ✅ 添加响应式适配（平板 500px，手机 400px）
|
||||
- ✅ 添加最小高度限制（100px）
|
||||
- ✅ 创建尺寸优化测试文件
|
||||
@@ -1,347 +0,0 @@
|
||||
# Mermaid 支持方案对比
|
||||
|
||||
## 概述
|
||||
|
||||
Argon 主题现在支持多种 Mermaid 图表标记方式，每种方式都有其优缺点和适用场景。
|
||||
|
||||
---
|
||||
|
||||
## 方案对比表
|
||||
|
||||
| 方案 | 语法 | 优点 | 缺点 | 推荐度 | 适用场景 |
|
||||
|------|------|------|------|--------|----------|
|
||||
| **Shortcode** | `[mermaid]...[/mermaid]` | ✅ 最可靠<br>✅ 支持参数<br>✅ 不被格式化<br>✅ 易于编辑 | ❌ 需要记住语法 | ⭐⭐⭐⭐⭐ | **所有场景（推荐）** |
|
||||
| 容器语法 | `::: mermaid ... :::` | ✅ 符合 Markdown 规范<br>✅ 易于迁移 | ❌ 被 WP 格式化<br>❌ 换行符问题<br>❌ 特殊字符转换 | ⭐⭐⭐ | 简单图表 |
|
||||
| 代码块 | ` ```mermaid ... ``` ` | ✅ 通用语法<br>✅ 编辑器高亮 | ❌ 被代码高亮干扰<br>❌ 嵌套问题 | ⭐⭐ | 不推荐 |
|
||||
| HTML | `<div class="mermaid">...</div>` | ✅ 灵活<br>✅ 完全控制 | ❌ 编辑不便<br>❌ 可读性差 | ⭐⭐ | 特殊需求 |
|
||||
|
||||
---
|
||||
|
||||
## 详细对比
|
||||
|
||||
### 1. Shortcode 方式 ⭐⭐⭐⭐⭐（推荐）
|
||||
|
||||
#### 语法
|
||||
```
|
||||
[mermaid theme="default" width="100%" align="center"]
|
||||
flowchart TD
|
||||
A[开始] --> B[处理]
|
||||
B --> C[结束]
|
||||
[/mermaid]
|
||||
```
|
||||
|
||||
#### 优点
|
||||
- ✅ **最可靠**：不依赖 WP-Markdown 的处理方式
|
||||
- ✅ **不被破坏**：不会被 WordPress 自动格式化
|
||||
- ✅ **支持参数**：theme、width、height、align
|
||||
- ✅ **易于编辑**：在编辑器中清晰可见
|
||||
- ✅ **完全兼容**：与其他 Shortcode 一样使用
|
||||
|
||||
#### 缺点
|
||||
- ❌ 需要记住 Shortcode 语法
|
||||
- ❌ 不是标准 Markdown 语法
|
||||
|
||||
#### 适用场景
|
||||
- ✅ **所有场景**（强烈推荐）
|
||||
- ✅ 复杂流程图
|
||||
- ✅ 需要自定义样式
|
||||
- ✅ 长期维护的文档
|
||||
|
||||
#### 示例
|
||||
```
|
||||
[mermaid theme="dark" width="80%"]
|
||||
sequenceDiagram
|
||||
Alice->>Bob: Hello
|
||||
Bob-->>Alice: Hi
|
||||
[/mermaid]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. 容器语法 ⭐⭐⭐
|
||||
|
||||
#### 语法
|
||||
```markdown
|
||||
::: mermaid
|
||||
flowchart TD
|
||||
A --> B
|
||||
:::
|
||||
```
|
||||
|
||||
#### 优点
|
||||
- ✅ 符合 Markdown 扩展规范
|
||||
- ✅ VuePress、Docusaurus 等使用相同语法
|
||||
- ✅ 易于迁移到其他平台
|
||||
|
||||
#### 缺点
|
||||
- ❌ **被 WordPress 格式化破坏**
|
||||
- `-->` 转换为 `–>`
|
||||
- 换行符可能丢失
|
||||
- 需要复杂的 JavaScript 处理
|
||||
- ❌ 不支持参数配置
|
||||
- ❌ 依赖 WP-Markdown 的处理方式
|
||||
|
||||
#### 适用场景
|
||||
- ✅ 简单的流程图
|
||||
- ✅ 不包含特殊字符
|
||||
- ✅ 需要跨平台兼容
|
||||
|
||||
#### 注意事项
|
||||
- ⚠️ 避免使用 `-->` 箭头（可能被转换）
|
||||
- ⚠️ 避免复杂的多行文本
|
||||
- ⚠️ 需要开启主题的 Mermaid 支持
|
||||
|
||||
---
|
||||
|
||||
### 3. 代码块方式 ⭐⭐
|
||||
|
||||
#### 语法
|
||||
````markdown
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A --> B
|
||||
```
|
||||
````
|
||||
|
||||
#### 优点
|
||||
- ✅ 通用的 Markdown 语法
|
||||
- ✅ 编辑器可能提供语法高亮
|
||||
|
||||
#### 缺点
|
||||
- ❌ **被代码高亮干扰**
|
||||
- Prism.js 会处理代码块
|
||||
- 可能出现嵌套问题
|
||||
- ❌ 被 WP-Markdown 包裹在 `document.write()` 中
|
||||
- ❌ 需要特殊处理排除
|
||||
|
||||
#### 适用场景
|
||||
- ⚠️ **不推荐使用**
|
||||
- 仅在其他方式不可用时考虑
|
||||
|
||||
#### 注意事项
|
||||
- ⚠️ 需要在代码高亮中排除 mermaid
|
||||
- ⚠️ 可能出现渲染冲突
|
||||
|
||||
---
|
||||
|
||||
### 4. HTML 方式 ⭐⭐
|
||||
|
||||
#### 语法
|
||||
```html
|
||||
<div class="mermaid">
|
||||
flowchart TD
|
||||
A --> B
|
||||
</div>
|
||||
```
|
||||
|
||||
#### 优点
|
||||
- ✅ 完全控制 HTML 结构
|
||||
- ✅ 可以添加自定义属性
|
||||
|
||||
#### 缺点
|
||||
- ❌ 编辑不便
|
||||
- ❌ 可读性差
|
||||
- ❌ 不符合 Markdown 风格
|
||||
|
||||
#### 适用场景
|
||||
- ✅ 需要特殊的 HTML 结构
|
||||
- ✅ 需要自定义 CSS 类
|
||||
- ✅ 程序生成的内容
|
||||
|
||||
---
|
||||
|
||||
## 使用建议
|
||||
|
||||
### 新项目
|
||||
|
||||
**强烈推荐使用 Shortcode 方式**：
|
||||
|
||||
```
|
||||
[mermaid]
|
||||
flowchart TD
|
||||
A --> B
|
||||
[/mermaid]
|
||||
```
|
||||
|
||||
**理由**：
|
||||
1. 最可靠，不会被破坏
|
||||
2. 支持参数配置
|
||||
3. 易于维护
|
||||
4. 长期稳定
|
||||
|
||||
### 现有项目迁移
|
||||
|
||||
如果你已经使用了容器语法 `::: mermaid ... :::`：
|
||||
|
||||
#### 选项 1：保持不变（简单图表）
|
||||
- 如果图表简单，没有特殊字符
|
||||
- 如果渲染正常，无需修改
|
||||
|
||||
#### 选项 2：迁移到 Shortcode（推荐）
|
||||
- 批量替换：`::: mermaid` → `[mermaid]`
|
||||
- 批量替换：`:::` → `[/mermaid]`
|
||||
- 测试验证
|
||||
|
||||
### 不同场景的选择
|
||||
|
||||
#### 场景 1：技术文档
|
||||
**推荐**：Shortcode
|
||||
- 需要长期维护
|
||||
- 图表复杂
|
||||
- 需要自定义样式
|
||||
|
||||
#### 场景 2：博客文章
|
||||
**推荐**：Shortcode
|
||||
- 简单易用
|
||||
- 不需要记住复杂语法
|
||||
- 稳定可靠
|
||||
|
||||
#### 场景 3：跨平台内容
|
||||
**推荐**：容器语法（如果目标平台支持）
|
||||
- 需要在多个平台发布
|
||||
- 目标平台支持容器语法
|
||||
- 可以接受一些限制
|
||||
|
||||
#### 场景 4：程序生成
|
||||
**推荐**：HTML 或 Shortcode
|
||||
- 由程序自动生成
|
||||
- 需要批量处理
|
||||
- 可以使用模板
|
||||
|
||||
---
|
||||
|
||||
## 性能对比
|
||||
|
||||
| 方案 | 渲染速度 | 内存占用 | 兼容性 | 稳定性 |
|
||||
|------|----------|----------|--------|--------|
|
||||
| Shortcode | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
|
||||
| 容器语法 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
|
||||
| 代码块 | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ | ⭐⭐ |
|
||||
| HTML | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q1: 为什么推荐 Shortcode 而不是容器语法？
|
||||
|
||||
**A**: 容器语法虽然符合 Markdown 规范，但在 WordPress 环境下会遇到以下问题：
|
||||
1. WordPress 的 `wptexturize()` 会转换特殊字符
|
||||
2. WP-Markdown 的处理方式不一致
|
||||
3. 需要复杂的 JavaScript 来修复这些问题
|
||||
|
||||
Shortcode 方式完全避免了这些问题，更加可靠。
|
||||
|
||||
### Q2: 可以混用多种方式吗？
|
||||
|
||||
**A**: 可以，但不推荐。建议统一使用一种方式，便于维护。
|
||||
|
||||
### Q3: 如何批量迁移到 Shortcode？
|
||||
|
||||
**A**: 使用 WordPress 的搜索替换功能：
|
||||
1. 安装 "Better Search Replace" 插件
|
||||
2. 搜索：`::: mermaid`，替换为：`[mermaid]`
|
||||
3. 搜索：`:::`（在 mermaid 代码块后），替换为：`[/mermaid]`
|
||||
4. 测试验证
|
||||
|
||||
### Q4: Shortcode 支持哪些参数？
|
||||
|
||||
**A**:
|
||||
- `theme`: 主题（default, dark, forest, neutral）
|
||||
- `width`: 宽度（100%, 80%, 600px 等）
|
||||
- `height`: 高度（auto, 500px 等）
|
||||
- `align`: 对齐（left, center, right）
|
||||
|
||||
### Q5: 容器语法还会继续支持吗？
|
||||
|
||||
**A**: 会继续支持，但不推荐新项目使用。我们会持续修复容器语法的问题，但 Shortcode 是更好的选择。
|
||||
|
||||
---
|
||||
|
||||
## 技术实现对比
|
||||
|
||||
### Shortcode 实现
|
||||
|
||||
**PHP 端**（functions.php）：
|
||||
```php
|
||||
add_shortcode('mermaid','shortcode_mermaid');
|
||||
function shortcode_mermaid($attr,$content=""){
|
||||
$content = shortcode_content_preprocess($attr, $content);
|
||||
$theme = isset( $attr['theme'] ) ? $attr['theme'] : 'default';
|
||||
// ... 生成 HTML
|
||||
return $out;
|
||||
}
|
||||
```
|
||||
|
||||
**JavaScript 端**（argontheme.js）：
|
||||
```javascript
|
||||
const selectors = [
|
||||
'div.mermaid-shortcode', // 直接检测
|
||||
// ...
|
||||
];
|
||||
```
|
||||
|
||||
**优点**：
|
||||
- ✅ 简单直接
|
||||
- ✅ 不需要复杂的解析
|
||||
- ✅ 性能最优
|
||||
|
||||
### 容器语法实现
|
||||
|
||||
**JavaScript 端**（argontheme.js）：
|
||||
```javascript
|
||||
// 1. 检测容器语法
|
||||
detectContainerBlocks(blocks);
|
||||
|
||||
// 2. 提取内容
|
||||
extractContainerContent(startElement, processedElements);
|
||||
|
||||
// 3. 转换 HTML
|
||||
htmlToText(html);
|
||||
|
||||
// 4. 修复特殊字符
|
||||
text.replace(/–/g, '-');
|
||||
```
|
||||
|
||||
**缺点**：
|
||||
- ❌ 需要复杂的 DOM 遍历
|
||||
- ❌ 需要处理多种 HTML 结构
|
||||
- ❌ 需要修复 WordPress 的格式化
|
||||
- ❌ 性能开销较大
|
||||
|
||||
---
|
||||
|
||||
## 总结
|
||||
|
||||
### 推荐方案
|
||||
|
||||
1. **首选**：Shortcode 方式 `[mermaid]...[/mermaid]`
|
||||
- 最可靠、最稳定
|
||||
- 支持参数配置
|
||||
- 易于维护
|
||||
|
||||
2. **备选**：容器语法 `::: mermaid ... :::`
|
||||
- 简单图表可用
|
||||
- 跨平台兼容
|
||||
- 需要注意限制
|
||||
|
||||
3. **不推荐**：代码块和 HTML 方式
|
||||
- 仅在特殊情况下使用
|
||||
|
||||
### 迁移建议
|
||||
|
||||
- ✅ 新项目：直接使用 Shortcode
|
||||
- ✅ 现有项目：逐步迁移到 Shortcode
|
||||
- ✅ 简单图表：可以保持容器语法
|
||||
|
||||
### 文档链接
|
||||
|
||||
- [Shortcode 使用指南](./mermaid-shortcode-guide.md)
|
||||
- [容器语法使用指南](./mermaid-usage-guide.md)
|
||||
- [修复总结](./mermaid-fix-summary.md)
|
||||
- [开发者指南](./mermaid-developer-guide.md)
|
||||
|
||||
---
|
||||
|
||||
**最后更新**：2026-01-24
|
||||
**版本**：Argon v2.x
|
||||
Reference in New Issue
Block a user