Under the hood: directives, icons, layouts, math

Frontmatter is a YAML block between --- fences at the very top of the diagram. Its config: key can override almost the entire configuration for that one diagram. Proof, live: this page's initialize() sets the pink theme, and the diagram below flips itself to the dark theme anyway - while every other diagram on the page stays pink.

---
config:
  theme: dark
---
flowchart LR
  ev["App events"] --> ing["Ingestion"]
  ing --> dw[("Warehouse")]
  dw --> bi["Dashboards"]

• The order matters: frontmatter must be the FIRST thing in the block - the --- fence before the diagram keyword.
• title lives here too: title: My diagram in frontmatter is the modern way to caption a diagram.
• Scope is one diagram. Ten diagrams on a page, one frontmatter block each, zero interference.

Before frontmatter existed, per-diagram config went in a %%{init: {...}}%% directive on the first line. Deprecated since v10.5, but still parsed - and you WILL meet it in older READMEs and Stack Overflow answers, so read it fluently:

%%{init: { "theme": "forest" } }%%
flowchart LR
  a["Same trick"] --> b["older syntax"]
  b --> c["still parses in v11"]

Theme is the party trick; the workhorse overrides are diagram-type settings. Nesting under config: mirrors the config schema - here, flowchart edges become right-angled steps for that circuit-board look, on this one diagram only:

---
config:
  flowchart:
    curve: step
---
flowchart LR
  raw["Raw zone"] --> stg["Staging"]
  stg --> mart["Marts"]
  stg --> ml["Feature store"]

Architecture diagrams place service nodes (each with an icon) inside group boxes, and wire them edge-to-edge with side anchors: L, R, T, B. The five default icons need no registration at all:

architecture-beta
  group nova(cloud)[Nova platform]
  service ing(server)[Ingestion] in nova
  service dw(database)[Warehouse] in nova
  service lake(disk)[Object storage] in nova
  service web(internet)[Dashboards]
  ing:R -- L:dw
  dw:B -- T:lake
  dw:R -- L:web

• Icon goes in parentheses, label in brackets: service dw(database)[Warehouse].
• Edges anchor to sides: ing:R -- L:dw means "ingestion's right side to warehouse's left side" - you're steering geometry, not just topology.
• Groups nest services with in group_id - the platform boundary draws itself.

On a page you control, register any iconify pack once and reference its icons as packname:icon-name in architecture diagrams (and flowchart icon shapes). The docs' own recipe, fetching the logos pack from a CDN:

Then in any architecture diagram on that page:

The switch itself is beautifully boring:

• Many edge crossings - the classic data lineage graph where every source feeds every mart. ELK's routing untangles what dagre leaves knotted.
• Long ranks - wide layers (20 tables in one tier) that dagre spreads into a football field. ELK packs them more sensibly.
• Dense subgraph nesting - multiple zones with cross-zone edges tend to route cleaner under ELK.
• Not worth it below ~15 nodes: for small diagrams the engines produce near-identical results, and dagre needs zero extra setup. Try dagre first, reach for ELK when the diagram visibly fights you.

Wrap an expression in $$...$$ inside a quoted label and mermaid hands it to the KaTeX typesetter (v10.9+). Supported in flowcharts and sequence diagrams - a lovely fit for ML pipeline docs where the transformation IS a formula:

Diagrams are user input, and mermaid treats them that way. The securityLevel setting - a SECURE key, so only initialize() can set it, never a pasted diagram - has four positions:

The everyday symptom: click statements that silently do nothing. A flowchart like this needs the SITE to be at loose - no frontmatter can rescue it, by design: