# mermaid-diagrams

Mermaid Diagrams Create professional software diagrams using Mermaid's text-based syntax. Mermaid renders diagrams from simple text definitions, making diagrams version-controllable, easy to update, and maintainable alongside code. Installation OpenClaw / Moltbot / Clawbot

npx clawhub@latest install mermaid-diagrams

Core Syntax All Mermaid diagrams follow this pattern: diagramType definition content Key principles: First line declares diagram type (e.g., classDiagram, sequenceDiagram, flowchart) Use %% for comments Line breaks and indentation improve readability but aren't required Unknown words break diagrams; invalid parameters fail silently Diagram Type Selection TypeUse ForReferenceClass DiagramsDomain modeling, OOP design, entity relationshipsreferences/class-diagrams.mdSequence DiagramsAPI flows, auth flows, component interactionsreferences/sequence-diagrams.mdFlowchartsProcesses, algorithms, decision trees, user journeysreferences/flowcharts.mdERDDatabase schemas, table relationships, data modelingreferences/erd-diagrams.mdC4 DiagramsSystem context, containers, components, architecturereferences/c4-diagrams.mdState DiagramsState machines, lifecycle states—Git GraphsBranching strategies—Gantt ChartsProject timelines, scheduling— For styling, themes, and layout options: See references/advanced-features.md Quick Start Examples Class Diagram (Domain Model) classDiagram Title -- Genre Title *-- Season Title *-- Review User --> Review : creates class Title { +string name +int releaseYear +play() } class Genre { +string name +getTopTitles() } Sequence Diagram (API Flow) sequenceDiagram participant User participant API participant Database User->>API: POST /login API->>Database: Query credentials Database-->>API: Return user data alt Valid credentials API-->>User: 200 OK + JWT token else Invalid credentials API-->>User: 401 Unauthorized end Flowchart (User Journey) flowchart TD Start([User visits site]) --> Auth{Authenticated?} Auth -->|No| Login[Show login page] Auth -->|Yes| Dashboard[Show dashboard] Login --> Creds[Enter credentials] Creds --> Validate{Valid?} Validate -->|Yes| Dashboard Validate -->|No| Error[Show error] Error --> Login ERD (Database Schema) erDiagram USER ||--o{ ORDER : places ORDER ||--|{ LINE_ITEM : contains PRODUCT ||--o{ LINE_ITEM : includes USER { int id PK string email UK string name datetime created_at } ORDER { int id PK int user_id FK decimal total datetime created_at } Best Practices Start simple — begin with core entities/components, add details incrementally Use meaningful names — clear labels make diagrams self-documenting Comment extensively — use %% comments to explain complex relationships Keep focused — one diagram per concept; split large diagrams into multiple views Version control — store .mmd files alongside code for easy updates Add context — include titles and notes to explain diagram purpose Iterate — refine diagrams as understanding evolves Configuration and Theming Configure diagrams using frontmatter:

config:
theme: base
themeVariables:
primaryColor: "#ff6b6b"

flowchart LR A --> B Available themes: default, forest, dark, neutral, base Layout options:

layout: dagre (default) — classic balanced layout
layout: elk — advanced layout for complex diagrams

Look options:

look: classic — traditional Mermaid style
look: handDrawn — sketch-like appearance

Rendering and Export Native support in: GitHub/GitLab — automatically renders in Markdown VS Code — with Markdown Mermaid extension Notion, Obsidian, Confluence — built-in support Export options: Mermaid Live Editor — online editor with PNG/SVG export

Mermaid CLI — npm install -g @mermaid-js/mermaid-cli then mmdc -i input.mmd -o output.png

When to Create Diagrams Always diagram when: Starting new projects or features Documenting complex systems Explaining architecture decisions Designing database schemas Planning refactoring efforts Onboarding new team members Use diagrams to: Align stakeholders on technical decisions Document domain models collaboratively Visualize data flows and system interactions Plan before coding Create living documentation that evolves with code Common Pitfalls Breaking characters — avoid {} in comments; escape special characters Syntax errors — misspellings break diagrams; validate in Mermaid Live Overcomplexity — split complex diagrams into multiple focused views Missing relationships — document all important connections between entities Stale diagrams — a wrong diagram is worse than no diagram; update when systems change NEVER Do NEVER create diagrams with more than 15 nodes — they become unreadable; split into multiple focused diagrams NEVER leave arrows unlabeled — every connection should explain the relationship or data flow NEVER create diagrams without a title or caption — context-free diagrams are useless outside the author's head NEVER use diagrams as the sole documentation — pair diagrams with prose that explains the "why" NEVER let diagrams go stale — update diagrams when architecture changes; stale diagrams mislead NEVER use Mermaid for data visualization — Mermaid is for architecture and flow diagrams, not charts of business data