Skip to content

Draw the documentation's Mermaid diagrams, as GitHub does, before the first release with one - #3

Merged
ssegura merged 1 commit into
mainfrom
feat/mermaid-diagrams
Nov 6, 2026
Merged

ssegura merged 1 commit into
mainfrom
feat/mermaid-diagrams

Conversation

@ssegura

@ssegura ssegura commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

Related: isa-group/RESTest#439, whose workflow writes each release into restest-version and waits for llms.txt to name it; isa-group/RESTest#438, which put the first Mermaid diagram in docs/DESIGN.md.

What you can do now that you could not before

See RESTest's diagrams on the site as GitHub draws them, rather than as their code. docs/DESIGN.md on master has one, the modules and their interfaces, so 2.5.0 would otherwise reach the site with a block of Mermaid text where the diagram should be. A diagram wider than the text is drawn smaller to fit it, and the button "Full size" under it, or a click on it, shows it at its own size over the page, scrollable on a phone.

Try it yourself

With Node 26, build the site from RESTest's master, which has the diagram, and look at it:

git clone --branch feat/mermaid-diagrams https://github.com/isa-group/restest-site && cd restest-site
npm ci && npm test 2>&1 | grep -E '^ℹ (pass|fail)'
npm run sync -- --ref master && npx astro build | grep -E 'valid|built in'
grep -o '<pre class="mermaid"[^>]*>%%{init' dist/docs/design/index.html
npm run preview
ℹ pass 49
ℹ fail 0
· All internal links are valid. ·
[build] 77 page(s) built in 1.37s
<pre class="mermaid" data-pagefind-ignore>%%{init

Open http://localhost:4321/restest-site/docs/design/#components-and-interfaces: the diagram is drawn, every label whole; "Full size" shows it at its own size, and a click or Escape closes it; switch the theme and it is drawn again. http://localhost:4321/restest-site/docs/faults/, which has no diagram, loads nothing of Mermaid.

How it works

  • The block becomes the diagram's text. A plugin of the site's Markdown processor turns a code block marked mermaid into <pre class="mermaid"> holding the text, escaped. Being no code block any more, Expressive Code leaves it alone; data-pagefind-ignore keeps its text out of search. Without JavaScript the reader sees the text, as on GitHub.
  • Mermaid draws it in the browser. Starlight's MarkdownContent component is replaced by one that adds a script: on a page with a diagram it imports Mermaid, which Vite splits off, so a page without one loads 1.4 KB of script and nothing more. It draws each diagram, and draws them again when the theme changes. A diagram that sets its own colours, as DESIGN.md's does, keeps them in both themes, as on GitHub; any other takes Mermaid's light or dark colours.
  • Labels whole. Mermaid sizes a label by measuring its text in its fontFamily setting, Trebuchet unless told otherwise, and then leaves out of the picture a diagram's own font when the list names a generic family with a hyphen, such as sans-serif or system-ui, as DESIGN.md's does. The text was then drawn in the page's font, wider than the one measured, and labels were cut ("OpenAPI documer", "EventStrear"). The site gives Mermaid the page's font, once loaded, so that it measures in the font the text is drawn in.

What changed in the code

  • src/markdown/mermaid.mjs (new) — the plugin, for Sätteri, the Markdown processor the site already uses.
  • src/components/MarkdownContent.astro (new) — Starlight's component with the script that draws the diagrams, the button "Full size" and the dialog it opens.
  • astro.config.mjs — the plugin and the component.
  • src/styles/docs.css — the drawn diagram without the frame of code, the button, and the dialog.
  • package.json — mermaid 12.2.0, and satteri 0.10.5, which the site already had through Astro and whose function the test calls.
  • test/mermaid.test.mjs (new) — a block marked mermaid becomes the escaped text of a diagram; any other stays a code block.
  • scripts/lib/llms.mjs — a comment beside the opening sentence: RESTest's workflow waits for it, so the two change together.
  • README.md, .github/workflows/site.yml — RESTest's workflow in the present tense, now that it exists: what it writes, with what, what it waits for, and that restest-version never goes back; and a paragraph on the diagrams.

Evidence

  • npm test: 49 tests pass, the two new ones among them.
  • npm run build, with restest-version (v2.4.0, no diagram): 73 pages, every internal link valid.
  • npm run sync -- --ref master && npx astro build: 77 pages, every link valid, the diagram's text in docs/design/.
  • In the browser, at 1440 px and 375 px, light and dark: the diagram drawn, none of its 28 labels narrower than its text, in the page and at full size; the dialog scrolls on a phone and closes with a click or Escape; no horizontal scroll on the page; a page without a diagram fetches nothing of Mermaid.
  • npm audit --omit=dev: no vulnerabilities.

Decisions taken

  • Drawn in the browser, not at build time. Drawing at build time needs a headless browser in the build, and the plugins that do it, such as rehype-mermaid, are written for rehype, which the site's processor is not. In the browser it needs nothing new in the build, and follows the theme.
  • Mermaid 12.2.0, the newest release older than two weeks. 11.17.2, the last of 11, leaves the font out in the same way, and npm audit reports a low advisory in the KaTeX that 11 uses.
  • The page's font, in place of the one a diagram names when Mermaid leaves it out: DESIGN.md's diagram is drawn in Space Grotesk rather than the system's font. A list in RESTest with no hyphenated name, such as "Segoe UI", Roboto, Arial, would be kept.
  • A button "Full size" rather than the diagram alone as a button: a diagram made a button hides its labels from screen readers, and on a phone nothing would say it can be opened.
  • Vite's warning that some chunks are over 500 kB stays. They are Mermaid's, and are loaded only by a diagram that needs them; the largest, ELK's layout, by none of RESTest's.

Open questions

None.

🤖 Generated with Claude Code

… first release with one

A code block marked mermaid becomes the diagram's text, which Mermaid, loaded only on a page that has
a diagram, draws in the browser and draws again when the theme changes. A diagram wider than the text
is drawn smaller, and a button under it shows it at its own size. Mermaid measures labels in the page's
font, since it leaves out of the picture a diagram's own font that names a generic family.

The comment beside llms.txt's opening sentence says RESTest's workflow waits for it, and the README and
site.yml describe that workflow in the present tense.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ssegura
ssegura merged commit cb197df into main Nov 6, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant