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:

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:

1. •

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

   mermaid

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

2. •

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

   mermaid

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

3. •

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

4. •

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

   mermaid

   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:

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:

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:

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

Common Issues