mermaid-simple-validator

Validate mermaid diagram syntax in Markdown files and .mermaid files — no browser required.

Uses JSDOM to create a fake DOM so mermaid can parse and validate diagrams purely in Node.js.

Install

npm install mermaid-simple-validator

Usage

npx mermaid-simple-validate [-L] <path>

• <path> — a .md file, a .mermaid file, or a directory (scanned recursively)
• -L — follow symbolic links when scanning a directory

Supported files

| Extension | Behaviour | |------------|-----------| | .md | Extracts ```mermaid … ``` fenced blocks; line ranges in the output exclude the fences | | .mermaid | Validates the entire file content as a single diagram |

Examples

Validate a single file:

npx mermaid-simple-validate diagrams.md

Scan a directory recursively (symlinks are skipped by default):

npx mermaid-simple-validate docs/

Scan a directory and follow symlinks:

npx mermaid-simple-validate -L docs/

Output

Given diagrams.md:

## Flowchart

```mermaid
flowchart TD
  A --> B
  B --> C
```

## Broken diagram

```mermaid
flowchart LR
  X -> Y  %% `->` is invalid
```

npx mermaid-simple-validate diagrams.md

Output:

diagrams.md:
  block 1 (lines 4-6): valid (flowchart-v2)
  block 2 (lines 12-13): INVALID
    Parse error on line 2:
    flowchart LR    X -> Y
    ...
    Expecting 'SEMI', 'NEWLINE', 'EOF', 'AMP', 'START_LINK', 'LINK', 'LINK_ID', got 'MINUS'

1 error(s) found.

Exit code is 1 when any block fails validation, 0 otherwise.

How it works

1. Scans a file or directory for .md and .mermaid files
2. For .md files — extracts ```mermaid fenced code blocks and records their line range (excluding fences)
3. For .mermaid files — treats the entire file content as a mermaid diagram
4. Creates a lightweight JSDOM window/document
5. Calls mermaid.parse() on each block
6. Reports success (with detected diagram type) or the parse error, including the exact line range

License

MIT