Mermaid

Purpose: Visual diagramming tool for creating flowcharts, sequence diagrams, architecture diagrams, and more in Docusaurus documentation.

Last verified: December 2025

Overview

Mermaid is a diagramming and charting tool that uses text-based syntax to create diagrams. Docusaurus supports Mermaid diagrams via @docusaurus/theme-mermaid and can be used in any Markdown file.

Usage

Add Mermaid diagrams using code blocks with the mermaid language:

```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

Diagram Types

Quick navigation to all diagram types:

Basic Diagrams: Flowcharts • Sequence Diagrams • Class Diagrams • State Diagrams • Entity Relationship Diagrams

Charts & Visualizations: Gantt Charts • Pie Charts • User Journey • Quadrant Chart • Radar Diagrams • Treemap Diagrams

Specialized Diagrams: Requirement Diagram • GitGraph • C4 Diagrams • Mindmaps • Timeline

Flow & Process: Sankey Diagrams • Block Diagrams • Kanban Diagrams • Architecture Diagrams

Experimental: ZenUML • XY Chart • Packet Diagram

Flowcharts

Description: Flowcharts are the most basic and commonly used diagram type in Mermaid. They represent processes, workflows, or algorithms using nodes and connections.

Use Cases:

Process flows and workflows
Decision trees and algorithms
System architecture overviews
Business process documentation
User journey flows

Nuances:

Supports multiple directions: TD/TB (top-down), BT (bottom-up), LR (left-right), RL (right-left)
Various node shapes: rectangles, diamonds (decisions), circles, cylinders (databases), etc.
Can use subgraphs to group related nodes
Automatic layout by default (Dagre algorithm), or ELK layout for complex diagrams
Supports styling with CSS classes and inline styles

Syntax:

graph TD
    User[User visits pacing.agency] --> GTM{GTM Loaded?}
    GTM -->|Yes| Termly[Termly CMP checks consent]
    GTM -->|No| Wait[Wait for GTM]
    Wait --> GTM
    Termly --> Consent{Consent given?}
    Consent -->|Yes| Track[Fire tracking tags]
    Consent -->|No| Block[Block tracking tags]
    Track --> sGTM[sGTM processes events]
    sGTM --> GA4[Send to GA4]
    sGTM --> BigQuery[Log to BigQuery]
    sGTM --> Ads[Send to ad platforms]

Sequence Diagrams

Description: Sequence diagrams show interactions between objects or components over time, displaying the order of messages exchanged.

Use Cases:

API interactions and request/response flows
System component communication
User interaction flows
Database transaction sequences
Microservice communication patterns

Nuances:

Participants are defined at the start and can be actors, systems, or components
Supports loops, alt/else blocks, and notes
Arrow types indicate message direction: ->> (solid), -->> (dashed)
Activation boxes show when a participant is active
Can include notes on the left or right of participants

Syntax:

sequenceDiagram
    participant User
    participant Webflow as Webflow Site
    participant GTM as GTM Web Container
    participant sGTM as sGTM Server
    participant GA4 as Google Analytics 4
    participant BigQuery as BigQuery
    
    User->>Webflow: Visits pacing.agency
    Webflow->>GTM: Load GTM-PGPK24VR
    GTM->>GTM: Check Termly consent
    GTM->>sGTM: Send event to GTM-NHVBMP3D
    sGTM->>GA4: Forward to GA4 (G-TPFS2Z0HNJ)
    sGTM->>BigQuery: Log to pacingeventssgtm1
    sGTM->>sGTM: Process for ad platforms
    sGTM-->>GTM: Event processed
    GTM-->>User: Page loaded

Class Diagrams

Description: Class diagrams represent the structure of object-oriented systems, showing classes, their attributes, methods, and relationships.

Use Cases:

Object-oriented system design
Database schema design
API structure documentation
Code architecture visualization
Inheritance and composition relationships

Nuances:

Supports classes, interfaces, and abstract classes
Shows relationships: inheritance (<|--), composition (*--), aggregation (o--), association (-->)
Can include visibility modifiers: + (public), - (private), # (protected)
Supports generic types and annotations
Can group classes into packages or namespaces

Syntax:

classDiagram
    class WebflowCMSCollection {
        +String id
        +String name
        +String slug
        +getItems()
        +createItem()
    }
    class Service {
        +String name
        +String slug
        +String category
        +Array deliverables
        +RichText description
    }
    class CaseStudy {
        +String name
        +String slug
        +Array kpis
        +Image mainImage
        +linkToService()
    }
    class Tool {
        +String name
        +String slug
        +String category
        +Color brandColor
        +linkToServices()
    }
    WebflowCMSCollection <|-- Service
    WebflowCMSCollection <|-- CaseStudy
    WebflowCMSCollection <|-- Tool
    Service "1" --> "*" CaseStudy : showcases
    Service "1" --> "*" Tool : uses

State Diagrams

Description: State diagrams (also called state machines) show the different states an object or system can be in and the transitions between them.

Use Cases:

System state management
Workflow state transitions
User interface state flows
Process lifecycle documentation
Game state machines

Nuances:

States can be simple, composite (nested), or concurrent
Transitions can have guards, events, and actions
Supports history states (shallow and deep)
Can define initial and final states
Supports fork and join for concurrent states

Syntax:

stateDiagram-v2
    [*] --> PageLoad
    PageLoad --> GTMLoaded: GTM container loads
    GTMLoaded --> ConsentCheck: Termly CMP active
    ConsentCheck --> TrackingEnabled: User consents
    ConsentCheck --> TrackingBlocked: User denies
    TrackingEnabled --> EventFired: User action
    EventFired --> sGTMProcessed: Event sent to server
    sGTMProcessed --> GA4Logged: Forwarded to GA4
    sGTMProcessed --> BigQueryStored: Logged to dataset
    GA4Logged --> [*]
    BigQueryStored --> [*]
    TrackingBlocked --> [*]

Entity Relationship Diagrams

Description: ER diagrams visualize the structure of databases, showing entities (tables), their attributes (columns), and relationships between them.

Use Cases:

Database schema design
Data modeling
Database documentation
Relationship mapping
Data architecture planning

Nuances:

Entities are represented as rectangles with attributes listed inside
Relationships show cardinality: ||--|| (one-to-one), ||--o{ (one-to-many), }o--o{ (many-to-many)
Attributes can be marked as keys, required, or optional
Supports weak entities and identifying relationships
Can show attribute types and constraints

Syntax:

erDiagram
    SERVICE ||--o{ CASE-STUDY : showcases
    SERVICE ||--o{ SUB-SERVICE : contains
    SERVICE ||--o{ TOOL : uses
    SERVICE ||--o{ FAQ : answers
    CASE-STUDY }o--o{ CLIENT : features
    CASE-STUDY }o--|| SERVICE : demonstrates
    TOOL }o--|| SERVICE : supports
    FAQ }o--|| SERVICE : relates_to
    SERVICE {
        string name PK
        string slug
        string category
        array deliverables
        richText description
    }
    CASE-STUDY {
        string name PK
        string slug
        array kpis
        image mainImage
        richText body
    }
    TOOL {
        string name PK
        string slug
        string category
        color brandColor
        image icon
    }
    FAQ {
        string question PK
        string shortAnswer
        richText longAnswer
        int sortOrder
    }

Gantt Charts

Description: Gantt charts are project management tools that visualize project schedules, showing tasks, their durations, dependencies, and milestones over time.

Use Cases:

Project planning and scheduling
Resource allocation
Timeline visualization
Milestone tracking
Sprint planning

Nuances:

Tasks can be marked as done, active, or crit (critical path)
Supports task dependencies using after keyword
Can exclude specific dates (e.g., weekends, holidays)
Supports sections to group related tasks
Date format is configurable (YYYY-MM-DD by default)
Can show progress percentages and task priorities

Syntax:

gantt
    title Tech Stack Documentation Project
    dateFormat YYYY-MM-DD
    section Documentation Setup
    Create architecture.md    :a1, 2024-12-01, 5d
    Setup Docusaurus         :a2, after a1, 7d
    Implement auto-sync      :a3, after a2, 3d
    section Tool Documentation
    Document Webflow CMS     :b1, after a3, 10d
    Document GTM setup      :b2, after b1, 8d
    Document n8n workflows  :b3, after b2, 7d
    section Deployment
    Configure Cloudflare Pages :c1, after a2, 5d
    Deploy to docs.pacing.agency :c2, after b3, 2d

Pie Charts

Description: Pie charts display proportional data as slices of a circle, where each slice's size represents its proportion of the whole.

Use Cases:

Budget allocation visualization
Market share representation
Survey results
Category distribution
Resource allocation breakdown

Nuances:

Values are automatically calculated as percentages
Supports up to 12 different slices with automatic color assignment
Can include a title and legend
Values can be displayed as percentages or raw numbers
Supports custom styling for individual slices

Syntax:

pie title Monthly Event Distribution
    "Page Views" : 45000
    "Form Submissions" : 1200
    "Video Plays" : 8500
    "Button Clicks" : 3200
    "Scroll Depth" : 18000

User Journey

Description: User journey diagrams map out the steps a user takes to accomplish a goal, showing their experience across different stages and touchpoints.

Use Cases:

Customer experience mapping
User onboarding flows
Product usage journeys
Service design
UX research documentation

Nuances:

Organized into sections representing different stages
Each step has a score (1-5) indicating satisfaction or importance
Can include multiple actors (users, systems, etc.)
Supports rich text descriptions for each step
Automatically uses different colors for different sections

Syntax:

journey
    title Lead Qualification Process
    section Initial Contact
      Form submission captured: 5: Webflow, GTM
      Event sent to sGTM: 4: GTM, sGTM
      Contact created in CRM: 5: n8n, TwentyCRM
    section Qualification
      Email sent to lead: 4: n8n, Email Service
      Lead views email: 3: Lead, Email Service
      Lead clicks CTA: 5: Lead, Email Service
    section Conversion
      Meeting scheduled: 5: Lead, Calendar
      Sales team notified: 4: n8n, Slack
      Deal created in CRM: 5: n8n, TwentyCRM

Quadrant Chart

Description: Quadrant charts (also called 2x2 matrices) plot items on a two-dimensional grid divided into four quadrants, useful for prioritization and strategic planning.

Use Cases:

Feature prioritization (impact vs effort)
Risk assessment (probability vs impact)
Strategic planning matrices
Campaign analysis (reach vs engagement)
Technology evaluation

Nuances:

X and Y axes are configurable with custom labels
Each quadrant can have a descriptive label
Points are plotted using [x, y] coordinates (0.0 to 1.0)
Supports custom quadrant labels and colors
Useful for Eisenhower matrix, BCG matrix, and similar frameworks

Syntax:

quadrantChart
    title Marketing Tool Priority Matrix
    x-axis Low Effort --> High Effort
    y-axis Low Value --> High Value
    quadrant-1 Quick Wins
    quadrant-2 Strategic Projects
    quadrant-3 Time Sinks
    quadrant-4 Fill-Ins
    GTM Setup: [0.3, 0.8]
    sGTM Migration: [0.7, 0.9]
    BigQuery Integration: [0.6, 0.7]
    n8n Workflows: [0.4, 0.6]
    Webflow CMS: [0.2, 0.5]
    Cloudflare Pages: [0.3, 0.4]

Requirement Diagram

Description: Requirement diagrams document system requirements and their relationships to system elements, showing how requirements are satisfied by design elements.

Use Cases:

Requirements traceability
System design documentation
Compliance mapping
Quality assurance planning
Requirements validation

Nuances:

⚠️ Experimental Feature: Requirement diagrams are experimental and may not work in all Mermaid versions. If you encounter errors, use a flowchart diagram instead.
Requirements can have properties: id, text, risk, verifymethod, owner
Elements can be functional or technical
Relationships show how requirements are satisfied by elements
Supports risk levels and verification methods

Note: Due to parsing issues with requirement diagrams in some Mermaid versions, the examples below may not render correctly. Consider using a flowchart diagram as an alternative for requirements documentation.

Example - Tracking & Analytics Requirements:

Note: Requirement diagrams are currently experimental and have parsing issues in Mermaid. Use the flowchart alternative shown above for requirements documentation.

GitGraph (Git) Diagram

Description: GitGraph diagrams visualize Git branching workflows, showing commits, branches, merges, and the history of a repository.

Use Cases:

Git workflow documentation
Branching strategy visualization
Release process documentation
Code review process flows
Team collaboration patterns

Nuances:

Note: If GitGraph doesn't render, ensure you're using a recent version of Mermaid that supports git diagrams.
Commits are created with commit id: "message"
Branches are created with branch name and switched with checkout name
Merges are performed with merge branchName
Supports tags, cherry-picks, and rebases
Can show commit messages and branch labels

Syntax:

gitGraph
    commit id: "Initial tech stack docs"
    commit id: "Add Webflow CMS docs"
    branch feature/gtm-tracking
    checkout feature/gtm-tracking
    commit id: "Document GTM web container"
    commit id: "Add sGTM server docs"
    checkout main
    commit id: "Update architecture.md"
    merge feature/gtm-tracking
    commit id: "Add n8n workflow docs"
    branch feature/docusaurus-sync
    checkout feature/docusaurus-sync
    commit id: "Implement auto-sync script"
    checkout main
    merge feature/docusaurus-sync
    commit id: "Deploy to Cloudflare Pages"

C4 Diagrams

Description: C4 diagrams model software architecture at different levels of abstraction (Context, Container, Component, Code), following the C4 model for visualizing software systems.

Use Cases:

Software architecture documentation
System design communication
Technical documentation
Architecture decision records
System context visualization

Nuances:

⚠️ Experimental Feature: C4 diagrams are experimental. The syntax and properties can change in future releases. Mermaid's C4 diagram syntax is compatible with PlantUML.
Five diagram types: System Context, Container, Component, Dynamic, and Deployment
Uses fixed styling (CSS colors), so themes don't affect appearance
Layout is semi-automatic based on statement order
Supports boundaries (Enterprise, System, Container) to group elements
Can customize element and relationship styles with UpdateElementStyle and UpdateRelStyle

C4 diagrams are used to visualize software architecture at different levels of abstraction. Five types of C4 charts are supported:

System Context (C4Context) - High-level view showing the system and its relationships with users and other systems
Container diagram (C4Container) - Shows containers (applications, data stores, etc.) within a system
Component diagram (C4Component) - Shows components within a container
Dynamic diagram (C4Dynamic) - Shows the flow of data or control between components
Deployment diagram (C4Deployment) - Shows how containers are deployed to infrastructure

Example - System Context Diagram:

Example - Container Diagram:

Key Syntax Elements:

Person(alias, label, ?descr) - Represents a person/user
System(alias, label, ?descr) - Represents a system
System_Ext(alias, label, ?descr) - External system
Container(alias, label, ?techn, ?descr) - Application container
ContainerDb(alias, label, ?techn, ?descr) - Database container
Rel(from, to, label, ?techn) - Relationship between elements
BiRel(from, to, label) - Bidirectional relationship
UpdateElementStyle(element, $bgColor, $fontColor, $borderColor) - Customize element styling
UpdateRelStyle(from, to, $textColor, $lineColor, $offsetX, $offsetY) - Customize relationship styling

Note: C4 diagrams use fixed styling (CSS colors), so different themes don't affect them. The layout is semi-automatic based on the order of statements. For complete syntax reference, see the C4-PlantUML documentation.

Mindmaps

Description: Mindmaps are hierarchical diagrams that organize information around a central concept, with branches representing related ideas or subtopics.

Use Cases:

Brainstorming and idea organization
Knowledge mapping
Project planning
Study notes
Concept visualization

Nuances:

Starts with a root node (usually in double parentheses)
Uses indentation to create hierarchy
Automatically arranges nodes in a radial layout
Supports multiple levels of nesting
Can include icons and emojis in node labels

Syntax:

mindmap
  root((Documentation Structure))
    Tools
      GTM
        Web Container
        Server Container
      Webflow
        CMS Collections
        Designer API
      n8n
        Workflows
        Self-hosted
    Architecture
      Tracking Flow
      Data Pipeline
      Infrastructure
    Guides
      Server-side Tracking
      Marketing Tech Optimization
    Resources
      Scripts
      Automation Files
      API Schemas

Timeline

Description: Timeline diagrams display events, milestones, or activities in chronological order, showing when things happened or will happen.

Use Cases:

Project timelines
Historical event documentation
Release planning
Roadmap visualization
Event scheduling

Nuances:

Organized by time periods (years, quarters, months, etc.)
Each period can have multiple events listed with indentation
Supports titles and descriptions for each event
Can show parallel timelines or multiple tracks
Useful for showing project phases and milestones

Syntax:

timeline
    title Pacing Agency Tech Stack Evolution
    section 2024 Q1
        January : Webflow CMS setup
                 : Initial GTM container deployment
        February : Termly CMP integration
        March : GA4 configuration
    section 2024 Q2
        April : sGTM server setup on Stape
        May : BigQuery data warehouse connection
        June : n8n automation platform deployment
    section 2024 Q3
        July : TwentyCRM integration
        August : Cloudflare Pages deployment
        September : Docusaurus documentation site
    section 2024 Q4
        October : Server-side tracking migration
        November : Automated workflow implementation
        December : Tech stack documentation complete

ZenUML

Description: ZenUML-style sequence diagrams provide an alternative syntax for sequence diagrams, though this is not standard Mermaid syntax.

Use Cases:

Alternative sequence diagram syntax
Simplified interaction documentation
API flow documentation

Nuances:

⚠️ Note: ZenUML is a separate tool, not standard Mermaid. Use sequence diagrams instead for similar functionality.
Uses arrow notation: -> for synchronous, --> for return
More compact syntax than standard sequence diagrams
Not officially supported in Mermaid - use standard sequence diagrams for compatibility

Syntax (using Sequence Diagram instead):

Sankey Diagrams

Description: Sankey diagrams visualize flow or transfer between nodes, where the width of the connections represents the quantity or magnitude of flow.

Use Cases:

Energy flow visualization
Data flow analysis
Resource allocation tracking
Website traffic flow
Process flow with quantities

Nuances:

⚠️ Experimental Feature (v10.3.0+): Sankey diagrams are experimental. The syntax is very close to plain CSV but may be extended in the future.
Uses CSV format: source,target,value (three columns)
Supports empty lines for visual spacing
Link colors can be set to source, target, gradient, or a hex color
Node alignment options: justify, center, left, right
Configurable width, height, and visual styling

A Sankey diagram visualizes flow from one set of values to another. The things being connected are called nodes and the connections are called links.

Example:

Syntax:

The syntax uses CSV format with 3 columns: source,target,value

sankey
    %% source,target,value
    Electricity grid,Over generation / exports,104.453
    Electricity grid,Heating and cooling - homes,113.726
    Electricity grid,H2 conversion,27.14

CSV Features:

Empty lines: Allowed for visual purposes (without comma separators)
Commas in text: Wrap in double quotes: "Heating and cooling, homes",193.026
Double quotes in text: Use pairs: "Heating and cooling, ""homes""",193.026

Configuration Options:

sankey: {
  width: 800,
  height: 400,
  linkColor: 'source',  // 'source', 'target', 'gradient', or hex color
  nodeAlignment: 'left', // 'justify', 'center', 'left', 'right'
}

Link Coloring:

source - Link uses source node color
target - Link uses target node color
gradient - Smooth transition between source and target colors
Hex color code (e.g., #a1a1a1)

Node Alignment:

justify - Distribute nodes evenly
center - Center nodes
left - Align nodes to the left
right - Align nodes to the right

XY Chart

Description: XY charts (also called Cartesian charts) plot data points on X and Y axes, supporting both bar and line chart types in a single diagram.

Use Cases:

Time series data visualization
Sales trends
Performance metrics over time
Comparative data analysis
Multi-series data plotting

Nuances:

⚠️ Beta Feature: XY charts are in beta and may not be available in all Mermaid versions. Use a Gantt chart or external charting library if this doesn't render.
Supports both bar and line chart types simultaneously
X-axis can be categorical (labels) or numeric
Y-axis is numeric with configurable range
Can display multiple data series
Useful for showing trends and comparisons over time

Syntax (using Gantt chart as alternative if XY Chart doesn't render):

Block Diagrams

Description: Block diagrams provide full control over block positioning, unlike flowcharts which use automatic layout. They're ideal for representing complex systems where precise positioning matters.

Use Cases:

Software architecture with specific layouts
Network diagrams
Process flowcharts with custom positioning
System design with spatial relationships
Educational diagrams requiring precise placement

Nuances:

Author has full control over block positions (unlike automatic flowchart layout)
Supports multiple columns and custom block widths
Various block shapes: rectangles, circles, cylinders, diamonds, etc.
Can create composite blocks (blocks within blocks)
Supports block arrows and space blocks for layout control
Useful when automatic layout doesn't produce desired results

Basic Structure:

Multi-Column Layout:

Example - System Architecture:

Key Features:

Column Control: Define number of columns with columns N
Block Width: Span multiple columns with blockId:width (e.g., a:2 spans 2 columns)
Composite Blocks: Nest blocks within blocks using block:groupId:width ... end
Block Shapes: Various shapes available:
- id["Label"] - Rectangle (default)
- id("Label") - Round edges
- id(["Label"]) - Stadium shape
- id[["Label"]] - Subroutine
- id[("Label")] - Cylindrical (database)
- id(("Label")) - Circle
- id>"Label"] - Asymmetric
- id{"Label"} - Rhombus (decision)
- id{{"Label"}} - Hexagon
- id[/"Label"/] - Parallelogram
- id[\"Label"\]] - Trapezoid

Block Arrows:

Space Blocks:

Connecting Blocks:

Styling:

Class Styling:

Packet Diagram

Description: Packet diagrams visualize the structure of network packets, showing the layout of headers, fields, and data segments in network protocols.

Use Cases:

Network protocol documentation
Packet structure visualization
Network engineering documentation
Protocol analysis
Educational network diagrams

Nuances:

⚠️ Beta Feature: Packet diagrams are in beta and may not be available. Use a flowchart or table to represent packet structure if this doesn't render.
Shows bit ranges and field names (e.g., 0-15: Source Port)
Useful for TCP/IP, UDP, and other protocol documentation
Can represent packet headers and data segments
Alternative: Use flowcharts or tables if this diagram type doesn't render

Syntax (using Packet Diagram):

packet
    title sGTM Event Payload Structure
    0-31: "Event Timestamp"
    32-63: "Client ID"
    64-95: "Session ID"
    96-127: "Page URL"
    128-159: "Event Name"
    160-191: "Event Parameters"
    192-223: "User Agent"
    224-255: "IP Address (hashed)"
    256-287: "Consent State"
    288-319: "GTM Container ID"

Kanban Diagrams

Description: Kanban diagrams visualize tasks moving through different stages of a workflow, similar to physical Kanban boards used in agile project management.

Use Cases:

Project management and task tracking
Sprint planning and backlog management
Workflow visualization
Team task organization
Agile development boards

Nuances:

Columns represent workflow stages (e.g., Todo, In Progress, Done)
Tasks are listed under their respective columns
Supports task metadata: assigned, ticket, priority (Very High, High, Low, Very Low)
Can configure ticketBaseUrl for clickable ticket links
Proper indentation is crucial - tasks must be indented under columns
Each column and task needs a unique identifier

Basic Syntax:

Defining Columns:

Columns represent workflow stages. Each column needs a unique identifier and title:

Adding Tasks:

Tasks are listed under their respective columns with indentation:

Task Metadata:

Add metadata to tasks using @{ ... } syntax:

Supported Metadata Keys:

assigned - Who is responsible for the task
ticket - Links to a ticket or issue number
priority - Task urgency: 'Very High', 'High', 'Low', 'Very Low'

Full Example with Metadata:

Configuration:

Set ticketBaseUrl in the config block to create clickable ticket links:

---
config:
  kanban:
    ticketBaseUrl: 'https://yourproject.atlassian.net/browse/#TICKET#'
---

The #TICKET# placeholder is replaced with the ticket value from task metadata.

Important Notes:

Proper indentation is crucial - tasks must be indented under their parent columns
Each column and task needs a unique identifier
Column titles can be written as columnId[Title] or just [Title] (auto-generated ID)

Architecture Diagrams

Description: Architecture diagrams visualize cloud and CI/CD infrastructure, showing services, resources, and their relationships in deployment environments.

Use Cases:

Cloud infrastructure documentation
CI/CD pipeline visualization
Microservices architecture
Deployment architecture
System resource mapping

Nuances:

⚠️ Beta Feature (v11.1.0+): Architecture diagrams are used to show relationships between services and resources commonly found within Cloud or CI/CD deployments.
Consists of groups, services, edges, and junctions
Default icons: cloud, database, disk, internet, server
Can use custom icons from iconify.design by registering icon packs
Edge directions specified with L (left), R (right), T (top), B (bottom)
Supports arrows on edges and group boundaries
Junctions allow 4-way connections between services

Architecture diagrams consist of groups, services, edges, and junctions. Services are connected by edges, and related services can be placed within groups.

Example:

Groups:

Groups organize related services. Syntax: group {group id}({icon name})[{title}] (in {parent id})?

Services:

Services represent individual components. Syntax: service {service id}({icon name})[{title}] (in {parent id})?

Default Icons:

cloud - Cloud service
database - Database
disk - Storage/disk
internet - Internet/gateway
server - Server

Custom Icons:

You can use any icon from iconify.design by registering an icon pack and using name:icon-name format:

Edges:

Edges connect services. Syntax: {serviceId}{{group}}?:{T|B|L|R} {<}?--{>}? {T|B|L|R}:{serviceId}{{group}}?

Edge Direction:

Specify which side of the service the edge connects to using L (left), R (right), T (top), or B (bottom):

Arrows:

Add arrows with < (left side) and/or > (right side):

Edges from Groups:

Use {group} modifier to create edges from group boundaries:

Junctions:

Junctions act as 4-way connection points:

Radar Diagrams

Description: Radar diagrams (also known as spider charts, star charts, or polar charts) plot multi-dimensional data in a circular format, with each axis representing a different dimension.

Use Cases:

Performance comparison across multiple metrics
Skills assessment
Product feature comparison
Quality evaluation
Multi-criteria decision analysis

Nuances:

⚠️ Beta Feature (v11.6.0+): Radar diagrams plot low-dimensional data in a circular format.
Axes are defined with axis keyword and can have custom labels
Curves represent different entities being compared
Values can be specified as lists {1,2,3} or key-value pairs {axis1: 10, axis2: 20}
Supports max and min for scaling
Graticule can be circle (default) or polygon
Configurable ticks, margins, and curve styling
Supports theme variables for colors (cScale0 through cScale11)

Example:

Syntax:

radar-beta
  title Data Platform Capabilities
  axis realtime["Real-time Processing"], storage["Data Storage"]
  axis query["Query Performance"], cost["Cost Efficiency"]
  axis integration["API Integration"], compliance["GDPR Compliance"]
  curve ga4["GA4"]{4, 3, 4, 5, 5, 4}
  curve bigquery["BigQuery"]{5, 5, 5, 3, 5, 4}
  curve webflow["Webflow CMS"]{2, 4, 3, 4, 4, 3}
  graticule polygon
  max 5

Key Elements:

title: Optional title at the top of the diagram
axis: Define axes with ID and optional label. Multiple axes can be defined: axis id1["Label1"], id2["Label2"]
curve: Define data points. Values can be a list {1, 2, 3} or key-value pairs {axis3: 30, axis1: 20}
max/min: Scale the diagram (default min is 0)
graticule: circle (default) or polygon
ticks: Number of concentric circles/polygons (default: 5)
showLegend: Show or hide legend (default: true)

Configuration Options:

---
config:
  radar:
    width: 600
    height: 600
    marginTop: 50
    marginBottom: 50
    marginLeft: 50
    marginRight: 50
    axisScaleFactor: 1
    axisLabelFactor: 1.05
    curveTension: 0.17
  themeVariables:
    radar:
      axisColor: "#000000"
      axisStrokeWidth: 1
      axisLabelFontSize: 12
      curveOpacity: 0.7
      curveStrokeWidth: 2
      graticuleColor: "#000000"
      graticuleOpacity: 0.5
      graticuleStrokeWidth: 1
      legendBoxSize: 10
      legendFontSize: 14
---

Theme Variables:

Radar charts support color scales cScale${i} (where i is 0-11) for curve colors. Set these in themeVariables:

themeVariables:
  cScale0: "#FF0000"
  cScale1: "#00FF00"
  cScale2: "#0000FF"

Treemap Diagrams

Description: Treemap diagrams display hierarchical data as nested rectangles, where each rectangle's size is proportional to its value, making it easy to compare proportions across categories.

Use Cases:

Budget allocation visualization
File system disk usage
Market share analysis
Portfolio composition
Hierarchical data with size relationships

Nuances:

⚠️ Beta Feature: Treemap diagrams display hierarchical data as nested rectangles.
Hierarchy created using indentation (spaces or tabs)
Section/parent nodes: "Section Name"
Leaf nodes with values: "Leaf Name": value
Supports styling with :::class syntax
Value formatting: supports D3 format specifiers (,, $, .1f, .1%, etc.)
Configurable padding, node sizes, font sizes, and borders
Works best with natural hierarchies and positive values
Very small values may be difficult to see

Basic Example:

Hierarchical Example - Tool Usage Breakdown:

Syntax:

Section/Parent nodes: "Section Name"
Leaf nodes with values: "Leaf Name": value
Hierarchy: Created using indentation (spaces or tabs)
Styling: Use :::class syntax for custom styling

Styling with Classes:

treemap-beta
"Main"
    "A": 20
    "B":::important
        "B1": 10
        "B2": 15
    "C": 5

classDef important fill:#f96,stroke:#333,stroke-width:2px;

Configuration Options:

---
config:
  treemap:
    useMaxWidth: true
    padding: 10
    diagramPadding: 8
    showValues: true
    nodeWidth: 100
    nodeHeight: 40
    borderWidth: 1
    valueFontSize: 12
    labelFontSize: 14
    valueFormat: ','  # Thousands separator
---

Value Formatting:

The valueFormat option supports D3 format specifiers:

, - Thousands separator (default)
$ - Add dollar sign
.1f - One decimal place
.1% - Percentage with one decimal
$0,0 - Dollar sign with thousands separator
$.2f - Dollar sign with 2 decimal places

Example with Currency Formatting:

Use Cases:

Financial data (budget allocations, market shares)
File system analysis (disk space usage)
Population demographics
Product hierarchies and sales volumes
Organizational structures

Limitations:

Works best with natural hierarchies
Very small values may be difficult to see
Deep hierarchies can be challenging
Not suitable for negative values

Styling and Customization

Node Styling

Syntax:

graph TD
    A[Default] --> B[Styled Node]
    C[Another Node] --> D[Final Node]
    
    style B fill:#e1f5ff,stroke:#01579b,stroke-width:2px
    style D fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px

Subgraphs

Syntax:

graph TB
    subgraph Frontend
        A[React App]
        B[Components]
    end
    
    subgraph Backend
        C[API Server]
        D[Database]
    end
    
    A --> C
    B --> C
    C --> D

Flowchart Direction

TD or TB - Top to Bottom (default)
BT - Bottom to Top
LR - Left to Right
RL - Right to Left

Node Shapes

A[Text] - Rectangle (default)
A(Rounded) - Rounded rectangle
A{Decision} - Diamond (decision)
A((Circle)) - Circle
A([Stadium]) - Stadium shape
A[[Subroutine]] - Subroutine
A[(Database)] - Cylinder
A>Parallelogram] - Parallelogram

Arrow Types

A-->B - Solid arrow
A---B - Solid line (no arrow)
A-.->B - Dotted arrow
A-.-B - Dotted line
A==>B - Thick arrow
A==B - Thick line
A--|label|-->B - Arrow with label
A-.|label|.->B - Dotted arrow with label

Configuration

Mermaid themes are configured in docusaurus.config.ts. The Pacing Tech Stack site uses a custom theme based on the base theme with Pacing brand colours that work well in both light and dark modes.

Current Configuration:

themeConfig: {
  mermaid: {
    theme: {
      light: 'base',
      dark: 'base',
    },
    themeVariables: {
      // Light mode colours
      primaryColor: '#e1f5ff',
      primaryTextColor: '#01579b',
      primaryBorderColor: '#0277bd',
      secondaryColor: '#f3e5f5',
      tertiaryColor: '#e8f5e9',
      // ... additional theme variables
    },
    darkThemeVariables: {
      // Dark mode colours
      primaryColor: '#01579b',
      primaryTextColor: '#e1f5ff',
      // ... dark mode overrides
    },
    options: {
      maxTextSize: 50000,
    },
  },
},

Customising Individual Diagrams:

You can override the theme for specific diagrams using frontmatter:

```mermaid
---
config:
  theme: 'base'
  themeVariables:
    primaryColor: '#BB2528'
    primaryTextColor: '#fff'
---
graph TD
    A --> B
```

Available Built-in Themes:

default - Default Mermaid theme
neutral - Great for black and white documents
dark - Works well with dark-coloured elements
forest - Contains shades of green
base - The only theme that can be fully customised (used in this site)

Best Practices

Keep diagrams simple: Complex diagrams can be hard to read. Break large diagrams into smaller, focused ones.
Use meaningful labels: Clear labels make diagrams self-documenting.
Consistent styling: Use consistent colours and styles across related diagrams.
Test rendering: Always preview diagrams locally before committing.
Accessibility: Ensure diagrams are readable in both light and dark modes.

Dynamic Mermaid Component

For dynamic diagrams (e.g., with user input), use the Mermaid component:

import Mermaid from '@theme/Mermaid';

<Mermaid
  value={`graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;`}
/>

Resources

Mermaid Live Editor - Test diagrams before adding to docs
Mermaid Documentation - Complete syntax reference
Docusaurus Mermaid Docs - Docusaurus-specific guidance

Docusaurus setup: See tools/docusaurus.md
Source files: tools/, architecture.md, README.md
Docusaurus README: docusaurus/README.md

Overview​

Usage​

Diagram Types​

Flowcharts​

Sequence Diagrams​

Class Diagrams​

State Diagrams​

Entity Relationship Diagrams​

Gantt Charts​

Pie Charts​

User Journey​

Quadrant Chart​

Requirement Diagram​

GitGraph (Git) Diagram​

C4 Diagrams​

Mindmaps​

Timeline​

ZenUML​

Sankey Diagrams​

XY Chart​

Block Diagrams​

Packet Diagram​

Kanban Diagrams​

Architecture Diagrams​

Radar Diagrams​

Treemap Diagrams​

Styling and Customization​

Node Styling​

Subgraphs​

Flowchart Direction​

Node Shapes​

Arrow Types​

Configuration​

Best Practices​

Dynamic Mermaid Component​

Resources​

Related Documentation​

Overview

Usage

Diagram Types

Flowcharts

Sequence Diagrams

Class Diagrams

State Diagrams

Entity Relationship Diagrams

Gantt Charts

Pie Charts

User Journey

Quadrant Chart

Requirement Diagram

GitGraph (Git) Diagram

C4 Diagrams

Mindmaps

Timeline

ZenUML

Sankey Diagrams

XY Chart

Block Diagrams

Packet Diagram

Kanban Diagrams

Architecture Diagrams

Radar Diagrams

Treemap Diagrams

Styling and Customization

Node Styling

Subgraphs

Flowchart Direction

Node Shapes

Arrow Types

Configuration

Best Practices

Dynamic Mermaid Component

Resources

Related Documentation