mermaid-check

Mermaid 语法检查与修复

本项目使用 mermaid 9.4.3（CDN 加载），配置 htmlLabels: false，securityLevel: 'loose'。 图表写在 ```mermaid 代码围栏中，由 _layouts/default.html 中的 JS 转换后渲染。

---

渲染管线原理

```mermaid 代码围栏
  ↓ kramdown 渲染
<div class="language-mermaid"><code>原始文本（HTML 实体转义）</code></div>
  ↓ 项目 JS（default.html）
code.textContent → 原始 mermaid 文本（含 <br>、-->、| 等）
  ↓ srcToInnerHTML() 转换
innerHTML: 转义 < > & 但保留 <br/> 为真实 HTML 标签
  ↓ mermaid.init()
读取 innerHTML → entityDecode() → 解析器

关键函数 srcToInnerHTML

function srcToInnerHTML(src) {
    return src
        .replace(/&/g, '&')
        .replace(/</g, '&lt;')
        .replace(/>/g, '&gt;')
        .replace(/&lt;br\s*\/?&gt;/gi, '<br/>');
}

原理：先将所有 HTML 特殊字符转义，再把 <br> 从实体还原为真实标签。 mermaid 的 entityDecode 通过 escape()/unescape() 能正确处理：

• --> → 解码回 -->
• <br/> (真实标签) → escape 变为 %3Cbr/%3E → unescape 变回 <br/>
• | → escape 变为 %7C → unescape 变回 |

---

使用 Node.js 验证 mermaid 语法

安装 mermaid CLI：

npm install -g @mermaid-js/mermaid-cli

验证单个图表：

echo 'flowchart LR
    A[text] -->|label| B' > /tmp/test.mmd
npx mmdc -i /tmp/test.mmd -o /tmp/test.svg 2>&1

批量验证项目中所有 mermaid 块：

python3 << 'EOF'
import re, os, subprocess, tempfile

base = os.getcwd()
errors = []
for root, dirs, files in os.walk(base):
    dirs[:] = [d for d in dirs if d not in ['.git', '.claude', 'node_modules']]
    for f in files:
        if not f.endswith('.md'): continue
        path = os.path.join(root, f)
        with open(path) as fh:
            content = fh.read()
        for m in re.finditer(r'```mermaid\n(.*?)\n```', content, re.DOTALL):
            block = m.group(1)
            line = content[:m.start()].count('\n') + 1
            with tempfile.NamedTemporaryFile(suffix='.mmd', mode='w', delete=False) as tmp:
                tmp.write(block)
                tmp_path = tmp.name
            result = subprocess.run(
                ['npx', 'mmdc', '-i', tmp_path, '-o', '/dev/null'],
                capture_output=True, text=True
            )
            os.unlink(tmp_path)
            if result.returncode != 0:
                errors.append((path, line, result.stderr.strip()))