Skip to content

mermaidjs-lint

Package Index Published Version Downloads Node CI Docs License
npm npm npm Downloads Node CI Docs License

I hate walls of text. I do love a good diagram though. mermaidjs is brilliant for separating the semantic structure of a diagram from the pixel pushing.

AI Agents love this separation too. And yet AI Agents kind of suck at diagrams though. So here is a linting and autofixer engine built on top of:

Get started Browse the rules

Lint your docs with one command

Run these in a project that has a package.json, then name your own markdown files and folders.

bun add --dev @jpeakai/mermaidjs-lint
bunx @jpeakai/mermaidjs-lint docs/
bunx @jpeakai/mermaidjs-lint --fix docs/

npm install --save-dev @jpeakai/mermaidjs-lint
npx -y @jpeakai/mermaidjs-lint docs/
npx -y @jpeakai/mermaidjs-lint --fix docs/

docs/architecture.md:6 contrast-text-below-aa classDef warn: text 1.43:1 < 4.5 (#ffffff on #ffd400)
docs/login.md:3-7 parse-diagram-unparseable sequenceDiagram did not parse (parser: mermaid-core) (its line numbers count within the diagram, not the file): Parse error on line 3: Expecting 'TXT', got 'NEWLINE'
docs/pipeline.md:3-41 complexity-node-count-acceptable-exceeded 37 nodes > 35 acceptable threshold
3 finding(s) in 3 file(s)

The run exits 1 while any finding remains, so it works as a CI gate.

Get started to begin from an empty folder through a fully worked example.

Fix unreadable label text and unclosed fences

Add --fix to apply the fixes that pass verification:

Before

flowchart LR A --> B classDef warn fill:#ffff00,color:#fefefe class A warn
docs/flow.md:4 contrast-text-below-aa classDef warn: text 1.06:1 < 4.5 (#fefefe on #ffff00)

After --fix

flowchart LR A --> B classDef warn fill:#ffff00,color:#000000 class A warn
0 finding(s) in 1 file(s)

A fix is kept only if the markdown around the diagrams is unchanged and each diagram reparses with the same node ids, subgraphs and counts. Edge endpoints, edge labels and node text are not compared, so review the diff.

Four tenets

  • Always readable in light mode or dark mode. Declared fills, label colours and borders are scored as the host draws them, on nodes, erDiagram rows, edge labels and sequence diagrams, in both themes.
  • It actually renders a valid diagram. Every diagram parses with the mermaid parsers this package ships, and every mermaid fence is closed.
  • Visual Complexity stays readable. Node count and visual complexity are scored against a density preset, so an oversized diagram is flagged to be split.
  • Make your own rules. A plugin adds rules of your own, which run through the same config, fix engine and verification as the built-ins.

The contrast, parse and complexity rules deliver the first three, and the plugin model delivers the fourth. Concepts states the limit of each.

Go further in the docs site

  • Get started

    Lint a file, read a finding, fix it, and add the check to your project.

  • Guides

    Gate CI, configure the rules, lint a MkDocs site, and write rules of your own.

  • Concepts

    How a run works, how plugins load, and why contrast and complexity are measured the way they are.

  • Reference

    Every rule, flag, config key, and the types a rule receives.

Runs on Bun or Node

It needs Bun, or Node >=20. The package installs mermaid 11.17.2 to parse diagrams, and your host may draw with another version.

Which version these pages describe

This site is published with each release, so it describes the latest release on npm. A change on main that is not yet released is listed under Unreleased in the changelog. mermaidjs-lint --version prints the version you run.

Contribute

CONTRIBUTING.md covers setup. Licensed under MIT.

What it does not do

  • It does not draw diagrams. "Renders" means the mermaid parsers this package ships accept the diagram, so a diagram that parses but draws badly is not caught.
  • It does not know your host's mermaid version. A host on an older mermaid may fail to draw a diagram type that parses here.
  • It does not score unstyled nodes or theme settings outside a sequence diagram. A sequenceDiagram is scored by its resolved theme colours. Elsewhere only the colours a diagram declares are scored, and Contrast profiles lists what is left out.
  • It does not see a diagram inside another fence. A mermaid fence after an unclosed fence of another language is read as that fence's code.
  • It has no per-diagram suppression. A rule is on for every diagram or off for all of them, and Troubleshooting gives the workarounds.
  • It does not split diagrams. A complexity finding names the subgraphs to split along, and a human or an LLM decides. The fixture gallery shows what an LLM would do.
  • It does not choose colours. A contrast fix only swaps a declared label colour for black or white, and only when that passes every background it is scored on.
  • It has no warnings. Every finding fails the run, and a rule you do not want is switched off in the config.

Project

Topic Where
Report a bug or ask a question GitHub issues, with the output of mermaidjs-lint --version
Report a vulnerability, and the plugin trust model SECURITY.md
What counts as a breaking change Versioning
What changed in each release, and what is not yet released CHANGELOG.md
Lint and fix diagrams from an AI coding agent The agent skill, copied into .claude/skills/mermaidjs-lint/SKILL.md, and its evals