Mermaid Conventions

FCC uses Mermaid for ~280 diagrams across its documentation. The conventions below produce diagrams that are readable on the web, look right in PDF, are accessible to screen readers, and are diffable in PRs.

The Figure-N convention

Every diagram has:

1. A one-paragraph introduction immediately before.
2. The Mermaid code block.
3. A caption on the line below, starting with "Figure N: ..."
4. A one-paragraph follow-up after the caption.

Example:

The FCC three-phase cycle runs Find → Create → Critique. Each phase
is handled by a distinct persona with its own R.I.S.C.E.A.R. definition.

```mermaid
flowchart LR
    F[Find] --> C[Create]
    C --> Q[Critique]

Figure 1: The FCC three-phase cycle.

The Critique persona holds halt authority, making the cycle auditable rather than merely sequential.

The intro orients the reader. The figure gives the visual. The caption anchors the reference. The follow-up draws the lesson.

## Numbering discipline

Four options for numbering:

- **Per-page.** Figure 1, 2, 3 on each page, reset at the top. Simplest.
- **Per-chapter.** Figure 1.1, 1.2 (chapter 1, diagrams 1 and 2). Scales to books.
- **Sequential across the doc set.** Figure 247. Pedantic but unambiguous.
- **Named only.** No numbers; each diagram has a memorable title.

FCC standardized on per-chapter for its books and per-page for its tutorial and guidebook material. Choose one; document it; enforce in PR review.

## Intro-and-follow-up rhythm

The paragraphs around a diagram do different work:

- **Intro paragraph.** Set context. What is this about? Why does it matter? One or two sentences; never more than three.
- **Caption.** Strict Figure-N format. Acts as the anchor for cross-references ("See Figure 3").
- **Follow-up paragraph.** Extract the lesson. What should the reader take away? Often a single sentence.

Diagrams without intros or follow-ups float. They look like decorations. Always bracket them.

## Mermaid subtypes to know

FCC uses:

- **flowchart** — most common. Left-to-right (LR) or top-to-bottom (TB).
- **sequenceDiagram** — for turn-by-turn interactions.
- **classDiagram** — for type relationships.
- **stateDiagram-v2** — for state machines.
- **erDiagram** — for entity-relationship (rare in FCC).
- **gantt** — for project timelines (rare).
- **C4Context / C4Container** — for architectural context (via Mermaid C4 subset).

Keep each diagram to one subtype. Mixing leads to confusion.

## Size discipline

A readable diagram has:

- Fewer than 20 nodes (flowchart) or fewer than 12 participants (sequence).
- Fewer than 30 edges.
- Labels that fit in two lines each.

When a diagram exceeds these, split it. One big diagram never helps; two smaller ones almost always do.

## Accessibility

Mermaid does not produce alt text automatically. Your caption *is* the alt text. Make it descriptive enough to stand alone. "Figure 3: Flow of a scenario run from input through Finder, Creator, and Critique to output" is better than "Figure 3: The workflow."

For truly complex diagrams, add a short text description below the follow-up: "In words: the scenario begins with ..." Screen-reader users benefit; sighted users skip.

## Rendering pipeline

FCC's pipeline renders Mermaid via a Pandoc Lua filter that calls `mmdc` (the Mermaid CLI) for each block. The output is SVG for HTML and PNG for PDF. Rendered assets are cached under `publications/_cache/mermaid/` so unchanged diagrams do not re-render.

Minimum setup:

1. `npm install -g @mermaid-js/mermaid-cli`
2. Ensure Chromium or Firefox is available (Mermaid CLI uses headless browser).
3. Add a pre-commit hook or CI step to re-render changed diagrams.

For Docker-ephemeral CI, use the `minlag/mermaid-cli` image.

## Styling

Mermaid accepts custom themes. FCC uses the default "default" theme with a small palette override:

```mermaid
%%{init: {'theme':'default', 'themeVariables':{'primaryColor':'#dbeafe','lineColor':'#1e3a8a'}}}%%
flowchart LR
    A --> B

Two rules:

1. Pick one theme for the whole project.
2. Override colors only where the default is illegible (e.g., print contrast).

Custom fonts via Mermaid are brittle; avoid in publication pipelines.

Caveats and workarounds

• Large sequence diagrams overflow PDF pages. Split them at natural phases.
• Chromium instability. Some complex diagrams fail intermittently in headless Chromium. FCC caches successful renders and retries on failure. Plan for 95% success rate, not 100%.
• Mermaid in EPUB. Some EPUB readers do not render inline SVG. Use PNG for EPUB-bound content.
• Mermaid version drift. Pin @mermaid-js/mermaid-cli to a specific minor version. New Mermaid versions occasionally change defaults.

Diffable diagrams

The whole point of diagram-as-code is that diagrams are diffable. Follow-on conventions:

• One diagram per fenced block. Never two.
• Consistent node ordering. Alphabetize or topologically sort; do not reorder arbitrarily.
• Avoid trailing whitespace. git diff punishes inconsistent whitespace.
• Short labels preferred. If two labels are "Handles payment authorization" and "Handles payment capture," abbreviate to "authz" and "capture" and put the longer forms in the caption.

When not to use Mermaid

Mermaid is not the right tool for:

• Detailed UML beyond basic classes and sequences. Use PlantUML or draw.io.
• Freeform architecture diagrams. Use Excalidraw or draw.io; export PNG, commit alongside Markdown.
• Interactive visualizations. Use D3 or Plotly via embedded HTML.
• Schematic electrical/mechanical diagrams. Use domain-specific tools.

Sample convention document

Adopt-and-customize this for your project:

"All architecture and workflow documentation shall include at least one Mermaid diagram per page. Each diagram shall have an introductory paragraph, a Figure-N caption, and a follow-up paragraph. Diagrams exceeding 20 nodes shall be split. All diagrams render via mmdc version X.Y; output formats are SVG (HTML) and PNG (PDF/EPUB). Pull requests that add or modify diagrams shall include the rendered assets or a clear path by which CI regenerates them."

One page; governs most disputes.

Where next

With diagrams under control, the next piece is generated-docs hygiene. Continue to Persona-Driven Docs, or to Publication Pipeline 101 for multi-format output.