Configuration

YAML Spec Format

Every diagram starts with a YAML spec file. The top-level fields are:

type: flow          # flow | gantt | timeline | quadrant
title: My Diagram   # Optional title displayed on the diagram
theme: default      # Optional theme override

Flow Diagrams

Flow diagrams have nodes and edges:

type: flow
title: Deployment Pipeline
nodes:
  - id: build
    label: Build
    shape: rectangle    # rectangle, circle, diamond, hexagon
    color: "#22d3ee"    # Optional custom color
    icon: docker        # Optional brand icon
  - id: test
    label: Test Suite
    icon: github-actions
  - id: deploy
    label: Production
    icon: aws
edges:
  - from: build
    to: test
    label: "on success"
  - from: test
    to: deploy
    label: "all pass"
    style: dashed       # solid, dashed, dotted

Node Properties

Property	Type	Description
id	string	Unique identifier (required)
label	string	Display text (required)
shape	string	Node shape: rectangle, circle, diamond, hexagon
color	string	Hex color for the node
icon	string	Brand icon name

Edge Properties

Property	Type	Description
from	string	Source node ID (required)
to	string	Target node ID (required)
label	string	Edge label text
style	string	Line style: solid, dashed, dotted

Gantt Charts

type: gantt
title: Q1 Roadmap
tasks:
  - id: design
    label: Design Phase
    start: 2025-01-01
    end: 2025-01-15
  - id: build
    label: Build Phase
    start: 2025-01-16
    end: 2025-02-15
    depends: design
  - id: launch
    label: Launch
    start: 2025-02-16
    end: 2025-02-16
    milestone: true

Timeline

type: timeline
title: Product History
events:
  - date: "2024-01"
    title: v0.1 Released
    description: Initial release with flow diagrams
  - date: "2024-06"
    title: v0.2 Released
    description: Added Gantt charts and themes
  - date: "2025-01"
    title: v0.3 Released
    description: Timeline and quadrant support

Quadrant Charts

type: quadrant
title: Technology Radar
x_axis: Effort
y_axis: Impact
quadrants:
  - label: Quick Wins
  - label: Big Bets
  - label: Fill-Ins
  - label: Money Pit
items:
  - label: Caching
    x: 0.2
    y: 0.8
  - label: Rewrite
    x: 0.9
    y: 0.9
  - label: Lint Rules
    x: 0.1
    y: 0.2

Themes

Use --list-themes to see all available themes. Some popular ones:

Theme	Description
default	Clean, minimal dark theme
light	Light background with dark nodes
neon	Bright colors on dark background
pastel	Soft, muted colors
monochrome	Grayscale only
ocean	Blue-toned palette
forest	Green-toned palette
sunset	Warm orange/red palette

Apply a theme:

diagrams render spec.yaml --theme neon -o output.svg

Icons

diagrams supports multiple icon libraries with over 600 icons total. Use --list-icons to see all available icons.

Icon Types

Prefix	Library	Count	Description
(none)	Simple Icons	100+	Brand and technology logos by name
geist:	Geist Icons	541	Clean, minimal icons from Vercel's design system
aws:	AWS Icons	varies	Amazon Web Services service icons
gcp:	GCP Icons	varies	Google Cloud Platform service icons
favicon:	Favicons	any	Auto-fetched favicons from any domain
(emoji)	Emoji	any	Any emoji character

Simple Icons (Brand Logos)

Reference brand icons directly by name. Common icons include:

aws, gcp, azure, kubernetes, docker, github, gitlab, react, vue, angular, nodejs, python, rust, go, postgresql, redis, mongodb, kafka, nginx, cloudflare

nodes:
  - id: api
    label: API Gateway
    icon: aws
  - id: db
    label: Database
    icon: postgresql

Geist Icons

541 icons from the Vercel Geist design system. These are clean, minimal line icons that work well for technical and business diagrams. Use the geist: prefix:

nodes:
  - id: auth
    label: Auth Service
    icon: geist:shield
  - id: users
    label: User DB
    icon: geist:database
  - id: api
    label: API Server
    icon: geist:terminal
  - id: notify
    label: Notifications
    icon: geist:bell

Common Geist icons include:

geist:user, geist:database, geist:terminal, geist:settings, geist:shield, geist:globe, geist:mail, geist:bell, geist:search, geist:file, geist:folder, geist:cloud, geist:server, geist:lock, geist:key, geist:zap, geist:layers, geist:git-branch, geist:code, geist:cpu

Cloud Provider Icons

Use prefixed names for AWS and GCP service icons:

nodes:
  - id: lambda
    label: Lambda Function
    icon: aws:lambda
  - id: storage
    label: Cloud Storage
    icon: gcp:cloud-storage

Favicons

Fetch any website's favicon automatically:

nodes:
  - id: docs
    label: Documentation
    icon: favicon:docs.example.com

Emoji Icons

Use any emoji character directly:

nodes:
  - id: start
    label: Begin
    icon: "\U0001F680"