Repository navigation
Draw the documentation's Mermaid diagrams, as GitHub does, before the first release with one - #3
Merged
Merged
Conversation
… 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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Related: isa-group/RESTest#439, whose workflow writes each release into
restest-versionand waits forllms.txtto name it; isa-group/RESTest#438, which put the first Mermaid diagram indocs/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.mdonmasterhas 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: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
mermaidinto<pre class="mermaid">holding the text, escaped. Being no code block any more, Expressive Code leaves it alone;data-pagefind-ignorekeeps its text out of search. Without JavaScript the reader sees the text, as on GitHub.MarkdownContentcomponent 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, asDESIGN.md's does, keeps them in both themes, as on GitHub; any other takes Mermaid's light or dark colours.fontFamilysetting, 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 assans-seriforsystem-ui, asDESIGN.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—mermaid12.2.0, andsatteri0.10.5, which the site already had through Astro and whose function the test calls.test/mermaid.test.mjs(new) — a block markedmermaidbecomes 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 thatrestest-versionnever goes back; and a paragraph on the diagrams.Evidence
npm test: 49 tests pass, the two new ones among them.npm run build, withrestest-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 indocs/design/.npm audit --omit=dev: no vulnerabilities.Decisions taken
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.npm auditreports a low advisory in the KaTeX that 11 uses.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.Open questions
None.
🤖 Generated with Claude Code