DEV Community

Glen Baker
Glen Baker

Posted on • Originally published at entropicdrift.com

Mermaid-Sonar: Detecting Hidden Complexity in Diagram Documentation

#mermaid #documentation #complexity #readability

Originally published on Entropic Drift

The Problem with AI-Generated Diagrams

When building the MkDocs automation workflow for ripgrep, I ran into a consistent problem: diagrams could be syntactically incorrect or cognitively overwhelming and actually hurt comprehension rather than helping it. There could also be semantic and business logic issues with the diagrams, but we'll set that issue aside for this post.

I needed a way to give AI agents quantitative feedback about diagram complexity. Telling Claude "this diagram is too complex" doesn't work reliably and required manual direction from me. We need better tooling to determine when a given mermaid diagram would actually be readable and how to generally fix it if it isn't.

Traditional Mermaid validation tools only check syntax. They'll tell you if your diagram will render, but not whether humans can actually understand it. There's @mermaid-js/mermaid-cli for full rendering validation, but it requires a browser and is too slow for CI/CD. There's mermaid.parse() for fast syntax checking, but it provides no insight into readability.

That's why I built mermaid-sonar: a complexity analyzer that validates both syntax and readability using research-backed metrics.

Two Complementary Goals

  1. Complexity analysis:

    • Node count, edge count, graph density
    • Cyclomatic complexity, branching width
    • Requires: Static analysis of graph structure
    • No alternative: Can't extract these metrics from rendered output

  2. Dimension validation:

    • Will this diagram fit in the target viewport?
    • Does it exceed platform width constraints?
    • Options: Render in headless browser OR estimate from graph structure

Dimension Validation

For dimension validation, I had two options:

Option 1: Render diagrams (like @mermaid-js/mermaid-cli):

  • Pixel-perfect accuracy
  • Requires headless browser (heavy dependency)
  • Slow (seconds per diagram)
  • Doesn't work well in CI/CD pipelines
  • Adds complexity to tool requiring browser environment

Option 2: Estimate dimensions (layout-aware formulas):

  • Fast (milliseconds per diagram)
  • No additional dependencies (already parsing for complexity)
  • Perfect for CI/CD automation
  • Good enough accuracy for detecting viewport issues
  • Not pixel-perfect (but doesn't need to be)

I chose dimension estimation because:

  • We're already parsing the diagram for complexity metrics
  • Speed matters for validating 87+ diagrams in a workflow
  • We don't need pixel-perfect accuracy—we need to catch diagrams that will obviously exceed viewport limits
  • A diagram with 1302px estimated width on an 800px viewport is clearly a problem, whether the actual width is 1250px or 1350px

Why dimension validation matters: When a diagram exceeds viewport width, browsers and documentation frameworks shrink it to fit. A 1302px diagram forced into an 800px viewport gets scaled down to ~61% of its original size, making text and labels proportionally smaller and often unreadable. A diagram that's 63% oversized becomes a diagram with text that's 39% smaller than intended—turning readable labels into tiny, illegible text.

Here's an actual 1302px-wide diagram rendered in this blog post, which has an ~800px content width:

graph TD
    Root["Software Development
Lifecycle"] --> Plan["Planning & Design
Requirements"]
    Root --> Dev["Development
Implementation"]
    Root --> Test["Testing & QA
Quality Assurance"]
    Root --> Deploy["Deployment
Release Management"]
    Root --> Monitor["Monitoring
Observability"]
    Root --> Maintain["Maintenance
Bug Fixes"]
    Root --> Doc["Documentation
User Guides"]
    Root --> Security["Security
Vulnerability Mgmt"]
Enter fullscreen mode Exit fullscreen mode

Notice how the text becomes harder to read as the diagram is automatically shrunk to fit the viewport? This is why dimension validation matters—even technically correct diagrams become unreadable when they exceed viewport constraints.

How Dimension Estimation Works

Since we're already parsing diagrams for complexity analysis, we can estimate dimensions using layout-aware formulas:

  1. Label extraction: Parse node labels from the diagram source (handling multi-line labels by measuring the longest line)
  2. Layout direction: Detect whether the diagram uses TD (top-down), LR (left-right), or other layouts
  3. Graph structure: For LR/RL layouts, calculate the longest path through the graph accounting for branches and merges
  4. Width estimation formula:
    • LR/RL layouts: width = longestPath × avgLabelLength × charWidth + longestPath × nodeSpacing
    • TD/TB layouts: width = maxBranchWidth × avgLabelLength × charWidth + maxBranchWidth × nodeSpacing

Where charWidth defaults to 8px (typical monospace character width) and nodeSpacing defaults to 50px (Mermaid's default spacing).

This provides accurate-enough width estimates for catching viewport issues, without requiring browser rendering.

What Mermaid-Sonar Does

Mermaid-sonar analyzes Mermaid diagrams in your documentation and detects:

  1. Syntax errors - Using the official Mermaid parser (prevents build failures)
  2. Excessive complexity - Too many nodes, edges, or branching (hurts comprehension)
  3. Poor layout choices - TD layout for wide trees, LR for deep hierarchies (reduces readability)
  4. Performance issues - Graphs approaching Mermaid's O(n²) rendering limits (slow page loads)
  5. Viewport compatibility - Diagrams that exceed target platform dimensions (e.g., MkDocs 800px width limit)

Finding the Right Thresholds: Research-Backed Limits

The hardest part of building mermaid-sonar wasn't the implementation—it was figuring out what "too complex" actually means. I didn't want arbitrary limits; I needed defensible thresholds based on research.

Cognitive Load Research

The breakthrough came from finding "Scalability of Network Visualisation from a Cognitive Load Perspective" (Kwon et al., 2020). This paper studied how humans process graph visualizations and found:

  • High-density graphs (>0.3 density): 50-node limit before cognitive overload
  • Low-density graphs (<0.3 density): 100-node limit for comprehension
  • Density matters more than raw node count for readability

This gave me the foundation for the max-nodes rule with density-aware thresholds.

Performance Constraints

Mermaid's official blog post "Flow Charts are O(n²) Complex" provided clear guidance on rendering performance:

  • 100 connections is the practical limit before rendering slows significantly
  • Layout algorithms scale quadratically with edges
  • Performance degrades sharply beyond this threshold

This directly informed the max-edges rule.

Visual Hierarchy Research

Studies on visual hierarchy and information design consistently show:

  • 7±2 items is the working memory limit (Miller's Law)
  • 8 parallel branches as a reasonable limit for tree diagrams
  • Beyond this, readers lose track of structure

This shaped the max-branch-width rule.

Software Engineering Standards

McCabe's cyclomatic complexity metric (originally for code) translates well to diagrams:

  • Complexity = edges - nodes + 2 for connected graphs
  • 15 is the standard threshold for "too complex" in code
  • Same principle applies to decision paths in diagrams

This gave me the cyclomatic-complexity rule.

How It Works: From Source to Metrics

Mermaid-sonar follows a simple pipeline:

1. Parse Diagram Source 

// Use official Mermaid parser
const diagram = mermaid.parse(diagramSource);
Enter fullscreen mode Exit fullscreen mode

The parser builds an AST (abstract syntax tree) representing the diagram structure.

2. Extract Graph Metrics 

const metrics = {
  nodeCount: countNodes(diagram),
  edgeCount: countEdges(diagram),
  graphDensity: edgeCount / (nodeCount * (nodeCount - 1)),
  maxBranchWidth: findMaxBranchWidth(diagram),
  averageDegree: (2 * edgeCount) / nodeCount,
  cyclomaticComplexity: edgeCount - nodeCount + 2
};
Enter fullscreen mode Exit fullscreen mode

3. Apply Research-Backed Rules 

if (nodeCount > (density > 0.3 ? 50 : 100)) {
  issues.push({
    rule: 'max-nodes',
    severity: 'error',
    message: `Complex diagram with ${nodeCount} nodes`,
    suggestion: 'Consider breaking into focused sub-diagrams',
    citation: 'https://arxiv.org/abs/2008.07944'
  });
}
Enter fullscreen mode Exit fullscreen mode

4. Provide Actionable Feedback 

❌ docs/architecture.md:42
   Wide tree diagram with 12 parallel branches (>8 max)
   → Consider using 'graph LR' or split into multiple diagrams

⚠️ docs/workflow.md:156
   Complex diagram with 85 nodes
   → Consider breaking into focused sub-diagrams

✓ docs/overview.md:15 - Valid and readable
Enter fullscreen mode Exit fullscreen mode

Each issue includes the specific problem, concrete fix suggestion, and link to supporting research when applicable.

Real-World Results: ripgrep Documentation

When I ran mermaid-sonar on the AI-generated ripgrep documentation (55 pages, 87 diagrams), the results validated the entire approach:

Syntax Errors Found: 8 diagrams (9% failure rate)

  • Missing arrows in flowcharts
  • Invalid node ID references
  • Malformed subgraph syntax
  • Quote escaping issues

These would have caused build failures. Without mermaid-sonar, I'd have discovered them during manual testing or—worse—in CI after pushing.

Complexity Issues Found: 12 diagrams (14% complexity rate)

  • 4 diagrams with >50 nodes (simplified to <30 each)
  • 3 wide tree diagrams (converted from TD to LR layout)
  • 5 overly dense graphs (split into focused sub-diagrams)

These rendered correctly but were cognitively expensive. Without mermaid-sonar, readers would struggle through overwhelming visualizations.

The Key Insight: 23% of AI-generated diagrams (20 out of 87) had issues that no existing tool would catch automatically. Manual review would take hours; mermaid-sonar caught everything in seconds.

Example: The 85-Node Architecture Diagram

One diagram stood out: an 85-node "Architecture Overview" that tried to show every component relationship in a single graph. Technically valid, but completely unreadable at typical markdown rendering sizes.

Mermaid-sonar output:

❌ docs/architecture.md:42
   Complex diagram with 85 nodes (limit: 50 for high-density graphs)
   Graph density: 0.38 (high-density threshold: 0.3)
   → Consider breaking into focused sub-diagrams
   Research: https://arxiv.org/abs/2008.07944
Enter fullscreen mode Exit fullscreen mode

The fix: Split into three focused diagrams:

  1. Core components (18 nodes) - The main execution pipeline
  2. Plugin system (22 nodes) - Extension mechanisms
  3. Configuration flow (15 nodes) - How settings propagate

Each diagram now tells a clear story instead of overwhelming readers with everything at once.

Visualization: Before and After Examples

Let's look at specific examples showing how mermaid-sonar's feedback improves diagram readability. These are actual fixes from the ripgrep documentation.

Example 1: Converting Wide Trees (TD → LR Layout)

Problem: Wide tree diagrams with many parallel branches in TD (top-down) layout create excessive horizontal width. With 8 parallel branches, this exceeds viewport limits by 63%.

Before (failed validation):

❌ ERROR: Diagram width (1302px) exceeds viewport limit by 502px (63% over)
   This TD layout with 8 parallel branches creates excessive width
Enter fullscreen mode Exit fullscreen mode 
graph TD
    Root["Software Development
Lifecycle"] --> Plan["Planning & Design
Requirements"]
    Root --> Dev["Development
Implementation"]
    Root --> Test["Testing & QA
Quality Assurance"]
    Root --> Deploy["Deployment
Release Management"]
    Root --> Monitor["Monitoring
Observability"]
    Root --> Maintain["Maintenance
Bug Fixes"]
    Root --> Doc["Documentation
User Guides"]
    Root --> Security["Security
Vulnerability Mgmt"]
Enter fullscreen mode Exit fullscreen mode

After (passes validation):

✓ LR layout stacks vertically, width under 400px
✓ No issues found
Enter fullscreen mode Exit fullscreen mode 
graph LR
    Root["Software Development
Lifecycle"] --> Plan["Planning & Design
Requirements"]
    Root --> Dev["Development
Implementation"]
    Root --> Test["Testing & QA
Quality Assurance"]
    Root --> Deploy["Deployment
Release Management"]
    Root --> Monitor["Monitoring
Observability"]
    Root --> Maintain["Maintenance
Bug Fixes"]
    Root --> Doc["Documentation
User Guides"]
    Root --> Security["Security
Vulnerability Mgmt"]
Enter fullscreen mode Exit fullscreen mode

Fix: Changed graph TD to graph LR. Wide trees with many parallel branches work better in LR layout, which stacks branches vertically for natural scrolling instead of forcing horizontal width.

Width improvement: 1302px → ~400px (69% reduction)

Example 2: Split into Sequential Phases (712px → 400px per diagram)

Problem: Wide tree diagrams with many parallel branches create excessive horizontal width, even in TD layout.

Before (warning - 4 parallel branches):

⚠️  Diagram width (712px) due to 4+ parallel branches
Enter fullscreen mode Exit fullscreen mode 
graph TD
    Start[Directory Traversal] --> WorkQueue["Work Queue
Files to Search"]
    WorkQueue --> T1[Thread 1]
    WorkQueue --> T2[Thread 2]
    WorkQueue --> T3[Thread 3]
    WorkQueue --> TN[Thread N]

    T1 -->|Work Done| Steal1{More Work?}
    T2 -->|Work Done| Steal2{More Work?}
    T3 -->|Work Done| Steal3{More Work?}

    Steal1 -->|Queue Empty| StealFrom2[Steal from Thread 2]
    Steal2 -->|Queue Empty| StealFrom3[Steal from Thread 3]
    Steal3 -->|Queue Empty| StealFrom1[Steal from Thread 1]

    T1 --> Results[Aggregate Results]
    T2 --> Results
    T3 --> Results
    TN --> Results
Enter fullscreen mode Exit fullscreen mode

After (passes validation with zero warnings):

✓ Split into 3 focused diagrams, each ~400px
✓ Zero warnings (perfect validation)
Enter fullscreen mode Exit fullscreen mode

Phase 1: Work Distribution

flowchart LR
    Start[Directory Traversal] --> WorkQueue["Work Queue
Files to Search"]

    WorkQueue --> Workers["Worker Threads
(T1, T2, T3, TN)"]

    style Start fill:#e1f5ff
    style WorkQueue fill:#fff3e0
    style Workers fill:#f3e5f5
Enter fullscreen mode Exit fullscreen mode

Phase 2: Work Processing

flowchart LR
    Workers[Worker Threads] -->|Work Done| CheckWork{More Work?}

    CheckWork -->|Yes| ContinueWork[Process Next]
    CheckWork -->|No| CheckSteal{Queue Empty?}

    CheckSteal -->|Yes| Steal[Work Stealing]
    CheckSteal -->|No| ContinueWork

    style Workers fill:#fff3e0
    style CheckWork fill:#f3e5f5
    style Steal fill:#fff3e0
Enter fullscreen mode Exit fullscreen mode

Phase 3: Result Aggregation

flowchart LR
    Workers[Worker Threads] --> Completed[Work Completed]
    Steal[Work Stealing] --> Workers

    Completed --> Results[Aggregate Results]

    style Workers fill:#fff3e0
    style Results fill:#e8f5e9
Enter fullscreen mode Exit fullscreen mode

Fix: Split complex workflow into 3 focused phases:

  • Each phase has 3-5 nodes (simple and clear)
  • LR layout works perfectly for each sequential phase
  • Natural left-to-right reading flow
  • Zero warnings (no layout hints or width issues)

Tradeoff: Uses more vertical space but each phase is clearer and achieves perfect validation.

Example 3: Simplifying Complex Flows + Split Phases (64 nodes → 13 nodes across 3 diagrams)

Problem: Overly detailed flowchart with 64 nodes showing every decision point. Technically correct but cognitively overwhelming.

Before (failed validation):

❌ Complex diagram with 64 nodes and excessive height (900px)
❌ Cyclomatic complexity: 45 (threshold: 15)
Enter fullscreen mode Exit fullscreen mode 
flowchart TD
    Start([Config Loading Starts]) --> CheckEnv{RIPGREP_CONFIG_PATH
set?}

    CheckEnv -->|No| NoConfig[No config loaded]
    CheckEnv -->|Empty value| NoConfig
    CheckEnv -->|Yes| ReadFile[Attempt to read file]

    ReadFile --> FileExists{File
exists?}

    FileExists -->|No| FileError[Error: File not found]
    FileExists -->|Permission denied| FileError
    FileError --> NoConfig

    FileExists -->|Yes| ParseLines[Parse lines sequentially]

    ParseLines --> CheckLine{Process
each line}

    CheckLine --> IsEmpty{Empty
line?}
    IsEmpty -->|Yes| NextLine[Skip to next line]

    IsEmpty -->|No| IsComment{Starts with
'#'?}
    IsComment -->|Yes| NextLine

    IsComment -->|No| ConvertUTF8{Valid
UTF-8?}

    ConvertUTF8 -->|Yes| AddArg[Add to arguments list]
    AddArg --> NextLine

    ConvertUTF8 -->|No| Platform{Platform?}
    Platform -->|Unix-like| ParseErr[Report parse error
with line number]
    Platform -->|Windows| ParseErr

    ParseErr --> NextLine
    NextLine --> MoreLines{More
lines?}

    MoreLines -->|Yes| CheckLine
    MoreLines -->|No| ReportErrs{Parse errors
occurred?}

    ReportErrs -->|Yes| ShowErrs[Display errors
with line numbers]
    ReportErrs -->|No| Success[Config loaded successfully]

    ShowErrs --> Success
    NoConfig --> End([Continue with CLI args only])
    Success --> End
Enter fullscreen mode Exit fullscreen mode

After (passes validation with zero warnings):

✓ Simplified to 13 nodes across 3 focused phases
✓ Cyclomatic complexity: 8 (well below threshold)
✓ Zero warnings (perfect validation)
Enter fullscreen mode Exit fullscreen mode

Phase 1: Config Discovery and Loading

flowchart LR
    Start([Config Load]) --> Check{Path set?}

    Check -->|No/Empty| NoConfig[No config]
    Check -->|Yes| ReadFile{Readable?}

    ReadFile -->|No| Error[Error]
    ReadFile -->|Yes| Parse[Parse]

    Error --> NoConfig

    style Start fill:#e1f5ff
    style Error fill:#ffebee
    style NoConfig fill:#f5f5f5
Enter fullscreen mode Exit fullscreen mode

Phase 2: Argument Processing

flowchart LR
    Parse[Parse Config] --> Process["Skip empty lines/comments
    Validate UTF-8
    Collect arguments"]

    Process --> Check{Parse errors?}

    Check -->|Yes| Report[Report errors]
    Check -->|No| Success[Args collected]

    style Process fill:#fff3e0
    style Report fill:#ffebee
    style Success fill:#e8f5e9
Enter fullscreen mode Exit fullscreen mode

Phase 3: Finalization

flowchart LR
    Success[Config loaded] --> End([Continue with CLI args])
    NoConfig[No config] --> End
    Report[Errors reported] --> Success

    style Success fill:#e8f5e9
    style NoConfig fill:#f5f5f5
    style End fill:#e8f5e9
Enter fullscreen mode Exit fullscreen mode

Fix: Combined simplification with phase splitting:

  • Reduced 64 nodes → 13 nodes (80% reduction)
  • Split into 3 logical phases with natural boundaries
  • Each phase uses LR layout (3-5 nodes per diagram)
  • Complexity reduced from 45 → 8
  • Zero warnings (no layout hints, no width issues)

Key insight: Sometimes the best fix combines multiple strategies. We simplified the flow AND split it into phases, achieving both comprehensibility and perfect validation. Each phase tells a clear story step-by-step.

Multiple Valid Solutions: Tradeoffs in Practice

Examples 2 and 3 above demonstrate one approach (subgraphs and TD layout), but there's an important insight: multiple valid solutions exist, each with different tradeoffs.

Alternative: Split Diagram Approach

For both Examples 2 and 3, we could achieve zero warnings by splitting into multiple smaller LR diagrams:

Example 2 Alternative - Split work-stealing into 3 phases:

  1. Work Distribution (3 nodes)
  2. Work Processing (5 nodes)
  3. Result Aggregation (3 nodes)

Example 3 Alternative - Split config loading into 3 phases:

  1. Config Discovery (6 nodes)
  2. Argument Processing (5 nodes)
  3. Finalization (3 nodes)

Each smaller diagram passes validation perfectly with LR layout. See the linked files for complete runnable examples.

Choosing Your Approach

Approach Warnings Pros Cons When to Use
Single diagram (subgraph/TD) Layout hints Overview, concise, less vertical space Gets warnings (acceptable) Limited space, need big picture
Split diagrams (multiple LR) Zero Perfect validation, step-by-step clarity More vertical space, loses overview Tutorial-style, plenty of space

Both approaches are valid - the "single diagram with acceptable warnings" is often preferable for its conciseness, while "split diagrams with zero warnings" works better for step-by-step explanations.

See the examples: The mermaid-sonar examples directory includes both approaches for comparison.

Viewport Profiles: Platform-Specific Validation

The examples above use mermaid-sonar's viewport profile feature:

mermaid-sonar --viewport-profile mkdocs docs/
Enter fullscreen mode Exit fullscreen mode

This validates against documentation platform constraints:

  • Max width: 800px (typical content area)
  • Max height: No hard limit (vertical scrolling is natural)
  • Layout-aware estimation: Accounts for node label length and graph structure

Different documentation platforms have different viewport constraints:

  • MkDocs: 800px width (default content column)
  • GitHub: ~1000px width (README rendering)

The --viewport-profile flag ensures diagrams render well on your specific platform without manual width calculations.

Why This Matters for AI Documentation Workflows

The ripgrep documentation project revealed a fundamental insight: AI agents need quantitative feedback to produce quality diagrams.

The Feedback Loop Problem

Without mermaid-sonar:

  1. AI generates 87 diagrams
  2. Some have syntax errors → build fails
  3. Many are overly complex → readers confused
  4. Manual review required for all diagrams → bottleneck
  5. Subjective feedback ("too complex") → AI doesn't improve

With mermaid-sonar:

  1. AI generates 87 diagrams
  2. Mermaid-sonar validates automatically → specific issues found
  3. Quantitative feedback ("85 nodes, limit 50") → AI fixes automatically
  4. Manual review only for diagram type choices → efficient
  5. Clear metrics guide AI toward better outputs

The Broader Documentation Automation Ecosystem

Mermaid-sonar fits into a larger philosophy: automated documentation needs automated quality gates.

In the MkDocs drift automation workflow, I use multiple specialized validators:

  • Mermaid-sonar: Diagram complexity and syntax
  • MkDocs build: Documentation structure and links
  • Markdown linters: Formatting and style
  • Prodigy workflows: Orchestration and feedback loops

Each validator provides quantitative, actionable feedback that AI agents can act on. This is the same philosophy behind Debtmap for Rust code—convert subjective code quality into measurable metrics with clear thresholds.

The key insight: AI agents excel at fixing specific, measurable problems. "This diagram has 85 nodes, simplify to under 50" works. "This diagram feels too busy" doesn't.

Lessons Learned: Building for AI Consumption

Building mermaid-sonar taught me important lessons about designing tools for AI agents:

1. Quantitative Over Qualitative

What doesn't work: "This diagram is too complex"
What works: "This diagram has 85 nodes (limit: 50 for density 0.38)"

AI agents need numbers with clear thresholds. Subjective feedback creates ambiguity; quantitative metrics enable action.

2. Actionable Suggestions

What doesn't work: "Simplify this diagram"
What works: "Split into 3 sub-diagrams or use LR layout for wide trees"

Vague suggestions require creativity; specific actions can be executed mechanically.

3. Research Citations Build Trust

Including research links in error messages serves multiple purposes:

  • Validates the threshold isn't arbitrary
  • Helps humans understand the reasoning
  • Allows AI agents to reference authoritative sources
  • Makes the feedback defensible in code reviews

4. Machine-Readable Output is Critical

JSON output enables automated workflows:

{
  "rule": "max-nodes",
  "severity": "error",
  "threshold": 50,
  "actual": 85,
  "suggestion": "Split into sub-diagrams",
  "citation": "https://arxiv.org/abs/2008.07944"
}
Enter fullscreen mode Exit fullscreen mode

This structured data lets AI agents:

  • Parse issues programmatically
  • Prioritize by severity
  • Apply fixes systematically
  • Verify fixes resolved the issue

5. Fast Feedback Loops Matter

Static analysis (milliseconds) vs rendering (seconds) makes a huge difference when validating 87 diagrams. Fast feedback enables:

  • Rapid iteration during development
  • Quick CI/CD pipelines
  • Real-time validation in editors (future work)

Getting Started

Mermaid-sonar is production-ready and available now:

Installation:

npm install -g mermaid-sonar
Enter fullscreen mode Exit fullscreen mode

Basic usage:

# Validate your documentation
mermaid-sonar docs/

# Use with platform-specific viewport constraints
mermaid-sonar --viewport-profile mkdocs docs/

# Use in CI with strict mode (fails on any issues)
mermaid-sonar --strict --viewport-profile mkdocs docs/
Enter fullscreen mode Exit fullscreen mode

Viewport profiles available:

  • mkdocs - 800px width limit (MkDocs documentation framework)
  • docusaurus - 900px width limit (Docusaurus documentation framework)
  • github - 1000px width limit (GitHub README rendering)
  • mobile - 400px width limit (mobile devices)
  • Custom profiles via configuration file

Try the examples:
The examples directory includes runnable before/after diagrams from this blog post:

  • Clone the repo and run npx mermaid-sonar --viewport-profile mkdocs examples/mermaid-sonar-complexity-analyzer/
  • See both single-diagram and split-diagram approaches
  • Compare validation results yourself

See the project page for:

  • Complete CLI reference
  • Configuration options
  • CI/CD integration examples
  • All output formats

Conclusion

Mermaid-sonar solves a specific problem in AI-generated documentation: detecting hidden complexity in diagrams. The key insights:

  1. AI agents need quantitative feedback - "85 nodes (limit: 50)" beats "too complex"
  2. Research-backed thresholds build trust - Not arbitrary limits, but validated science
  3. Fast feedback enables iteration - Static analysis in milliseconds, not seconds
  4. Actionable suggestions drive fixes - "Split into 3 sub-diagrams" beats "simplify"
  5. Machine-readable output enables automation - JSON for programmatic processing
  6. Platform-aware validation prevents surprises - Viewport profiles ensure diagrams render well in production

For automated documentation workflows, this is critical. AI agents will generate technically correct but cognitively expensive diagrams. Mermaid-sonar catches these automatically, providing the quantitative feedback needed to guide agents toward readable visualizations.

This is part of a larger philosophy: automated generation needs automated quality gates. Whether it's mermaid-sonar for diagrams or debtmap for code complexity—quantitative validation enables higher quality AI-powered generation.

The tool is open source and ready to use:

Resources

Related Posts:

Tools:

Research:

Want more content like this? Follow me on Dev.to or subscribe to Entropic Drift for posts on AI-powered development workflows, Rust tooling, and technical debt management.

Check out my open-source projects:

Top comments (1)

Collapse
 
entropicdrift profile image
Glen Baker •

Shoot, looks like mermaid isn't rendering for dev.to, fortunately it renders in the original publication if you want the diagram visuals for better comparison.