Validate Mermaid diagrams in CI before documentation ships

Check Mermaid files and Markdown diagrams in CI with Flowgraph's CLI. Report syntax failures while keeping quotas, secrets, and fork behavior explicit.

Updated November 19, 2026 · 2 min read

A broken diagram often reaches documentation because nobody opens that page during code review. A CI validation step can catch Mermaid that no longer renders before the documentation is released.

Validation proves that the renderer accepts the source. It does not prove that the architecture, cardinality, or business process is correct. Keep semantic review alongside the automated check.

Start with a local check

Create an API key in Flowgraph Studio under Account settings → Render API (a free account works), set it as FLOWGRAPH_API_KEY, and run:

npx flowgraph-cli check docs

flowgraph-cli is a small MIT-licensed package with no dependencies; it needs Node 20 or later. It reads .mmd and .mermaid files and every Mermaid block in Markdown files under the folders you name, and prints each failing file with the line of the error. Exit code 0 means every diagram passed, 1 means one or more failed, and 2 means a usage or setup error, such as a missing key.

You can also pass a quoted glob, such as "docs/**/*.md"; globs need Node 22 or later. npx flowgraph-cli render docs --out-dir build/diagrams --theme theme.json writes the images as well.

Add a workflow

Pin the CLI version in CI so a new release can't change the check under you.

name: Check diagrams
on: [push, pull_request]
permissions:
  contents: read
jobs:
  diagrams:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          package-manager-cache: false
      - run: npx --yes flowgraph-cli@0.1.1 check docs --concurrency 2
        env:
          FLOWGRAPH_API_KEY: ${{ secrets.FLOWGRAPH_API_KEY }}

The action references follow the current setup-node examples; check them again when adopting the workflow. If you'd rather not install anything, the render API guide for CI does the same check with curl against /v1/validate.

Plan for secrets and quotas

Store the API key in repository or organization secrets. Pull requests from forks may not receive those secrets. Define whether such checks run later in a trusted context or use another validation path; do not expose a key to untrusted code to make the check pass.

Each diagram that passes uses one render from the monthly allowance (50 on Free, 5,000 on Pro, 20,000 on Pro Max); diagrams that fail aren't counted. Rechecking a large documentation tree on every commit can use a Free allowance quickly. Run the check only when Markdown or .mmd files change (a paths filter on the workflow trigger), or schedule a full check, and keep concurrency low: each key can send 30 requests a minute.

Make failure actionable

Keep CLI output in the job log and ask reviewers to fix the named source file. A green check should complement a readable preview, not replace it. Use the flowchart cheat sheet for common syntax fixes and the API reference for limits and responses.

More guides