Documentation

Diagrams

Routebase renders Mermaid diagrams everywhere documentation is written — no plugin, no external service, and no styling work: every diagram is drawn in your portal's own colors and fonts, in light and dark mode, automatically.

This page covers where diagrams render, how to add them, and how theming and per-diagram styling work. For the diagram block inside the page editor (split view, templates, error hints), see Authoring Pages.

Where diagrams render

  • Documentation pages — in the editor (live preview), in the portal preview, and on the published portal.
  • The API reference — endpoint descriptions and section descriptions support Mermaid, so a sequence diagram can sit right next to the endpoint it explains.
  • Inside the app — endpoint and folder descriptions in the API Designer render diagrams wherever they are shown.

Readers never need anything installed: diagrams render client-side in the browser, and the rendering library is only loaded on pages that actually contain one.

Adding a diagram

In the page editor, type / and choose Mermaid Diagram — or Sequence Diagram, ER Diagram, or State Diagram to start from a worked template. The block shows the source on the left and a live preview on the right; syntax help and templates sit in the block's toolbar. Details in Authoring Pages → Diagrams.

In Markdown — the editor's Markdown mode, descriptions in the API Designer, or content written through the MCP tools and routebase docs push — a diagram is a fenced code block with the mermaid language tag:

```mermaid
flowchart LR
  Client -- "POST /orders" --> API
  API --> Queue[(Queue)]
  Queue --> Worker
```

That block renders as:

flowchart LR
  Client -- "POST /orders" --> API
  API --> Queue[(Queue)]
  Queue --> Worker

All Mermaid diagram types work — flowcharts, sequence diagrams, ER diagrams, state diagrams, class diagrams, pie charts, Gantt charts, mindmaps, timelines, and the rest of what mermaid.js.org documents.

Generating diagrams from your API

The Diagram from API Data slash command (also reachable from any Mermaid block's toolbar) writes the diagram source for you, from data Routebase already has:

  • Endpoint — pick an endpoint and get a sequence diagram of its request/response flow.
  • Schemas — pick one or more schemas and get an ER diagram of their fields and relations.
  • Dependencies — pick a root service from your Service Catalog and get a flowchart of its dependency graph, with selectable depth.

The result is an ordinary Mermaid block: the generated source is yours to edit, and it does not update by itself when the API changes — regenerate it when it should.

Diagrams match your branding

Diagrams are not skinned with a generic diagram theme. At render time they pick up the portal's active design tokens — the same ones your theme and brand colors define:

  • Colors — node fills, borders, edge lines, and label backgrounds come from your portal theme; node borders use your primary color.
  • Typography — labels use your portal's body font, not a diagram-library default.
  • Light and dark — diagrams re-render when a reader flips the portal's theme toggle, matching either mode.

There is nothing to configure and nothing to keep in sync: change your portal's brand color and every diagram follows on the next portal build. Inside the app, the same diagrams follow the app theme instead — each surface matches its surroundings.

Styling an individual diagram

For deliberate emphasis — highlighting one node in a flow, coloring states by meaning — use Mermaid's own styling syntax, which is part of the diagram source and travels with it:

flowchart LR
  A[Request] --> B{Valid?}
  B -- yes --> C[Process]
  B -- no --> D[Reject]
  style D fill:#7f1d1d,stroke:#ef4444,color:#fecaca
  classDef done fill:#14532d,stroke:#22c55e,color:#dcfce7
  class C done

Two things that will not work, on purpose: Mermaid's %%{init: …}%% directives and YAML frontmatter config: blocks are ignored. Routebase renders diagrams with a hardened security configuration, which disables per-diagram config injection — colors set with style and classDef are the supported way to deviate from the theme.

Portal-wide adjustments

If you want to restyle diagrams across the whole portal — say, a different container background — use the Custom CSS card described in Branding & Appearance. Every diagram sits in a .docs-mermaid container (the rendered SVG in .docs-mermaid-svg inside it), so the frame, spacing, and background are one selector away. The colors inside a diagram are embedded in its SVG and are better changed through your theme's brand colors than through CSS overrides.

When a diagram cannot render

  • In the editor, a source that doesn't parse shows a Diagram syntax error panel with a plain-language hint above the raw Mermaid message — the page still saves.
  • On the portal, an invalid diagram (or a browser with JavaScript disabled) falls back to showing the diagram source as a readable code block. Nothing breaks the page.