mermaid
npx machina-cli add skill tslateman/duet/mermaid --openclawMermaid.js v11
Overview
Create text-based diagrams using Mermaid.js v11 declarative syntax. Mermaid is the only diagram format that renders natively in GitHub markdown -- no exported images to commit.
Quick Start
Basic Diagram Structure:
{diagram-type}
{diagram-content}
Common Diagram Types:
flowchart- Process flows, decision treessequenceDiagram- Actor interactions, API flowsclassDiagram- OOP structures, data modelsstateDiagram- State machines, workflowserDiagram- Database relationshipsgantt- Project timelinesjourney- User experience flows
WARNING:
references/diagram-types.mdcovers all 24+ diagram types with full syntax. Load only when you need a specific type's syntax.
Creating Diagrams
Inline Markdown Code Blocks:
```mermaid
flowchart TD
A[Start] --> B{Decision}
B -->|Yes| C[Action]
B -->|No| D[End]
```
Configuration via Frontmatter:
```mermaid
---
theme: dark
---
flowchart LR
A --> B
```
Comments: Use %% prefix for single-line comments.
Syntax Rules
Follow these to avoid parse errors:
- Indentation: Use consistent 4-space indentation
- Node IDs: Short unique identifiers (A, B, node1). Avoid reserved words
- Special characters: Wrap text with special characters in quotes
- Subgraphs: Must close with
endkeyword - Whitespace: No trailing whitespace (causes parsing failures)
- Complexity: Break diagrams at 15+ elements into multiple focused diagrams
CLI Usage
Convert .mmd files to images:
# Installation
npm install -g @mermaid-js/mermaid-cli
# Basic conversion
mmdc -i diagram.mmd -o diagram.svg
# With theme and background
mmdc -i input.mmd -o output.png -t dark -b transparent
# Custom styling
mmdc -i diagram.mmd --cssFile style.css -o output.svg
See references/cli-usage.md for Docker, batch processing, and advanced workflows.
Configuration & Theming
Common Options:
theme: "default", "dark", "forest", "neutral", "base"look: "classic", "handDrawn"fontFamily: Custom font specificationsecurityLevel: "strict", "loose", "antiscript"
See references/configuration.md for complete config options, theming, and customization.
Practical Patterns
Load references/examples.md for:
- Architecture diagrams
- API documentation flows
- Database schemas
- Project timelines
- State machines
- User journey maps
Resources
references/diagram-types.md- Syntax for all 24+ diagram typesreferences/configuration.md- Config, theming, accessibilityreferences/cli-usage.md- CLI commands and workflowsreferences/integration.md- JavaScript API and embeddingreferences/examples.md- Practical patterns and use cases
See Also
/excalidraw- For architecture diagrams where hand-drawn aesthetic and drag-and-drop editing matter/design- Design thinking applies to diagram composition and layout/prose- Diagram labels benefit from the same concision rules as prose
Overview
Mermaid.js v11 enables writing text-based diagrams to visualize flows, sequences, classes, states, ERs, Gantt charts, and more. It supports inline rendering in GitHub markdown and CLI rendering to SVG/PNG/PDF, with theming and configuration for consistent visuals.
How This Skill Works
Diagrams are authored using Mermaid syntax inside code blocks or with frontmatter to configure appearance. The Mermaid CLI (mmdc) can convert .mmd files to images, while Mermaid blocks render natively in GitHub READMEs, enabling inline documentation diagrams without exported assets.
When to Use It
- Embed flowcharts to illustrate business processes and decision paths in README or docs
- Document API calls and system interactions using sequence diagrams
- Model data structures or database schemas with class or ER diagrams
- Plan projects with Gantt charts, timelines, or user journey maps
- Embed diagrams that render natively on GitHub without exporting images
Quick Start
- Step 1: Install Mermaid CLI: npm install -g @mermaid-js/mermaid-cli
- Step 2: Create diagram.mmd with Mermaid syntax (e.g., flowchart TD ... )
- Step 3: Render to SVG/PNG/PDF: mmdc -i diagram.mmd -o diagram.svg
Best Practices
- Keep node IDs short and avoid reserved words
- Use consistent 4-space indentation and close subgraphs with end
- Split large diagrams into smaller, focused diagrams for readability
- Add inline notes with comments using %%
- Incrementally build diagrams and validate against Mermaid syntax rules
Example Use Cases
- Flowchart showing an onboarding workflow
- Sequence diagram detailing API authentication steps
- Class diagram representing a microservice data model
- ER diagram illustrating relational database relationships
- Gantt chart outlining a project sprint timeline
