Mermaid Validation
Validate mermaid diagram syntax immediately after generating or modifying mermaid code blocks in markdown files, and auto-fix any issues found.
Why This Matters
Mermaid diagrams have strict syntax rules that are easy to get subtly wrong — missing semicolons, incorrect arrow syntax, unquoted labels with special characters, mismatched brackets in subgraphs. Invalid diagrams silently fail to render, leaving the user with a broken code block they have to debug themselves. Validating every diagram before delivering it catches these issues early.
Workflow
After writing or editing any mermaid code block in a markdown file:
- Extract each mermaid block from the file (the content between
```mermaid and ``` fences, not the fences themselves)
- Validate by piping the content through the validation script
- If invalid: fix the errors based on the validator output, then re-validate
- Repeat until all blocks pass
Validation Script
The script uses mermaid-ast, which parses with the grammars vendored from mermaid itself, so a diagram it accepts is one mermaid renders. It covers 18 diagram types and auto-installs on first run to ~/.cache/claude-plugins/mermaid-ast/. A leading frontmatter block is allowed and stripped before parsing. Errors carry a line when the grammar reports one, no column. Known gap: a %% comment inside an erDiagram is rejected although mermaid accepts it.
Usage
Pipe raw mermaid content (without the fences) to stdin:
echo 'flowchart TD
A[Start] --> B[End]' | bash ${CLAUDE_PLUGIN_ROOT}/skills/mermaid-validation/scripts/validate-mermaid.sh
- Exit code 0: valid diagram
- Exit code 1: invalid diagram (errors in JSON output)
Output
The script outputs JSON. The key fields to check are isValid and errors:
{
"isValid": false,
"diagramType": "flowchart",
"errors": [
{
"line": 2,
"message": "Failed to parse flowchart: Parse error on line 2: ... Expecting 'SQE', ..."
}
]
}
Fixing Common Errors
When the validator reports errors, use the line/column info and message to fix the issue in the original mermaid block, then re-validate. Common pitfalls:
- Unquoted labels with special characters: Labels containing
(, ), [, ], {, } need quoting — e.g., A["Process (step 1)"]
- Invalid arrow syntax: Arrows must match the diagram type (
--> for flowcharts, ->> for sequence diagrams)
- Missing diagram type: Every block must start with a type declaration (
flowchart TD, sequenceDiagram, classDiagram, etc.)
- Subgraph/end mismatch: Every
subgraph needs a corresponding end
- Incorrect node reuse: Once a node is defined with a shape, later references should use just the ID without redefining the shape
Rendering rules the validator cannot catch
The parser accepts these, the renderer breaks them. Check them by eye after validation passes.
- Long lines inside a container are cut. A flowchart node, a subgraph title, a note in a sequence or state diagram, a class box, an entity box: text in any of these is clipped when a line runs past about 24 characters. Break the text with
<br/> at a word boundary before the 24th character, and again every 24 characters after that. Text that is not boxed is unaffected: edge labels, state transition labels and sequence messages wrap or extend on their own.
1---2name: mermaid-validation3description: Validate mermaid diagram syntax after writing mermaid code blocks. Use this skill whenever you generate, write, or edit mermaid diagrams in markdown files — including flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, gantt charts, pie charts, mindmaps, gitgraph, and any other mermaid diagram type. Even if the diagram looks correct, always validate — subtle syntax errors silently break rendering. Trigger on any task that produces or modifies mermaid code blocks.4---56# Mermaid Validation78Validate mermaid diagram syntax immediately after generating or modifying mermaid code blocks in markdown files, and auto-fix any issues found.910## Why This Matters1112Mermaid diagrams have strict syntax rules that are easy to get subtly wrong — missing semicolons, incorrect arrow syntax, unquoted labels with special characters, mismatched brackets in subgraphs. Invalid diagrams silently fail to render, leaving the user with a broken code block they have to debug themselves. Validating every diagram before delivering it catches these issues early.1314## Workflow1516After writing or editing any mermaid code block in a markdown file:17181. **Extract** each mermaid block from the file (the content between ` ```mermaid ` and ` ``` ` fences, not the fences themselves)192. **Validate** by piping the content through the validation script203. If invalid: **fix** the errors based on the validator output, then re-validate214. Repeat until all blocks pass2223## Validation Script2425The script uses [mermaid-ast](https://github.com/neongreen/mermaid-ast), which parses with the grammars vendored from mermaid itself, so a diagram it accepts is one mermaid renders. It covers 18 diagram types and auto-installs on first run to `~/.cache/claude-plugins/mermaid-ast/`. A leading frontmatter block is allowed and stripped before parsing. Errors carry a `line` when the grammar reports one, no column. Known gap: a `%%` comment inside an `erDiagram` is rejected although mermaid accepts it.2627### Usage2829Pipe raw mermaid content (without the fences) to stdin:3031```bash32echo 'flowchart TD33 A[Start] --> B[End]' | bash ${CLAUDE_PLUGIN_ROOT}/skills/mermaid-validation/scripts/validate-mermaid.sh34```3536- **Exit code 0**: valid diagram37- **Exit code 1**: invalid diagram (errors in JSON output)3839### Output4041The script outputs JSON. The key fields to check are `isValid` and `errors`:4243```json44{45 "isValid": false,46 "diagramType": "flowchart",47 "errors": [48 {49 "line": 2,50 "message": "Failed to parse flowchart: Parse error on line 2: ... Expecting 'SQE', ..."51 }52 ]53}54```5556## Fixing Common Errors5758When the validator reports errors, use the line/column info and message to fix the issue in the original mermaid block, then re-validate. Common pitfalls:5960- **Unquoted labels with special characters**: Labels containing `(`, `)`, `[`, `]`, `{`, `}` need quoting — e.g., `A["Process (step 1)"]`61- **Invalid arrow syntax**: Arrows must match the diagram type (`-->` for flowcharts, `->>` for sequence diagrams)62- **Missing diagram type**: Every block must start with a type declaration (`flowchart TD`, `sequenceDiagram`, `classDiagram`, etc.)63- **Subgraph/end mismatch**: Every `subgraph` needs a corresponding `end`64- **Incorrect node reuse**: Once a node is defined with a shape, later references should use just the ID without redefining the shape6566## Rendering rules the validator cannot catch6768The parser accepts these, the renderer breaks them. Check them by eye after validation passes.6970- **Long lines inside a container are cut.** A flowchart node, a subgraph title, a note in a sequence or state diagram, a class box, an entity box: text in any of these is clipped when a line runs past about 24 characters. Break the text with `<br/>` at a word boundary before the 24th character, and again every 24 characters after that. Text that is not boxed is unaffected: edge labels, state transition labels and sequence messages wrap or extend on their own.
asermax