# Mermaid Validation

> 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.

- Skill: `asermax/mermaid-validation` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add asermax/mermaid-validation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/asermax/mermaid-validation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: asermax (https://skillmd.com/u/asermax)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/asermax/mermaid-validation

---


# 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:

1. **Extract** each mermaid block from the file (the content between ` ```mermaid ` and ` ``` ` fences, not the fences themselves)
2. **Validate** by piping the content through the validation script
3. If invalid: **fix** the errors based on the validator output, then re-validate
4. Repeat until all blocks pass

## Validation Script

The 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.

### Usage

Pipe raw mermaid content (without the fences) to stdin:

```bash
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`:

```json
{
  "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.