Guide to integrating Mermaid diagram validation into automated workflows, CI/CD pipelines, and git pre-commit hooks.

Overview

Validating Mermaid diagrams early in the development workflow catches syntax errors before they reach production. Integration points include:

  1. Pre-commit hooks - Validate locally before commits
  2. CI/CD pipelines - Validate on pull requests and merges
  3. Automated fixes - Auto-correct common syntax issues

Pre-commit Framework Setup

Reference: Implementing Quality Checks In Your Git Workflow

The pre-commit framework provides a standardized way to run validation checks during the pre-commit phase.

Why Pre-commit?

“Given how useful checking code quality is before committing, there’s actually a framework around git hooks called pre-commit. It’s somewhat like a mini-GitHub Actions that can be used to run various commands during the pre-commit phase. This is where you normally want most CI/CD like checks.”

Installation

Global installation (recommended):

Terminal window
pip install --user pre-commit

Or use pipx:

Terminal window
pipx install pre-commit

Configuration

Create .pre-commit-config.yaml in your repository root:

repos:
  - repo: local
    hooks:
      - id: mermaid-validate
        name: Validate Mermaid Diagrams
        entry: mermaid-validate validate-md
        language: node
        files: \.md$
        additional_dependencies: ['mermaid-validate']

Install Git Hook

Terminal window
pre-commit install

Run Manually

Terminal window
pre-commit run --all-files

Validation Strategies

1. Staged Files Only (Local Development)

Fast validation - Only check files staged for commit:

repos:
  - repo: local
    hooks:
      - id: mermaid-validate-staged
        name: Validate Mermaid in Staged Files
        entry: mermaid-validate validate-md
        language: node
        files: \.md$
        pass_filenames: true

Performance: With fast validators like @ai-of-mine/fast-mermaid-validator-mcp, validation adds virtually no overhead (1-2ms per diagram).

2. All Files (CI/CD)

Comprehensive validation - Check entire codebase:

Terminal window
mermaid-validate validate-md docs/**/*.md

3. Modified Files (Pull Requests)

Targeted validation - Check only files changed in PR:

Terminal window
git diff --name-only origin/main...HEAD | grep '\.md$' | xargs mermaid-validate validate-md

GitHub Actions Integration

Basic Workflow

Create .github/workflows/mermaid-validation.yml:

name: Validate Mermaid Diagrams


on:
  pull_request:
    paths:
      - '**.md'
  push:
    branches:
      - main


jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4


      - uses: actions/setup-node@v4
        with:
          node-version: '20'


      - name: Install mermaid-validate
        run: npm install -g mermaid-validate


      - name: Validate Mermaid diagrams
        run: mermaid-validate validate-md docs/**/*.md

Advanced: Render Diagrams as Artifacts

name: Validate and Render Mermaid


on:
  pull_request:
    paths:
      - '**.md'


jobs:
  validate-and-render:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4


      - uses: actions/setup-node@v4
        with:
          node-version: '20'


      - name: Install Mermaid CLI
        run: npm install -g @mermaid-js/mermaid-cli


      - name: Validate and render diagrams
        run: |
          find docs -name "*.md" -exec sh -c '
            mmdc -i {} -o {}.svg 2>&1 | tee validation.log
          ' \;


      - name: Upload rendered diagrams
        uses: actions/upload-artifact@v4
        with:
          name: mermaid-diagrams
          path: docs/**/*.svg


      - name: Check for validation errors
        run: |
          if grep -q "Error" validation.log; then
            echo "Mermaid validation failed"
            exit 1
          fi

GitLab CI Integration

Create .gitlab-ci.yml:

stages:
  - validate


mermaid-validation:
  stage: validate
  image: node:20
  before_script:
    - npm install -g mermaid-validate
  script:
    - mermaid-validate validate-md docs/**/*.md
  only:
    changes:
      - "**/*.md"
  allow_failure: false

High-Performance Validation

@ai-of-mine/fast-mermaid-validator-mcp

Reference: Automatically fix AI Generated Mermaid Diagrams

This high-performance validator provides:

  • 1-2ms latency per diagram (vs. 100-500ms for traditional mmdc approach)
  • Real grammar parsing using Jison, ANTLR, and Langium
  • 28 diagram types supported
  • REST and MCP interfaces

Pre-commit Hook Configuration

repos:
  - repo: local
    hooks:
      - id: fast-mermaid-validate
        name: Fast Mermaid Validation
        entry: npx @ai-of-mine/fast-mermaid-validator-mcp validate
        language: node
        files: \.md$
        pass_filenames: true

Why Performance Matters

“A pre-commit hook can validate only the files you staged before each commit, saving time during local development. Because the fast validator returns results in 1-2 milliseconds per diagram, it adds virtually no overhead.”

Comparison

| Validator | Latency per Diagram | Approach | CI/CD Ready | |-----------|--------------------|---------| | | mmdc (official) | 100-500ms | Puppeteer rendering | ⚠️ Slow for large repos | | mermaid-validate | 50-200ms | Node.js parsing | ✅ Good | | fast-mermaid-validator-mcp | 1-2ms | Real grammar parsing | ✅ Excellent | | Mermaider | 10-50ms | Puppeteer (persistent browser) | ✅ Good |

Best Practices

1. Fail Fast in CI/CD

Catch errors early in the pipeline:

stages:
  - validate
  - test
  - build
  - deploy


# Validation runs first - blocks pipeline on failure

2. Different Configs for Local vs. CI

Local: Validate only staged files for speed CI/CD: Validate entire codebase for completeness

3. Cache Dependencies

Speed up CI runs by caching npm packages:

cache:
  paths:
    - node_modules/
  key:
    files:
      - package-lock.json

4. Provide Clear Error Messages

When validation fails, show:

  • Which file contains the error
  • Line number (if available)
  • Specific syntax issue
  • Suggested fix

5. Auto-fix When Possible

Reference: cloud-on-prem/mermaid-validator

Some tools include auto-fix capabilities:

  • Normalize whitespace
  • Fix common syntax patterns
  • Correct registry URLs

Automated Diagram Generation

mermaid-gen

GitHub: lukesdm/mermaid-gen

Automated mermaid diagram generation for GitHub documentation using git hooks.

Warning: Syntax errors can cause the pre-commit hook to hang. Always validate before committing.

Safe Auto-generation Pattern

  1. Generate diagrams in separate step
  2. Validate generated diagrams
  3. Only commit if validation passes
Terminal window
# Generate diagrams
mermaid-gen generate


# Validate before committing
mermaid-validate validate-md docs/**/*.md && git add docs/

Environment-Specific Configuration

Developer Environment

# .pre-commit-config.yaml (local)
repos:
  - repo: local
    hooks:
      - id: mermaid-fast-check
        name: Quick Mermaid Check
        entry: fast-mermaid-validator
        language: node
        files: \.md$
        stages: [commit]

CI/CD Environment

# .pre-commit-config.yaml (CI)
repos:
  - repo: local
    hooks:
      - id: mermaid-full-validation
        name: Comprehensive Mermaid Validation
        entry: mermaid-validate validate-md
        language: node
        files: \.md$
        pass_filenames: false
        always_run: true

“The pre-commit configuration in the developers environment will/should be different than the one run in CI/CD.”

Handling Validation Failures

Graceful Degradation

mermaid-validation:
  stage: validate
  script:
    - mermaid-validate validate-md docs/**/*.md || echo "Validation warnings detected"
  allow_failure: true  # Warn but don't block pipeline

Block on Critical Errors Only

Terminal window
# Distinguish warnings from errors
mermaid-validate validate-md docs/**/*.md 2>&1 | tee validation.log


if grep -q "CRITICAL" validation.log; then
  echo "Critical validation errors detected"
  exit 1
fi

Example: Complete Setup

Repository Structure

project/
├── .pre-commit-config.yaml
├── .github/
│   └── workflows/
│       └── mermaid-validation.yml
├── docs/
│   └── architecture.md
└── package.json

.pre-commit-config.yaml

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer


  - repo: local
    hooks:
      - id: mermaid-validate
        name: Validate Mermaid Diagrams
        entry: npx mermaid-validate validate-md
        language: node
        files: \.md$
        pass_filenames: true
        additional_dependencies: ['mermaid-validate']

GitHub Actions Workflow

name: Documentation Validation


on:
  pull_request:
    paths:
      - 'docs/**.md'
  push:
    branches:
      - main


jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4


      - uses: actions/setup-node@v4
        with:
          node-version: '20'


      - name: Install validators
        run: npm install -g mermaid-validate


      - name: Run validation
        run: mermaid-validate validate-md docs/**/*.md

Troubleshooting

Pre-commit Hook Not Running

Terminal window
# Reinstall hook
pre-commit uninstall
pre-commit install


# Test manually
pre-commit run --all-files

Validation Timeout in CI

Increase timeout for large repositories:

timeout-minutes: 10

False Positives

Use .mermaidignore to exclude files:

# Ignore generated files
build/
dist/
*.generated.md

Sources

  1. GitHub - cloud-on-prem/mermaid-validator
  2. Automatically fix AI Generated Mermaid Diagrams
  3. GitHub - lukesdm/mermaid-gen
  4. Implementing Quality Checks In Your Git Workflow
  5. pre-commit hooks
  6. pre-commit - to be continuous