Make it yours: theming, config, and shipping

Per-diagram config attaches to the source itself, so it travels with the diagram. The modern way is a frontmatter block: YAML between --- fences, before the diagram type line. The older way is the init directive - a %%{init: ...}%% comment with JSON. Both work in v11; frontmatter is what current docs teach and what reads best in review.

And here it is live - this block overrides the page's own theme with forest, proving the config travels inside the source:

---
config:
  theme: forest
---
flowchart LR
  a[Same Nova source] --> b{Theme?}
  b -->|forest| c[Green diagram]
  b -->|none| d[Page default]

Time to confess. Every pink diagram across all six sessions is stock mermaid - no CSS hacks, no SVG editing. The page initializes mermaid with theme: base plus pink themeVariables, and every diagram wears them automatically. Here is that exact trick, self-contained in one block:

---
config:
  theme: base
  themeVariables:
    primaryColor: '#FFEFF5'
    primaryBorderColor: '#D6246E'
    lineColor: '#C05585'
---
flowchart LR
  src[App events] --> ing[Ingestion]
  ing --> dw[(Warehouse)]
  dw --> bi[Dashboards]

Three variables did most of that work. The heavy hitters: primaryColor (node fill), primaryBorderColor, primaryTextColor, lineColor (edges), fontFamily, plus secondary/tertiary sets for subgraphs and second-class nodes. Mermaid derives sensible values for everything you do not set.

Contrast check your choices: light fill + dark border + near-black text survives projectors, printers, and colorblind readers. Diagram-specific variables (sequence actors, gantt bars) are listed per diagram in the theming docs.

The grammar has four words: group (a labeled container), service (a box with an icon), junction (an invisible split point), and edges that name which SIDE they leave and enter: ing:R --> L:dw means "from ingestion's right side into the warehouse's left side". You place things; mermaid routes.

architecture-beta
  group nova(cloud)[Nova platform]
  service gw(internet)[Event gateway]
  service ing(server)[Ingestion] in nova
  service dw(database)[Warehouse] in nova
  service bi(server)[Dashboards] in nova
  service ml(disk)[Feature store] in nova
  junction fan in nova

  gw:R --> L:ing
  ing:R --> L:dw
  dw:R -- L:fan
  fan:T -- B:bi
  fan:B -- T:ml

• Icons: five ship built in - cloud, database, disk, internet, server. Thousands more via iconify packs when you control the renderer.
• Sides are the layout tool: L R T B on each edge end is how you sculpt the arrangement - there is no direction flag like a flowchart's LR.
• Beta means beta: the keyword is literally architecture-beta. Keep labels plain (letters, numbers, spaces) and expect the syntax to evolve.

C4 is a documentation METHOD (Context, Container, Component, Code) with its own boxy visual convention. Mermaid implements it - C4Context and friends - but flags it experimental: the docs say syntax and properties can change in future releases. Use it when your org already speaks C4; keep examples small.

C4Context
  title Nova in context
  Person(analyst, "Analyst", "Reads dashboards daily")
  System(nova, "Nova platform", "Events to warehouse to insight")
  System_Ext(crm, "CRM", "Nightly export source")
  Rel(analyst, nova, "Uses")
  Rel(crm, nova, "Sends data")

mmdc is the official command-line renderer. It spins up headless Chromium via puppeteer, renders exactly what the browser would, and writes the file format you asked for - the extension picks it.

No npm on the machine? The maintained docker image skips the install entirely: docker run --rm -v $(pwd):/data minlag/mermaid-cli -i nova.mmd -o nova.svg. Because puppeteer downloads a browser, the first install is heavy - normal, not broken.

The pattern is one job: when a .mmd file changes, run mmdc over it and publish the output. Two flavors:

• Commit artifacts back - the job renders docs/*.mmd to docs/img/*.svg and commits them, so even non-mermaid surfaces (wikis, emails, slides) get current images.
• Attach to the docs build - MkDocs or Docusaurus renders fences at build time; mmdc covers only the exports slides need.

Everything this course does - live rendering, pink theme, all of it - starts with one ES module import and one initialize call. Here is the skeleton, ready to steal:

securityLevel matters: strict (the default) sanitizes labels and disables click interactions - right for pages that render other people's diagrams. loose enables clicks and HTML labels - only for sources you fully trust. This page runs strict.

An SVG diagram is invisible to a screen reader unless you say what it means. Two lines fix that in ANY diagram type, right after the type keyword:

flowchart LR
  accTitle: Nova high level flow
  accDescr: App events flow through ingestion into the warehouse which feeds dashboards
  src[App events] --> ing[Ingestion]
  ing --> dw[(Warehouse)]
  dw --> bi[Dashboards]

Multi-line descriptions use accDescr { ... } with no colon. Rule of thumb: the description should let someone who cannot see the diagram repeat its point in a meeting.

When a host renders your fence, the HOST picks the mermaid version and config - GitHub ignores your custom themes and strips click interactions, and its mermaid version may lag features like architecture-beta. So:

• Fence it when the diagram lives next to code and freshness beats styling - READMEs, PRs, issues.
• Pre-render to SVG (mmdc in CI) when brand theming, exact appearance, or clickable links matter - slides, portals, published docs.
• Docs sites are the sweet spot - MkDocs and Docusaurus let you configure the mermaid version AND theme, so fences render branded.