validation-tools-cli

Comprehensive guide to CLI tools for validating Mermaid diagram syntax in markdown files.

Overview

Several CLI tools exist for validating Mermaid diagrams. They differ in implementation language, validation approach, and integration capabilities.

1. mermaid-validate (Node.js)

GitHub: cloud-on-prem/mermaid-validator

Installation

npm install -g mermaid-validate

Usage

Validate a diagram file:

mermaid-validate validate diagram.mmd

Validate a diagram string:

mermaid-validate validate "<diagram-string>" --string

Validate all Mermaid diagrams in a markdown file:

mermaid-validate validate-md document.md

Key Features

• Dedicated markdown file validation with validate-md command
• String validation for inline testing
• File-based validation for .mmd files
• CLI and programmatic API available

Use Case

Best for validating multiple diagrams across markdown documentation in Node.js projects.

2. go-mermaid (Go)

GitHub: sammcj/go-mermaid Package: pkg.go.dev/github.com/sammcj/go-mermaid

Installation

go install github.com/sammcj/go-mermaid@latest

Features

• Pure Go parser and validator
• Custom linting rules support
• Extract diagrams from markdown files
• Parse Mermaid syntax from raw text
• Programmatic validation API

Use Case

Best for Go projects or systems where Node.js/JavaScript runtime is unavailable. Enables custom linting rules tailored to project needs.

3. @mermaid-js/mermaid-cli (Official)

GitHub: mermaid-js/mermaid-cli NPM: @mermaid-js/mermaid-cli

Installation

npm install -g @mermaid-js/mermaid-cli

Usage

Validate by attempting to render:

mmdc -i diagram.mmd -o /tmp/test.svg

Pipe input from stdin:

cat diagram.mmd | mmdc -i - -o /tmp/test.svg

Use with npx (package name differs from command):

npx -p @mermaid-js/mermaid-cli mmdc -i diagram.mmd -o output.png

Validation Approach

The CLI validates syntax indirectly by attempting to render diagrams:

• If syntax is valid → SVG/PNG/PDF generated successfully
• If syntax is invalid → Error output to stderr

Key Features

• Official Mermaid project tool
• Renders diagrams to multiple formats (SVG, PNG, PDF)
• Theme and background customization
• Markdown file transformation (finds diagrams, creates SVGs, updates references)
• Stdin support for piping

Use Case

Best for projects already using the official Mermaid ecosystem. Validates syntax while producing visual output for documentation.

4. MCP Mermaid Validator (for AI Agents)

GitHub: rtuin/mcp-mermaid-validator NPM: @rtuin/mcp-mermaid-validator MCP Market: Mermaid Validator

Installation for Claude Code

claude mcp add-json "mermaid-validator" '{"command":"npx","args":["-y","@rtuin/mcp-mermaid-validator@latest"]}'

Features

• Model Context Protocol (MCP) server for LLM integration
• Validates and renders Mermaid diagrams
• Provides PNG output for visual confirmation
• Enables AI agents to verify diagram syntax

Validation Approach

The diagram is passed to mmdc via stdin, mmdc validates syntax and renders PNG if valid, and output/errors are captured from stdout/stderr.

Use Case

Best for AI-assisted documentation workflows where LLMs generate diagrams and need automated validation feedback.

Alternative: Mermaider

GitHub: vtomilin/mermaider

More efficient than traditional MCP validators:

• Uses puppeteer-core and mermaid-js API directly
• Leverages already-installed Chrome/Firefox browsers
• Avoids spawning mmdc process for every validation
• Provides validate_syntax tool for syntax error checking
• Supports all Mermaid diagram types

5. markdown-mermaid-cli (Python)

PyPI: markdown-mermaid-cli

Installation

pip install markdown-mermaid-cli

Features

• Python-Markdown extension
• Uses Mermaid-CLI under the hood
• Converts diagrams to Base64 encoded data URIs
• Enables PDF generation without client-side JavaScript
• Compatible with MkDocs, WeasyPrint

Use Case

Best for Python documentation projects using MkDocs or Sphinx that need to generate PDFs with embedded diagrams.

Comparison Matrix

Claude Code Validation Skill

Blog Post: A Mermaid Validation Skill for Claude Code Another Post: Agent Mermaid reporting for duty

Claude Code skills teach Claude domain-specific workflows. The Mermaid validation skill:

• Uses mmdc command for validation
• Command: mmdc -i <file-path> -o /tmp/mermaid-validation.svg 2>&1
• Validates diagrams before marking work complete
• Provides feedback loop for AI-generated diagrams

Validation Strategy Recommendations

For Node.js Projects

Use mermaid-validate for dedicated markdown validation:

npm install --save-dev mermaid-validate
mermaid-validate validate-md docs/**/*.md

For Go Projects

Use go-mermaid for native Go integration:

go install github.com/sammcj/go-mermaid@latest
go-mermaid validate docs/

For Python/MkDocs Projects

Use markdown-mermaid-cli for PDF generation:

pip install markdown-mermaid-cli

For AI-Assisted Workflows

Use MCP Mermaid Validator or Mermaider:

claude mcp add-json "mermaid-validator" '{"command":"npx","args":["-y","@rtuin/mcp-mermaid-validator@latest"]}'

For Visual Output + Validation

Use @mermaid-js/mermaid-cli (official):

mmdc -i diagram.mmd -o output.png -t dark -b transparent

Known Issues

.md File Extension Confusion

Issue: mermaid-js/mermaid-cli#160

When using .md file extensions with raw Mermaid syntax (without proper markdown code fences), mmdc may produce errors.

Solution:

• Use .mmd extension for raw Mermaid syntax files
• Use proper markdown code fences in .md files:

  ```mermaid
  graph TD
      A --> B
  ```

Syntax Errors During Pre-commit

Issue: lukesdm/mermaid-gen

Syntax errors can cause hangs during pre-commit hooks when using automated diagram generation tools.

Solution:

• Validate diagrams locally before committing
• Use fast validators like Mermaider (1-2ms latency)
• Configure pre-commit timeout limits

Sources

1. GitHub - cloud-on-prem/mermaid-validator
2. mermaid package - github.com/sammcj/go-mermaid
3. A Mermaid Validation Skill for Claude Code
4. GitHub - mermaid-js/mermaid-cli
5. Mermaid Validator MCP server for AI agents
6. markdown-mermaid-cli · PyPI
7. Agent Mermaid reporting for duty - Korny’s Blog
8. @mermaid-js/mermaid-cli - npm
9. @rtuin/mcp-mermaid-validator - npm
10. GitHub - vtomilin/mermaider
11. GitHub - rtuin/mcp-mermaid-validator
12. Provide better error message for .md files - Issue #160