mermaidjs-lint

| Docs | Rules | Changelog | npm |

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

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:

• mermaid parsing libraries
• colorjs.io for official WCAG 2.1 colour contrast readability scoring.

Lint your docs with one command

# bunx
bunx @jpeakai/mermaidjs-lint docs/
bunx @jpeakai/mermaidjs-lint --fix docs/

# npx
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.

Fix unreadable label text and unclosed fences

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

-  classDef warn fill:#ffd400,color:#ffffff
+  classDef warn fill:#ffd400,color:#000000

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.

Go further in the docs site

• Get started: run it, fix a diagram, and add the gate to your project.
• Use it in CI or before each commit.
• Configure the rules
• Write a project local rule.

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.

Contribute

CONTRIBUTING.md covers setup. Licensed under MIT.