For AI agents: the complete documentation index is available at https://lazygophers.github.io/pamphlet/en/llms.txt, the full documentation bundle is available at https://lazygophers.github.io/pamphlet/en/llms-full.txt, and this page is available as Markdown at https://lazygophers.github.io/pamphlet/en/write/diagrams/mermaid/index.md.
Pamphlet
  • English

      • Mermaid (the drawing engine)

      What it is

      Every diagram above is drawn by it. Mermaid turns text into pictures, and it is the only engine implemented in this version.

      One fence language, mermaid; the first keyword decides which kind of diagram you get.

      Install it once

      npm i -g mermaid-isomorphic playwright && npx playwright install chromium

      About 150MB and a minute the first time. Confirm with pamphlet doctor:

      ✓ mermaid (mermaid)

      Why a browser has to be downloaded

      Because Mermaid needs a real browser's layout engine to measure text.

      jsdom (a pure-JavaScript fake browser) does not implement SVGTextElement.getBBox() — without knowing how wide a run of text is, there is no way to lay out the shapes around it.

      This is not a preference. Mermaid organisation member @aloisklink ruled out the jsdom approach explicitly: https://github.com/mermaid-js/mermaid/issues/3886#issuecomment-1341694822

      The cost lands on "install once", not "every run".

      The browser starts lazily

      A text-only document never launches it. It starts only when a ```mermaid fence is actually encountered.

      Measured:

      CaseTime
      1st diagram (including browser cold start)733ms
      Each one after364ms
      A 40-node diagram412ms

      The DIAG-303 timeout is 10 seconds, roughly 13× the worst measured case.

      Which kinds it draws

      Thirteen. Each has two pages: one for Pamphlet's own syntax and one for the Mermaid fence syntax described here. They draw the same diagram.

      What it drawsOwn syntaxThe Mermaid fence
      Flowcharts:::flowfence syntax
      Sequence diagrams:::sequencefence syntax
      State diagrams:::statefence syntax
      Class diagrams:::classfence syntax
      Entity-relationship diagrams:::erfence syntax
      Gantt charts:::ganttfence syntax
      Pie charts:::piefence syntax
      Architecture diagrams:::architecturefence syntax
      System context diagrams:::c4fence syntax
      Data-flow diagrams:::dataflowfence syntax
      Mind maps:::mindmapfence syntax
      Git branch diagrams:::gitgraphfence syntax
      Block diagrams:::blockfence syntax

      They render, but imperfectly

      timeline / quadrantChart / journey / packet-beta / radar-beta / xychart-beta draw, but a few colours do not follow the theme and they report DIAG-304. The engine computes those colours from the primary colour, and the computed values are neither our sentinels nor caught by the substitution.

      Two colours it hard-codes (known not to follow the theme)

      The state diagram's edge-label colour (red) and the Gantt separator (navy) are written into Mermaid's own per-kind stylesheets and cannot be substituted with theme variables, so every build reports two DIAG-304 warnings.

      These two are known not to follow the theme: this repository's own examples/demo.md reports them too, and that is not a mistake in the demo.

      They stay reported rather than claimed in the alias table because they are real warnings, not noise — in dark mode that navy rule is nearly invisible. It is also how we find out the day Mermaid changes its defaults.

      Two kinds reject non-ASCII labels

      The parsers for sankey-beta and requirementDiagram only accept ASCII identifiers; CJK node names fail outright with DIAG-303. Verified against mermaid 11.17.2.

      For flow quantities, use a flowchart and put the numbers on the edge labels.

      When the source is wrong

      You get DIAG-303, and the hint suggests pasting the source into https://mermaid.live — Mermaid's own editor, whose errors are clearer than a command line's.

      The output is still written when a diagram fails: a placeholder box explains the reason in its place, the rest of the document is fine, and the exit code is 1.

      CI needs one extra step

      The image needs Chromium and its system dependencies:

      npx playwright install --with-deps chromium

      See checking docs in CI for a full CI configuration.

      Source: ADR-0004