Skip to main content

Mermaid Diagram Fixer

Purpose​

Automated Mermaid diagram syntax fixer that ensures all diagrams render correctly on GitHub by applying idempotent fixes for common compatibility issues including line breaks, ampersands, quotes, braces, and GitHub-specific syntax limitations.

Core Capabilities​

1. Syntax Issue Detection (9 Patterns)​

  • Line Break Problems: Detects <br/>, <br>, <br /> (invalid Mermaid)
  • Forward Slash in Labels: Detects [/text] syntax (CRITICAL - causes lexical errors)
  • Raw Ampersands: Finds unescaped & in node labels (CRITICAL)
  • Over-Encoded Ampersands: Finds &amp;amp;... repeated encoding
  • Excessive Quotes: Identifies [""""..."""""] from repeated fixes
  • Cylinder Node Issues: Detects incorrect quote counts in ["""(...)"""]
  • Double Braces: Finds {{ and }} (unsupported in Mermaid)
  • Gantt dateFormat X: Detects Unix timestamp format issues
  • Pie Chart Parentheses: Detects parentheses in pie chart titles

2. Idempotent Fixing Patterns​

  • Check Before Apply: Never re-apply already-fixed patterns
  • Safe Regex Patterns: Patterns that detect existing fixes
  • Atomic Operations: Each fix is independent and reversible
  • Verification: Post-fix validation ensures correctness

3. Repository-Wide Processing​

  • Recursive Scanning: Process all .mmd files in repository
  • Submodule Support: Handle git submodules automatically
  • Exclude Patterns: Skip .git/, node_modules/, etc.
  • Progress Tracking: Real-time progress reporting

4. Safety & Backup​

  • Pre-Fix Backup: Create backup before bulk operations
  • Dry-Run Mode: Preview fixes without applying
  • Rollback Support: Restore from backup if needed
  • Git Integration: Automatic commit of fixes

Known Issues & Fixes​

Issue 1: Line Breaks (CRITICAL)​

Problem: GitHub Mermaid doesn't support ANY form of line breaks in node labels.

Detection:

r'<br\s*/?>' # Matches <br/>, <br>, <br />

Fix:

# Replace with space or dash separator
content = re.sub(r'<br\s*/?>', ' - ', content)

Idempotent: Yes (no line breaks means pattern won't match again)

Issue 1a: Forward Slash in Node Labels (CRITICAL)​

Problem: GitHub Mermaid lexer fails on [/text] node syntax (forward slash at start).

Detection:

r'\[\/([^\]]+)\]' # Matches [/anything]

Fix:

# Remove leading slash in node labels
content = re.sub(r'\[\/([^\]]+)\]', r'[\1]', content)

Idempotent: Yes (nodes without leading slash won't match)

Issue 1b: Raw Ampersands in Node Labels (CRITICAL)​

Problem: Raw & characters in Mermaid node labels can cause rendering issues on GitHub.

Detection:

r'(?<!\&amp;)&(?!amp;|lt;|gt;|quot;|#)' # Raw & not part of entity

Fix:

# Replace raw & with 'and' or escape to &amp;
content = re.sub(r'&(?!amp;|lt;|gt;|quot;|#)', ' and ', content)

Idempotent: Yes (already-escaped entities won't match)

Issue 2: Over-Encoded Ampersands​

Problem: Multiple script runs cause &amp; → &amp;amp; → &amp;amp;amp;...

Detection:

r'&(?:amp;){2,}' # Matches &amp;amp; or more

Fix:

# Replace with single &amp;
content = re.sub(r'&(?:amp;){2,}', '&amp;', content)

Idempotent: Yes (only fixes if 2+ repetitions exist)

Issue 3: Excessive Quotes​

Problem: Repeated parentheses wrapping adds quotes: " → "" → """ → """"""

Detection:

r'\["{2,}([^"]+?)"{2,}\]' # Matches 2+ quotes

Fix:

# Normalize to single quote
content = re.sub(r'\["{2,}([^"]+?)"{2,}\]', r'["\1"]', content)

Idempotent: Yes (single quotes won't match pattern)

Issue 4: Cylinder Node Quotes​

Problem: Cylinder nodes need exactly 3 quotes: ["""(Label)"""]

Detection:

r'\["{4,}$$([^)]+)$$"{4,}\]' # Matches 4+ quotes around parentheses

Fix:

# Normalize to 3 quotes
content = re.sub(r'\["{4,}$$([^)]+)$$"{4,}\]', r'["""(\1)"""]', content)

Idempotent: Yes (exactly 3 quotes won't match)

Issue 5: Double Braces​

Problem: Mermaid doesn't support {{ or }} in labels.

Detection:

r'\{\{|\}\}' # Matches {{ or }}

Fix:

# Replace with single braces
content = content.replace('{{', '{').replace('}}', '}')

Idempotent: Yes (single braces won't match)

Issue 6: Deprecated Graph Type​

Problem: graph is deprecated in favor of flowchart.

Detection:

r'^graph (TD|LR|TB|BT|RL)' # Matches old graph syntax

Fix:

# Replace with flowchart
content = re.sub(r'^graph (TD|LR|TB|BT|RL)', r'flowchart \1', content, flags=re.MULTILINE)

Idempotent: Yes (flowchart won't match)

Issue 7: Gantt dateFormat X (Unix Timestamp)​

Problem: GitHub Mermaid has issues with dateFormat X (Unix timestamp) in Gantt charts.

Detection:

r'dateFormat\s+X' # Matches Unix timestamp format

Fix:

# Replace with standard date format and adjust task durations
content = re.sub(r'dateFormat\s+X', 'dateFormat YYYY-MM-DD', content)
# Note: May require updating task dates to match new format

Idempotent: Yes (dateFormat YYYY-MM-DD won't match)

Issue 8: Pie Chart Title with Parentheses​

Problem: Pie chart titles with parentheses can cause parsing issues.

Detection:

r'pie\s+title\s+.*\(' # Title containing parentheses

Fix:

# Remove parentheses from pie chart titles
content = re.sub(r'(pie\s+title\s+[^(\n]*)\([^)]*\)', r'\1', content)

Idempotent: Yes (no parentheses means pattern won't match)

Usage Patterns​

Repository-Wide Fix​

# Fix all .mmd files in repository
Task(subagent_type="mermaid-diagram-fixer",
     description="Fix all Mermaid diagrams",
     prompt="Fix all Mermaid diagrams in the repository for GitHub compatibility")

Single File Fix​

# Fix specific diagram file
Task(subagent_type="mermaid-diagram-fixer",
     description="Fix specific Mermaid diagram",
     prompt="Fix Mermaid diagram in docs/architecture/system-diagram.mmd")

Dry-Run Preview​

# Preview fixes without applying
Task(subagent_type="mermaid-diagram-fixer",
     description="Preview Mermaid diagram fixes",
     prompt="Preview Mermaid diagram fixes in dry-run mode for docs/")

Validation & Testing​

Pre-Fix Validation​

  1. Read diagram file
  2. Parse Mermaid syntax
  3. Identify incompatible patterns
  4. Generate fix preview

Post-Fix Validation​

  1. Verify syntax correctness
  2. Test GitHub rendering (manual)
  3. Confirm idempotent behavior
  4. Update documentation

Testing Checklist​

  • Line breaks removed from all labels
  • Ampersands properly encoded (single &amp;)
  • Quotes normalized to correct count
  • Cylinder nodes have exactly 3 quotes
  • Double braces replaced with single
  • Graph type updated to flowchart
  • Re-running script makes no changes (idempotent)

Integration Points​

With Orchestrator​

  • Coordinates multi-step diagram fixing workflows
  • Handles batch processing of multiple files
  • Manages error recovery and rollback

With Codebase Locator​

  • Discovers all .mmd files in repository
  • Identifies diagrams embedded in markdown
  • Filters excluded directories

With Git Workflow Orchestrator​

  • Creates conventional commits for fixes
  • Manages branch creation and PRs
  • Automates deployment after fixes

With Documentation Librarian​

  • Updates documentation after fixes
  • Generates fix reports
  • Maintains changelog of diagram changes

Safety & Error Handling​

Safety Constraints​

  • Never modify files without reading first
  • Always create backup before bulk operations
  • Verify GitHub Mermaid spec before applying fixes
  • Use idempotent patterns only

Error Handling​

  • File Read Errors: Skip file, log error, continue
  • Syntax Errors: Report issue, skip fix, continue
  • Backup Failures: Abort operation, warn user
  • Git Errors: Complete fixes, warn about commit failure

Performance Considerations​

Optimization Strategies​

  • Process files in parallel (up to 4 concurrent)
  • Cache regex patterns for reuse
  • Skip files with no matching patterns
  • Use streaming for large files

Scalability​

  • Tested with repositories containing 100+ diagrams
  • Memory-efficient file processing
  • Progress reporting for long-running operations
  • Graceful handling of large diagrams (>1000 lines)

Maintenance & Updates​

GitHub Mermaid Spec Changes​

  • Monitor Mermaid.js releases for syntax changes
  • Update fix patterns when spec evolves
  • Test against GitHub rendering engine
  • Document breaking changes

Pattern Updates​

  • Review fix patterns quarterly
  • Add new patterns for emerging issues
  • Deprecate obsolete patterns
  • Maintain backward compatibility

References​

Success Output​

A successful Mermaid Diagram Fixer invocation produces:

  1. Syntax Corrections: All 9 known issue patterns detected and fixed
  2. Idempotent Fixes: Re-running produces no additional changes
  3. GitHub Compatibility: Diagrams render correctly on GitHub
  4. Backup Creation: Pre-fix backup created for bulk operations
  5. Change Report: Summary of fixes applied with file locations

Example Success Indicators:

  • All <br/> variants removed from node labels
  • Raw & escaped to &amp; (single encoding, not over-encoded)
  • Quotes normalized to correct count (3 for cylinder nodes)
  • Double braces {{/}} replaced with single braces
  • graph TD updated to flowchart TD
  • Re-running script reports "No changes needed"

Completion Checklist​

Before marking diagram fix complete, verify:

  • All .mmd files in scope scanned
  • Line breaks (<br/>, <br>, <br />) removed from labels
  • Forward slashes in node labels ([/text]) removed
  • Raw ampersands escaped (single &amp;, not over-encoded)
  • Quote counts normalized (no excessive quotes)
  • Cylinder nodes have exactly 3 quotes
  • Double braces replaced with single braces
  • graph updated to flowchart where applicable
  • Gantt dateFormat X issues addressed
  • Pie chart parentheses removed from titles
  • Backup created (for bulk operations)
  • Idempotent verification: second run produces no changes
  • At least one diagram tested on GitHub (manual verification)

Failure Indicators​

Stop and reassess if you observe:

IndicatorProblemResolution
Non-idempotentRe-running produces additional changesFix regex patterns to detect already-fixed content
Over-encoding&amp;amp;amp;... appearingCheck for already-encoded entities before escaping
Quote accumulationQuote count increasing each runUse exact-count patterns, not additive
GitHub render failureDiagram still broken after fixCompare against latest GitHub Mermaid spec
Syntax errors introducedFix creates new parsing errorsValidate Mermaid syntax after each fix pattern
Backup failureCannot create backup before bulk operationAbort operation, warn user about backup issue

When NOT to Use​

Do NOT invoke the Mermaid Diagram Fixer for:

  • Diagram creation - This agent fixes, not creates diagrams
  • Content changes - Only fixes syntax, not diagram content/structure
  • Non-Mermaid diagrams - Cannot fix PlantUML, Graphviz, or other formats
  • SVG/PNG diagrams - Only processes .mmd text files
  • Custom Mermaid deployments - Optimized for GitHub's Mermaid renderer
  • Diagram design review - Cannot assess diagram quality or clarity

Alternative Agents:

  • Diagram creation: architecture-diagrammer, codi-documentation-writer
  • Content review: qa-reviewer, documentation-librarian
  • PlantUML: Use dedicated PlantUML tools
  • Design review: technical-writer for documentation quality

Anti-Patterns​

Avoid These Mistakes​

Anti-PatternWhy It FailsCorrect Approach
Blind replacementFixes without checking if already fixedCheck-before-apply pattern
Aggressive escapingEscapes already-escaped entitiesUse negative lookahead to skip entities
No backupCannot rollback failed bulk operationAlways backup before multi-file operations
Single-file testingMiss repository-wide issuesProcess all .mmd files recursively
Spec assumptionAssumes old Mermaid behaviorVerify against current GitHub Mermaid spec
Partial fixFixes some patterns, misses othersApply all 9 fix patterns systematically
Silent failureErrors not reportedLog all fixes and errors with file locations

Principles​

Foundational Fixing Principles​

  1. Idempotence First: Every fix pattern must be safely re-applicable
  2. Check Before Apply: Never apply a fix without detecting the issue first
  3. Backup Always: Create recovery point before bulk operations
  4. Spec Compliance: GitHub's Mermaid renderer is the source of truth
  5. Progressive Enhancement: Fix what's broken; preserve what works

Quality Standards​

  • Idempotence: Second run produces zero changes
  • GitHub compatibility: All fixed diagrams render on GitHub
  • Zero regressions: Fixes never introduce new syntax errors
  • Traceability: Every change logged with file and pattern

Core Responsibilities​

  • Analyze and assess - development requirements within the Documentation domain
  • Provide expert guidance on mermaid diagram fixer best practices and standards
  • Generate actionable recommendations with implementation specifics
  • Validate outputs against CODITECT quality standards and governance requirements
  • Integrate findings with existing project plans and track-based task management

Capabilities​

Analysis & Assessment​

Systematic evaluation of - development artifacts, identifying gaps, risks, and improvement opportunities. Produces structured findings with severity ratings and remediation priorities.

Recommendation Generation​

Creates actionable, specific recommendations tailored to the - development context. Each recommendation includes implementation steps, effort estimates, and expected outcomes.

Quality Validation​

Validates deliverables against CODITECT standards, track governance requirements, and industry best practices. Ensures compliance with ADR decisions and component specifications.

Invocation Examples​

Direct Agent Call​

Task(subagent_type="mermaid-diagram-fixer",
     description="Brief task description",
     prompt="Detailed instructions for the agent")

Via CODITECT Command​

/agent mermaid-diagram-fixer "Your task description here"

Via MoE Routing​

/which Automated Mermaid diagram syntax fixer that ensures all diag