Mermaid Diagram Linter

Validate Mermaid diagrams in markdown files for syntax errors, text overflow issues, and configuration requirements.

When to Use

Before deploying documentation sites
When diagrams appear as raw code instead of rendered
To validate diagram text length (prevents overflow)
Part of documentation quality checks

Validation Checks

1. Configuration Validation (mkdocs.yml)

Check that MkDocs is properly configured for enhanced markdown features.

✅ RECOMMENDED: Native Integration (Material for MkDocs)

Per official Material docs, native Mermaid integration requires ONLY the superfences extension:

# Required in mkdocs.yml - Native integration
markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - attr_list          # Required for icon attributes { .lg .middle }
  - md_in_html         # Required for card grids and markdown in HTML

# NO extra_javascript needed - superfences handles it natively!

⚠️ WARNING: Adding extra_javascript CDN can cause conflicts

If you have this in your config, remove it:

extra_javascript:
  - https://unpkg.com/mermaid@10/dist/mermaid.min.js  # ❌ NOT NEEDED

Material for MkDocs handles Mermaid natively. Adding the CDN manually can cause:

Double initialization
Version conflicts
Theme styling issues

Only add extra_javascript if:

Using custom Mermaid configuration (ELK layouts, etc.)
Need specific Mermaid version for compatibility
Using non-Material theme

If custom config is needed, use:

extra_javascript:
  - javascripts/mermaid-config.js  # Your custom config

With javascripts/mermaid-config.js:

import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: false, securityLevel: 'loose' });

Common Configuration Issues:

Missing Extension	Symptom	Fix
`custom_fences`	Mermaid renders as code blocks	Add superfences custom_fences
`pymdownx.emoji`	`:rocket:` shows as text	Add emoji extension
`attr_list`	Icon attributes not working	Add attr_list
`md_in_html`	Card grids show as raw text	Add md_in_html

Material for MkDocs Card Grids:

Card grids require BOTH attr_list AND md_in_html:

<div class="grid cards" markdown>

-   :material-rocket:{ .lg .middle } **Title**

    Description text

</div>

Without md_in_html, the markdown inside <div> tags won't be processed!

2. CSS Validation

Check for Mermaid overflow CSS in stylesheets:

/* Required for proper rendering */
.mermaid {
  overflow-x: auto;
  text-align: center;
}

.mermaid svg {
  max-width: 100%;
  height: auto;
}

.mermaid .nodeLabel {
  font-size: 12px !important;
}

3. Syntax Validation

Per official Mermaid docs, check each diagram for valid syntax:

Diagram Types:

Fully supported by Material theme: flowchart, sequenceDiagram, classDiagram, stateDiagram, erDiagram
Work but no theme styling: graph, gantt, pie, journey, gitGraph, mindmap, quadrantChart

Direction Keywords:

TB or TD - Top to bottom (recommended for mobile)
BT - Bottom to top
LR - Left to right (simple linear flows only)
RL - Right to left

Critical Syntax Rules:

Reserved "end" keyword - Must capitalize to avoid breaking diagram:

flowchart TD
    A[Start] --> B[End]      ✅ Capitalized "End"
    A[Start] --> B[end]      ❌ BREAKS diagram

First letter 'o' or 'x' - Add space or capitalize:

flowchart LR
    A --> oNode    ❌ Treated as circle edge
    A --> O_Node   ✅ Capitalize or use underscore

Prefer flowchart over graph - Both work identically, but flowchart is clearer intent

All nodes must be connected - Orphaned nodes cause syntax errors:

flowchart TD
    A --> B
    C[Orphan]      ❌ Not connected to anything

4. Text Formatting Best Practices

Per official Mermaid docs, use automatic text wrapping instead of manual line breaks.

❌ AVOID: Manual <br/> tags

flowchart TD
    A[Getting Started<br/>7 steps]    ❌ Manual breaks
    B[Intermediate<br/>11 steps]

✅ RECOMMENDED: Markdown strings with automatic wrapping

flowchart TD
    A["`**Getting Started**
    7 steps · 10 minutes
    Essential commands`"]           ✅ Auto-wraps, supports markdown

Markdown string syntax (backticks with quotes):

Supports bold, italic, code
Automatic text wrapping at node width
More maintainable than <br/> tags
Better mobile responsiveness

Text Length Guidelines:

Element	Max Length	Recommendation
Node text (single line)	15-20 chars	Use abbreviations, `...` for paths
Edge labels	10 chars	Keep brief
Subgraph titles	20 chars	Short descriptive names

Examples:

%% BAD: Text too long, will overflow
graph LR
    A["~/.git-worktrees/aiterm/feature-mcp/"] --> B

%% GOOD: Abbreviated with markdown string
flowchart LR
    A["`**Worktrees**
    ~/.git-worktrees/
    .../feature-mcp`"] --> B["`Next Step`"]

5. Layout Direction Best Practices

Prefer vertical layouts (TD/TB) over horizontal (LR/RL) for complex diagrams:

Layout	Best For	Avoid For
`flowchart TD`	Complex workflows, decision trees, multi-branch flows	-
`flowchart LR`	Simple linear flows (< 5 nodes), system architecture	Complex workflows, parallel processes

Why vertical layouts render better:

Better spacing on mobile/narrow screens
Reduced text overlap in decision diamonds
Clearer visualization of parallel processes using subgraphs
More readable for ADHD-friendly documentation

Examples:

%% BAD: Horizontal complex diagram
flowchart LR
    A --> B --> C --> D
    B --> E
    C --> F
    D --> G
    E --> G
    F --> G

%% GOOD: Vertical complex diagram
flowchart TD
    A --> B --> C --> D
    B --> E
    C --> F
    D --> G
    E --> G
    F --> G

When to use subgraphs (always with TD):

Parallel worktree workflows
Multi-path decision flows
Feature development pipelines

6. Diagram Count Report

Report all mermaid diagrams found:

Total count per file
Diagram types used
Files with most diagrams
Diagrams using <br/> tags (flag for modernization)

Validation Commands

# Check all docs
grep -r "^\`\`\`mermaid" docs/ | wc -l

# Find diagrams using <br/> tags (should use markdown strings instead)
grep -r "<br/>" docs/**/*.md | grep -B5 mermaid

# Find long node text (> 20 chars between quotes)
grep -E '\["[^"]{20,}"\]' docs/**/*.md

# Check for custom_fences config
grep -A5 "superfences" mkdocs.yml | grep -q "custom_fences"

# Check for unnecessary extra_javascript (native integration doesn't need it)
grep -A3 "extra_javascript" mkdocs.yml | grep -q "mermaid"

# Find diagrams using deprecated 'graph' keyword
grep -A1 "^\`\`\`mermaid" docs/**/*.md | grep -c "^graph "

Output Format

MERMAID DIAGRAM VALIDATION
==========================

Configuration:
  ✅ custom_fences configured in mkdocs.yml
  ✅ mermaid.js CDN in extra_javascript
  ⚠️  No Mermaid CSS found in stylesheets

Diagrams Found: 15 total
  docs/guides/GIT-WORKTREES-GUIDE.md: 12 diagrams
  docs/architecture/AITERM-ARCHITECTURE.md: 3 diagrams

Syntax Validation:
  ✅ All 15 diagrams have valid syntax

Text Length Issues:
  ⚠️  docs/guides/GIT-WORKTREES-GUIDE.md:156
      Node text "~/.git-worktrees/aiterm/feature-mcp/" is 38 chars (max 15)
      Suggestion: Use "~/.git-worktrees/.../feature-mcp"

Summary:
  Passed: 14/15
  Warnings: 1 (text length)
  Errors: 0 (syntax)
  Config: 2/3 (missing CSS)

Recommendations:
  1. Add Mermaid CSS to docs/stylesheets/extra.css
  2. Shorten node text in GIT-WORKTREES-GUIDE.md line 156

Integration

Called by:

/craft:site:status --check - Site health check
/craft:docs:validate - Documentation validation
/craft:check commit - Pre-commit checks

Related:

/craft:site:status - Quick Mermaid config check
/craft:docs:generate - Includes Mermaid guidelines

Best Practices

Per official Mermaid documentation and Material for MkDocs:

Use native integration - Let Material handle Mermaid, don't add extra_javascript unless needed
Markdown strings over <br/> - Use backtick syntax for multi-line text with auto-wrapping
Prefer flowchart keyword - Clearer intent than graph (both work identically)
Vertical layouts (TD) - Better mobile rendering, reduced text overlap
Capitalize "end" keyword - Use "End" or "END" to avoid breaking diagrams
Connect all nodes - Orphaned nodes cause syntax errors
Test locally - Run mkdocs serve to preview diagrams before deployment
Use subgraphs - Group related nodes for clarity and structure
Consistent diagram types - Stick to one type per document (flowchart, sequence, etc.)
Add comments - Use %% for documentation within diagrams
Keep it simple - Avoid over-engineering, Swedish "lagom" principle applies

Common Issues

Issue	Cause	Fix
Diagrams show as code	Missing custom_fences	Add superfences to mkdocs.yml
Diagram broken ("end" keyword)	Used lowercase "end"	Capitalize to "End" or "END"
Orphaned node error	Node not connected	Connect with arrow or remove
Text overflows boxes	Using `<br/>` tags	Switch to markdown strings with backticks
Double rendering	Extra_javascript + native	Remove extra_javascript, use native integration
Poor mobile rendering	Horizontal (LR) layout	Switch to vertical (TD) layout
Theme colors not applied	Using unsupported diagram type	Use flowchart/sequence/class/state/ER only
Syntax error on 'o' or 'x'	First letter treated as edge	Capitalize or add space before name

Mermaid Diagram Linter

Mermaid Diagram Linter

When to Use

Validation Checks

1. Configuration Validation (mkdocs.yml)

2. CSS Validation

3. Syntax Validation

4. Text Formatting Best Practices

5. Layout Direction Best Practices

6. Diagram Count Report

Validation Commands

Output Format

Integration

Best Practices

Common Issues

Similar Skills