Mermaid Documentation Guide

Mermaid is a JavaScript-based diagramming and charting tool that uses text definitions to create diagrams dynamically. This skill includes the complete official documentation from the mermaid repository.

Quick Start: Read mermaid-cli/README.md for installation and usage. Always use mermaid-cli to validate code and generate diagrams. Adjust width/height for readability (default PNGs are often too small).

Documentation Structure

Quick Start

• mermaid-README.md - Main Mermaid project README with overview, features, and quick examples

Getting Started

• intro/getting-started.md - Quick start guide for using Mermaid
• intro/index.md - Introduction and overview
• intro/syntax-reference.md - General syntax reference across all diagram types
• config/usage.md - How to use Mermaid in different environments

Installation and CLI

• mermaid-cli/README.md - Complete mermaid-cli (mmdc) installation and usage guide
• config/mermaidCLI.md - Additional CLI usage information from the main docs
• config/setup/ - Setup instructions for different environments

CLI Troubleshooting

• mermaid-cli/already-installed-chromium.md - Using already-installed Chromium instead of downloading
• mermaid-cli/linux-sandbox-issue.md - Fixing Linux sandbox issues
• mermaid-cli/docker-permission-denied.md - Fixing Docker permission issues
• mermaid-cli/reviewing.md - Code review guidelines for mermaid-cli

Diagram Type Syntax

For detailed syntax, examples, and best practices for each diagram type, refer to files in the syntax/ folder:

Core Diagrams

• syntax/flowchart.md - Process flows, decision trees, and workflows with various node shapes and arrow types
• syntax/sequenceDiagram.md - Actor interactions over time, showing message flows and activations
• syntax/classDiagram.md - Object-oriented structures with classes, attributes, methods, and relationships
• syntax/stateDiagram.md - State machines showing states and transitions
• syntax/entityRelationshipDiagram.md - Database schemas and data model relationships

Planning & Project Management

• syntax/userJourney.md - User experience mapping with satisfaction scores
• syntax/gantt.md - Project schedules, timelines, and task dependencies
• syntax/kanban.md - Workflow visualization with columns and cards
• syntax/timeline.md - Chronological events and project histories
• syntax/requirementDiagram.md - System requirements and verification methods

Data Visualization

• syntax/pie.md - Data proportions and percentages
• syntax/quadrantChart.md - 2x2 prioritization and analysis matrices
• syntax/xyChart.md - Line and bar charts for data trends
• syntax/sankey.md - Flow quantities and data transfers between stages

Technical Diagrams

• syntax/gitgraph.md - Git branching, merging, and workflow patterns
• syntax/c4.md - Software architecture at multiple abstraction levels
• syntax/block.md - System components and relationships
• syntax/packet.md - Network packet structures and protocol headers
• syntax/architecture.md - System design with icons and groupings

Advanced & Specialized

• syntax/mindmap.md - Hierarchical information and brainstorming
• syntax/zenuml.md - Alternative sequence diagram syntax with code-like format
• syntax/radar.md - Multi-axis comparisons
• syntax/treemap.md - Hierarchical data as nested rectangles

Configuration and Customization

• config/configuration.md - Mermaid configuration options
• config/theming.md - Theme customization and styling
• config/directives.md - Using directives in diagrams
• config/icons.md - Using icons in diagrams
• config/layouts.md - Layout configuration options
• config/math.md - Mathematical expressions in diagrams
• config/accessibility.md - Accessibility features and best practices

Troubleshooting and FAQs

• config/faq.md - Frequently asked questions
• syntax/examples.md - Collection of example diagrams

Common Usage Patterns

When the user asks to:

• Get an overview → Check mermaid-README.md
• Create a flowchart → Check syntax/flowchart.md
• Create a sequence diagram → Check syntax/sequenceDiagram.md
• Create a class diagram → Check syntax/classDiagram.md
• Create a Gantt chart → Check syntax/gantt.md
• Create an ER diagram → Check syntax/entityRelationshipDiagram.md
• Customize appearance → Check config/theming.md and config/configuration.md
• Install or use the CLI → Check mermaid-cli/README.md
• Use the CLI (additional info) → Check config/mermaidCLI.md
• Troubleshoot CLI issues → Check mermaid-cli/linux-sandbox-issue.md, mermaid-cli/already-installed-chromium.md, or mermaid-cli/docker-permission-denied.md
• Troubleshoot general issues → Check config/faq.md
• See examples → Check syntax/examples.md
• Learn syntax basics → Check intro/syntax-reference.md

Using Mermaid CLI

The mermaid-cli (mmdc) is the command-line tool for generating diagrams. For complete installation and usage details, see mermaid-cli/README.md.

Basic CLI Usage

# Generate PNG from mermaid file
mmdc -i input.mmd -o output.png

# Generate SVG
mmdc -i input.mmd -o output.svg

# Generate PDF
mmdc -i input.mmd -o output.pdf

# Specify theme
mmdc -i input.mmd -o output.png -t dark

# Specify background color
mmdc -i input.mmd -o output.png -b transparent

# Specify width
mmdc -i input.mmd -o output.png -w 1920

# Specify height
mmdc -i input.mmd -o output.png -H 1080

Important Notes:

• By default, PNG files might be too small. Adjust width and height to be large enough to be readable.
• Always test diagrams with mermaid-cli to validate syntax before finalizing.
• PNG output typically requires explicit width/height for good quality.

Quick Reference by Use Case

For Basic Diagram Creation

1. Choose the diagram type from the syntax/ folder
2. Read the syntax documentation for that type
3. Create your .mmd file with the diagram definition
4. Generate output using mmdc command

For Styling and Theming

1. Check config/theming.md for theme options
2. Check config/configuration.md for global settings
3. Use directives (see config/directives.md) for inline configuration

For Integration

1. Check config/usage.md for embedding in web pages
2. Check mermaid-cli/README.md for command-line usage
3. Check intro/getting-started.md for basic setup

For Troubleshooting

1. Check config/faq.md first for general issues
2. Check mermaid-cli/ folder for CLI-specific troubleshooting (Linux sandbox, Chromium, Docker)
3. Validate syntax against the specific diagram type documentation
4. Check syntax/examples.md for working examples
5. Review config/accessibility.md for rendering issues

Common Troubleshooting Tips

Line Breaks & Multi-line Text

• ✅ Use <br/> for line breaks: Node["Text<br/>More text"]
• ✅ Use <br/><br/> for paragraph spacing
• ❌ Never use plain newlines (\n) - causes "Unsupported markdown: list" errors
• Keep bullet points concise (2-4 words), limit to 3-4 per node

Text & Canvas Size

• Increase font size: classDef style font-size:20px
• Vertical flowcharts: mmdc -i file.mmd -o file.png -w 2000 -H 2800
• Horizontal flowcharts: mmdc -i file.mmd -o file.png -w 3000 -H 1400

Special Characters

• Avoid starting labels with numbers
• Escape quotes with \"
• Ampersands: Avoid & (renders as &) - use "and" or "+" instead
• Use < for <, > for > only when necessary

General Tips

• Start with the appropriate diagram type for your use case
• Refer to the specific diagram documentation in syntax/ for detailed syntax
• Test diagrams with mermaid-cli before finalizing
• Use consistent formatting and naming conventions
• Add comments with %% for documentation
• Consider your audience when choosing detail level
• Check the intro/syntax-reference.md for cross-diagram syntax patterns

File Organization

• mermaid-README.md - Main Mermaid project README
• mermaid-cli/ - Complete mermaid-cli documentation and troubleshooting
• intro/ - Getting started guides and general reference
• syntax/ - Complete syntax documentation for all diagram types
• config/ - Configuration, theming, CLI, and troubleshooting
• diagrams/ - Additional diagram documentation and examples
• ecosystem/ - Information about the Mermaid ecosystem
• community/ - Community resources and contributions

Notes

• Some diagram types may be experimental or have evolving syntax
• Always validate your diagrams with the mermaid-cli tool
• The official documentation is continuously updated
• For the latest updates, refer to https://mermaid.js.org/