claudeskill/skills/mermaid-fixer/SKILL.md

name: mermaid-fixer description: Fix Mermaid diagram syntax errors in Markdown files. Use when: (1) Mermaid diagrams aren't rendering or show parse errors, (2) User mentions "mermaid syntax error", "mermaid not working", "diagram broken", (3) CI/CD fails on Mermaid validation, (4) Documentation contains Mermaid code blocks that need fixing.

Mermaid Diagram Fixer

Automatically detects and fixes Mermaid diagram syntax errors in Markdown files using the check-mermaid.js validation script.

How It Works

1. Run check-mermaid.js to get detailed error reports
2. Parse error information (line numbers, error types, code snippets)
3. Apply intelligent fixes based on the specific error
4. Verify by running the check again

Core Script

The scripts/check-mermaid.js script is the heart of this skill. It:

• Scans Markdown files for ```mermaid code blocks
• Validates each block using the Mermaid CLI (mmdc)
• Returns detailed error reports with line numbers and error messages

Workflow

Step 1: Run the Check Script

node scripts/check-mermaid.js <path/to/file.md>

Expected output format:

• No errors: Returns exit code 0 with success message
• Has errors: Returns exit code 1 with structured error report:

## 🚨 Mermaid 语法检查报告

**检查文件：** `example.md`
**检查结果：** ❌ 发现 2 处语法错误 (共检测到 5 个代码块)

---

### ❌ 错误 #1 (代码块 #2)

- **文档位置：** 第 `51` 行至第 `86` 行

#### 核心错误详情
\`\`\`text
Error: Parse error on line 13: ...
Expecting 'SQE', 'DOUBLECIRCLEEND', ... got 'PS'
\`\`\`

#### 代码内容片段
\`\`\`text
[shows the problematic code]
\`\`\`

Step 2: Parse and Understand Errors

Key information from each error:

• 文档位置: Which line numbers contain the error
• 核心错误详情: The parser error message
• 代码内容片段: The actual Mermaid code causing the issue

Step 3: Apply Fixes Based on Error Type

Error Type: "got 'PS'" (Parentheses Issue)

Cause: Parentheses () in node labels or arrow labels within subgraphs

Fix: Quote the label

# Before (causes error)
NodeA[Label (with parens)]
-->|Label (parens)| NodeB

# After (fixed)
NodeA["Label (with parens)"]
-->"|Label (parens)|" NodeB

Error Type: "got 'SQS'" (Square Brackets Issue)

Cause: Square brackets [] in node labels

Fix: Quote the label

# Before
NodeA[Result[]<br/>text]

# After
NodeA["Result[]<br/>text"]

Error Type: "got 'DIAMOND_START'" or similar

Cause: Curly braces {} or other special characters in labels

Fix: Quote the label

# Before
NodeA[Label {variable}]

# After
NodeA["Label {variable}"]

Step 4: Apply the Fix to the File

1. Read the Markdown file
2. Locate the problematic code block using the reported line numbers
3. Apply the appropriate fix (quote labels with special characters)
4. Save the file

Step 5: Verify

Run check-mermaid.js again to confirm all errors are resolved.

Common Fix Patterns

Error Pattern	Fix Strategy
NodeID[label (text)]	Change to NodeID["label (text)"]
`-->	label (text)
NodeID[label[]text]	Change to NodeID["label[]text"]
NodeID[label{text}]	Change to NodeID["label{text}"]

Important Notes

1. Always quote labels containing: (), [], {}, <, >, #, or Chinese characters
2. Preserve the original structure - only modify the problematic labels
3. Check all reported errors - don't stop after fixing just one
4. Re-verify after each fix round

Example Usage

User: "My Mermaid diagrams in docs/architecture.md aren't rendering"

Claude:
1. Run: node scripts/check-mermaid.js docs/architecture.md
2. Parse error output
3. Identify errors (e.g., "got 'PS'" on line 45)
4. Read file, locate line 45, find the Mermaid block
5. Apply fix: quote labels with parentheses
6. Save and verify