1351371bd2
- Add skill that uses check-mermaid.js to validate Mermaid diagrams - Skill guides Claude to parse error reports and apply intelligent fixes - Fixes common Mermaid parser bugs (parentheses, brackets, braces in labels) - Include demo scripts with test Markdown file for validation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
151 lines
4.0 KiB
Markdown
151 lines
4.0 KiB
Markdown
---
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```markdown
|
|
## 🚨 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
|
|
```mermaid
|
|
# 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
|
|
```mermaid
|
|
# 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
|
|
```mermaid
|
|
# 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)|` | Change to `-->|"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
|
|
```
|