Skip to main content

Docusaurus

Purpose: Documentation site for Pacing Agency tech stack. Provides a browsable, searchable interface for all tool documentation, architecture notes, and operational guides.

Last verified: December 2025

Build test: Verified auto-sync working (December 2025) - tools sync automatically on push to GitHub via prebuild hook.

Account Details​

Overview​

Docusaurus is a static site generator that transforms our Markdown documentation into a searchable, navigable website. The site automatically syncs all tools/*.md files on every build, making it easy to keep documentation up to date.

Key Features:

  • Automatic sync of all tools/*.md files into browsable docs
  • Search functionality across all documentation
  • Custom Pacing-branded theme matching pacing.agency visual style
  • Automatic deployment to Cloudflare Pages on Git push
  • MDX safety checks (escapes email addresses, handles file links, detects potential secrets)
  • Protected access via Cloudflare Access with Google OAuth authentication

Build Process​

The Docusaurus site is built automatically on every push to the main branch via Cloudflare Pages:

  1. Pre-build step: scripts/sync-tools.cjs runs automatically (via prebuild hook in package.json)

    • Reads all tools/*.md files (except README.md)
    • Strips existing frontmatter and extracts H1 headings as titles
    • Fixes MDX issues (escapes emails, converts file:// links)
    • Checks for potential API keys/secrets (logs warnings)
    • Writes transformed files to docs/tools/<tool-name>.md

  2. Build step: Docusaurus compiles the site

    • Processes all Markdown/MDX files
    • Generates static HTML/CSS/JS
    • Outputs to build/ directory

  3. Deploy step: Cloudflare Pages serves the build/ directory

Local build:

cd docusaurus
npm install
npm run build  # Runs sync + build
npm start      # Runs sync + dev server

Sync Script Behavior​

The docusaurus/scripts/sync-tools.cjs script:

  • Source of truth: tools/*.md files in the parent directory
  • Output: docusaurus/docs/tools/*.md (generated, do not edit directly)
  • Transformations:
    • Removes existing frontmatter blocks
    • Extracts first H1 heading as page title
    • Removes the H1 from body (Docusaurus uses frontmatter title)
    • Escapes email addresses: <email@domain> → &lt;email@domain&gt;
    • Converts file:// links to inline code blocks
    • Adds Docusaurus frontmatter with id, title, and source fields
  • Safety checks: Warns if JWT-like tokens are detected (doesn't fail build)
  • Exclusions: Skips tools/README.md

Important: Always edit source files in tools/, never edit generated files in docusaurus/docs/tools/ (they get overwritten on every build).

Adding Custom Pages​

Option 1: Add a tool doc (auto-synced)​

  1. Create tools/<tool-name>.md in the parent directory
  2. The sync script automatically picks it up on the next build
  3. It appears in the sidebar under "Tools"

Option 2: Create a custom Docusaurus page​

  1. Create a new file in docusaurus/docs/ (not docs/tools/)
  2. Add proper frontmatter: 
    ---
    id: my-page
    title: My Page Title
    ---

    Your content here...
  3. Update docusaurus/sidebars.ts to include it in navigation if needed

Option 3: Edit core pages​

  • docusaurus/docs/intro.md - Based on README.md (manual sync)
  • docusaurus/docs/architecture.md - Based on architecture.md (manual sync)
  • docusaurus/docs/tools.md - Tools overview page (edit directly)

Configuration​

  • Config file: docusaurus/docusaurus.config.ts
  • Sidebar: docusaurus/sidebars.ts
  • Theme: Custom CSS in docusaurus/src/css/custom.css (matches pacing.agency brand)
  • Homepage: docusaurus/src/pages/index.tsx

Dependencies​

  • Node.js >= 20.0
  • npm (comes with Node.js)
  • Dependencies managed in docusaurus/package.json

Troubleshooting​

Build fails with MDX errors​

  • Check sync script warnings for potential issues
  • Look for unescaped email addresses (<email@domain> should be &lt;email@domain&gt;)
  • Check for file:// links that need to be converted

Tools not appearing in sidebar​

  • Ensure the file is in tools/ (not docusaurus/docs/tools/)
  • Check that the filename matches *.md (not README.md)
  • Run npm run prebuild manually in docusaurus/ to see sync output

Changes not showing up locally​

  • For tools: restart dev server or run npm run prebuild
  • For custom pages: changes should hot-reload automatically

Cloudflare Pages Setup​

The site is deployed via Cloudflare Pages with automatic builds on every push to main.

Current project: techstackdocs1 (connected to Pacing-Agency/techstackdocs)

Initial Setup​

  1. Create Pages project (via Dashboard):

    • Go to Cloudflare Dashboard → Workers & Pages → Create application → Pages
    • Select "Import an existing Git repository"
    • Or create manually and connect Git later

  2. Connect GitHub repository (via Dashboard):

    • Go to Cloudflare Dashboard → Workers & Pages → [project-name]
    • Click "Connect to Git" or "Change source"
    • Select GitHub and authorize
    • Choose repository: Pacing-Agency/techstackdocs
    • Confirm branch: main

  3. Configure build settings (via Dashboard):

    • Framework preset: Docusaurus (auto-fills settings below)
    • Production branch: main
    • Build command: npm run build
    • Build directory: build
    • Root directory: docusaurus

  4. Add custom domain (via Dashboard):

    • Go to Settings → Custom domains
    • Add: docs.pacing.agency
    • DNS will be configured automatically

  5. Configure Cloudflare Access (if needed):

    • Go to Zero Trust → Access → Applications
    • Update application to point to the Pages project
    • See tools/cloudflare-access.md for details

Verified Configuration (December 2025)​

Project: techstackdocs1

  • GitHub: Pacing-Agency/techstackdocs
  • Branch: main
  • Build command: npm run build
  • Root directory: docusaurus
  • Output directory: build
  • Custom domain: docs.pacing.agency (configured via Dashboard)

Build Configuration​

SettingValue
Framework presetDocusaurus
Production branchmain
Build commandnpm run build
Build directorybuild
Root directorydocusaurus

The build process automatically:

  • Runs npm run prebuild (syncs tools/*.md files)
  • Runs npm run build (builds Docusaurus site)
  • Deploys the build/ directory

Migrating to New Repository​

If the GitHub repository is moved or renamed:

  1. Create new Pages project (or update existing):

    wrangler pages project create <project-name> --production-branch=main

  2. Connect new repository via Dashboard (GitHub OAuth required)

  3. Update build settings to match configuration above

  4. Add custom domain if needed

  5. Update Cloudflare Access application to point to new project

  6. Delete old project once verified (remove custom domain first)

Mermaid Diagrams​

Docusaurus supports Mermaid diagrams for creating visual documentation. Mermaid is enabled via @docusaurus/theme-mermaid and can be used in any Markdown file.

For comprehensive Mermaid diagram documentation, syntax examples, and best practices, see tools/mermaid.md.

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:

  1. System Context (C4Context) - High-level view showing the system and its relationships with users and other systems
  2. Container diagram (C4Container) - Shows containers (applications, data stores, etc.) within a system
  3. Component diagram (C4Component) - Shows components within a container
  4. Dynamic diagram (C4Dynamic) - Shows the flow of data or control between components
  5. 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