Mermaid Diagrams

Generate professional, consistently-styled Mermaid diagrams for technical content with automatic template selection, content generation, and quality validation.

Quick Start

Subagent Pattern (Recommended):

When user requests diagram generation, spawn a subagent:

Generate 3 Mermaid diagrams for /path/to/chapter-01.md and save to diagrams/chapter-01/

The subagent will:

• Read chapter content
• Select appropriate templates
• Generate placeholder content
• Create content.json
• Run generation script
• Validate output

# 1. Create content.json (see assets/example-content.json)
# 2. Render diagrams
node scripts/generate.mjs --content content.json --out diagrams/chapter-01

# 3. Validate
node scripts/validate.mjs --dir diagrams/chapter-01

Prerequisites

Automated Installation (Recommended)

Run the installation script to automatically install and verify mermaid-cli:

cd $SKILL_DIR  # Path to skill-mermaid-diagrams directory
./scripts/install-deps.sh

The script will:

• Check Node.js version (>= 18.0.0 required)
• Install or upgrade mermaid-cli to latest version
• Verify installation and version compatibility
• Provide troubleshooting guidance if needed

Manual Installation

Alternatively, install Mermaid CLI globally:

npm install -g @mermaid-js/mermaid-cli

Verify installation:

mmdc --version  # Should be >= 11.0.0

Usage Patterns

Subagent Workflow (Primary Pattern)

When a user requests diagram generation, spawn a subagent to handle the complete workflow:

Task: Generate 3 Mermaid diagrams for chapter 5

Steps:
1. Read $CONTENT_DIR/chapters/chapter-05.md
2. Analyze content and select 3 appropriate diagram templates from: architecture, flowchart, sequence, concept-map, timeline, comparison
3. For each selected template:
   - Read template from $SKILL_DIR/assets/
   - Extract placeholders ({{PLACEHOLDER_NAME}} format)
   - Generate concise labels (max 8 words each) based on chapter content
4. Create content.json with structure:
   {
     "chapter": "chapter-05.md",
     "diagrams": [
       {
         "template": "architecture",
         "placeholders": { "SYSTEM_NAME": "...", ... }
       },
       ...
     ]
   }
5. Save to $CONTENT_DIR/diagrams/chapter-05/content.json
6. Run: node $SKILL_DIR/scripts/generate.mjs --content content.json --out $CONTENT_DIR/diagrams/chapter-05
7. Validate: node $SKILL_DIR/scripts/validate.mjs --dir $CONTENT_DIR/diagrams/chapter-05
8. Report success with file count

Note: Replace $SKILL_DIR and $CONTENT_DIR with actual paths:
- SKILL_DIR: Path to skill-mermaid-diagrams directory
- CONTENT_DIR: Path to your content/project directory

Manual Content Generation

If generating content.json manually:

# 1. Create content.json (see assets/example-content.json)
# 2. Render
cd $SKILL_DIR  # Path to skill-mermaid-diagrams directory
node scripts/generate.mjs \
  --content /path/to/content.json \
  --out /path/to/output

# 3. Validate
node scripts/validate.mjs --dir /path/to/output

Parameters:

• --content / -c: Content JSON file (required)
• --out / -o: Output directory (default: ./diagrams)

Validate All Generated Diagrams

for dir in diagrams/chapter-*/; do
  node scripts/validate.mjs --dir "$dir"
done

Available Templates

The skill includes 12 professionally-themed templates with consistent color schemes:

• architecture.mmd - System architecture, component diagrams, tool integration
• Use for: System components, tool pipelines, agent interactions
• Fixed node IDs (space-safe): Uses C1, C2, C3 internally, only labels are customizable
• flowchart.mmd - Decision flows, processes, workflows, debugging steps
• Use for: Decision trees, process flows, validation workflows
• sequence.mmd - Actor interactions, message passing, session patterns
• Use for: API call sequences, actor communication, message flows
• concept-map.mmd - Key concepts, mental models, paradigms, relationships
• Use for: Hierarchical concepts, mental models, knowledge graphs
• Improved version (graph-based, not mindmap): Full color control, readable text
• radial-concept.mmd - Layered concepts radiating from center - Use for: Progressive summarization, abstraction layers, hierarchical models
• 4 color-coded levels: green → orange → blue → purple
• timeline.mmd - Temporal progression, optimization stages, evolution
• Use for: Project phases, evolution timelines, staged processes
• comparison.mmd - Trade-offs, quadrant analysis (2D plotting)
• Use for: Cost vs performance, effort vs impact (X/Y coordinate plotting)
• Requires X/Y coordinates for items
• comparison-table.mmd - Side-by-side feature comparison
• Use for: AI vs Script decisions, option comparisons, feature matrices
• Alternative to quadrant when you need simple side-by-side, not 2D plotting
• gantt.mmd - Project timelines, task scheduling - Use for: Project planning, milestone tracking, task dependencies
• Supports: Multiple sections, task status (done/active/crit), date ranges
• mindmap.mmd - Organic radial mind maps - Use for: Brainstorming, organic thought structures, free-form concept mapping
• Limitation: Auto-assigns colors/text (limited theme control)
• Alternative: Use radial-concept.mmd for better color control
• class-diagram.mmd - UML class diagrams
• Use for: Object models, database schemas, system architecture (OOP)
• Supports: Attributes, methods, relationships (inheritance, composition, association)
• state-diagram.mmd - State machines, lifecycle diagrams
• Use for: Process states, object lifecycles, workflow stages
• Supports: Transitions with labels, notes on states, start/end markers

Template Placeholder Reference

Each template requires specific placeholders. All placeholders must be provided to avoid rendering errors.

• architecture.mmd: Uses fixed node IDs (C1, C2, C3, E1, E2) internally. Only *_LABEL placeholders are customizable. Labels can contain spaces (space-safe).
• concept-map.mmd: Improved graph-based version (replaced mindmap). Better color control and readability.
• comparison.mmd: QuadrantChart requires X/Y coordinates. Use comparison-table.mmd for simple side-by-side comparisons.
• gantt.mmd: Task status options: done, active, crit, or blank. Date format: YYYY-MM-DD. Duration: Nd (days) or YYYY-MM-DD.
• mindmap.mmd: Limited theme control (auto-colors, auto-text). For controlled colors/text, use radial-concept.mmd instead.
• class-diagram.mmd: Relationship types: <|-- (inheritance), *-- (composition), o-- (aggregation), --> (association), ..> (dependency).
• state-diagram.mmd: Uses stateDiagram-v2 syntax. States are simple identifiers (no spaces). Notes attach to states 1, 4, and 7.
• Text length limits: Generator warns if labels exceed recommended length (25-50 chars depending on template).

• Component labels: COMPONENT_1_LABEL, COMPONENT_2_LABEL
• Branch hierarchy: BRANCH_1, BRANCH_1_SUB_1, BRANCH_1_SUB_2
• Level-based: LEVEL_1_LABEL, LEVEL_1_NODE_1

Changelog & Migration Notes

v2.0 (2026-02-15) - Root Cause Fixes

Breaking Changes:

• architecture.mmd - Fixed node ID handling (space-safe)
• Before: Used placeholder values as node IDs → failed when labels contained spaces
• After: Uses fixed node IDs (C1, C2, C3) → labels can contain any characters
• Migration: Remove COMPONENT_1, COMPONENT_2, COMPONENT_3 from content.json (only *_LABEL variants needed)
• concept-map.mmd - Replaced mindmap with graph-based version
• Before: Mindmap syntax with auto-colors, black-on-purple text (unreadable)
• After: Graph LR syntax with explicit styling, white text on dark backgrounds
• Result: +100% contrast improvement (2.6:1 → 5.2:1 on purple nodes)

• radial-concept.mmd - Progressive summarization diagrams with 4 color-coded levels
• comparison-table.mmd - Side-by-side feature comparison (alternative to quadrant chart)
• Validation - Generator now warns about text length, unresolved placeholders, special characters

Color Scheme (Consistent Across All Templates)

• Primary Blue: #4A90E2 - Main components, actions
• Secondary Purple: #7B68EE - Supporting elements
• Tertiary Green: #90EE90 - External actors, success states
• Warning Yellow: #FFD700 - Decisions, cautions
• Error Red: #FF6B6B - Failures, critical paths

Output Structure

After generation, each chapter directory contains:

diagrams/chapter-01/
├── diagram-01-architecture.mmd   # Mermaid source
├── diagram-01-architecture.svg   # Vector output
├── diagram-01-architecture.png   # Raster output (1200px wide)
├── diagram-02-flowchart.mmd
├── diagram-02-flowchart.svg
├── diagram-02-flowchart.png
├── diagram-03-concept-map.mmd
├── diagram-03-concept-map.svg
├── diagram-03-concept-map.png
└── summary.json                   # Generation metadata

Error Handling

The generator includes robust error handling:

• Template Selection Failure: Falls back to first N templates in order
• Content Generation Failure: Skips diagram, continues with next
• Rendering Failure: Reports error, saves .mmd source for manual debugging
• Missing mmdc CLI: Exits early with installation instructions

Quality Validation

The validator checks each diagram for:

• ✅ File readable and valid UTF-8
• ✅ Theme configuration present
• ✅ No unresolved placeholders ({{PLACEHOLDER}})
• ✅ SVG file rendered
• ✅ PNG file rendered
• ✅ Syntax valid (can re-render without errors)

# Generate diagrams
node scripts/generate.mjs --content content.json --out diagrams/chapter-01

# Validate output
node scripts/validate.mjs --dir diagrams/chapter-01

# Fix any failures and re-run

Cost Analysis

Per Chapter (3 diagrams):

• Subagent LLM usage:
• Chapter reading: ~3000 tokens input
• Template selection: ~500 tokens output
• Content generation (3 diagrams): ~1500 tokens output
• Total: ~5000 tokens (~$0.002)
• Rendering: Free (local mmdc)

• 14 × $0.002 = ~$0.03 total

• Mermaid diagrams: ~$0.03
• GLM images: ~$0.63
• DALL-E images: ~$2.52
• Savings: 95-99% vs AI image generation

Customization

Modify Color Scheme

Edit theme variables in any template file (assets/*.mmd):

%%{init: {'theme':'base', 'themeVariables': {
  'primaryColor':'#NEW_COLOR',
  'secondaryColor':'#NEW_COLOR',
  ...
}}}%%

Add New Template

• Create assets/new-template.mmd with theme and placeholders
• Add entry to TEMPLATES object in scripts/generate.mjs:

const TEMPLATES = {
  ...
  "new-template": "Description of when to use this template",
};

• Test with content:

node scripts/generate.mjs --content test-content.json --out test-output

Troubleshooting

"mmdc not found"

• Install: npm install -g @mermaid-js/mermaid-cli
• Verify: which mmdc

• Check template name in content.json matches file in assets/ (case-sensitive)
• Available templates: architecture, flowchart, sequence, concept-map, radial-concept, timeline, comparison, comparison-table, gantt, mindmap, class-diagram, state-diagram

• Check .mmd file for syntax errors
• Manually test: mmdc -i diagram.mmd -o test.svg
• Validate with: node scripts/validate.mjs --dir output_dir

• Subagent didn't generate all required placeholder values
• Check template file to see required placeholders
• Manually add missing values to content.json and re-run generate.mjs

• Check chapter file path is correct
• Verify skill path is accessible from subagent
• Ensure mmdc is installed globally (subagent needs it too)

Examples

Generated Architecture Diagram

%%{init: {'theme':'base', ...}}%%
graph TB
    subgraph "Agent System"
        Gateway[Gateway Process]
        Session[Session Manager]
        Tools[Tool Registry]
    end

    User((User))
    Provider((LLM Provider))

    User -->|Request| Gateway
    Gateway -->|Route| Session
    Session -->|Select Tool| Tools
    Tools -->|Execute| Provider

Output: Clean, consistent, professional diagram with uniform styling across all chapters.

Best Practices

• Consistent counts: Use same --max value for all chapters (e.g., 3)
• Review before commit: Run validator on all outputs before pushing
• Version control: Commit both .mmd source and .svg/.png renders
• Iterate templates: If diagrams look wrong, adjust template then regenerate
• Manual touch-ups: Edit .mmd files directly for fine-tuning, then re-render with mmdc

Testing

Installation Test

./scripts/install-deps.sh

Verifies that mermaid-cli is installed and meets version requirements.

Functional Test

• Create test content: assets/example-content.json (already included)
• Generate diagrams: node scripts/generate.mjs --content assets/example-content.json --out test-output
• Validate output: node scripts/validate.mjs --dir test-output
• Verify all checks pass

References

Local Documentation

• Mermaid Syntax Guide: references/mermaid-syntax.md - Quick reference for diagram syntax, theming, and common patterns
• Example Content: assets/example-content.json - Real-world content structure example

External Resources

• Mermaid Docs: https://mermaid.js.org/
• Syntax Reference: https://mermaid.js.org/intro/syntax-reference.html
• Theming Guide: https://mermaid.js.org/config/theming.html
• CLI Documentation: https://github.com/mermaid-js/mermaid-cli
• Live Editor: https://mermaid.live/ (interactive testing)