feat: Add mermaid-fixer skill for automatic Mermaid syntax error correction
- 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>
This commit is contained in:
Misaka_Company
150
skills/mermaid-fixer/SKILL.md
Normal file
150
skills/mermaid-fixer/SKILL.md
Normal file
@@ -0,0 +1,150 @@
|
||||
---
|
||||
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
|
||||
```
|
||||
Reference in New Issue
Block a user