docs: offline booklets, mermaid diagrams, GFM alerts#5583
Merged
norman-abramovitz merged 7 commits intoJul 6, 2026
Merged
Conversation
documentation.yml and documentation-versioning.yml only triggered on master with Node 12 and have been dead weight since the develop docs lane landed in pr.yml. Drop their rows from the CI version-drift table.
docs-build/ holds one directory per booklet: _quarto.yml is the spine manifest over the docs/ pool, index.qmd the preface. render.sh assembles each booklet by copy (Quarto needs inputs inside the project dir), rewrites in-spine links to internal anchors (epub/PDF concatenate chapters, so file links would otherwise be dead), and renders epub + typst PDF to dist/booklets/. First booklet: the theming guide (theming-architecture, tailwind-usage, branding-architecture). Wired into the make system as build/clean booklets. The planned alert and mermaid shims are not needed: no spine chapter uses them, and the ceiling is documented in docs-build/README.md.
Any docs/ or docs-build/ change renders all booklets with Quarto 1.9.38 and uploads the epub/PDF outputs as a PR artifact for review; nothing is published. Booklet-only PRs skip the heavy code suite via the existing changes filter, and the quality gate accepts the job's skipped state like the other docs-lane jobs.
Quarto renders neither GFM alerts nor plain mermaid fences in book
output (verified: literal [!NOTE] blockquotes in both .md and .qmd
chapters; inert code blocks for mermaid). Rewrite alerts to callout
divs at assembly time, rewrite mermaid fences to executable {mermaid}
cells, and assemble chapters as .qmd so the cells execute (rendering
diagrams to images via Chrome for epub/PDF). The spine now lists
.qmd chapter names.
The theming layer stack, plugin-config fan-out, and secrets pipeline are flow diagrams that mermaid expresses better and keeps editable; GitHub, the website (theme-mermaid), and the booklets all render it. Directory trees and the spatial screen-region map stay ASCII — mermaid cannot express those.
Promote existing Note:/**NOTE** prose and bare blockquotes to > [!NOTE]/[!IMPORTANT]/[!TIP] alerts, which render as styled callouts on GitHub, the website, and in booklets. The release-guide occurrence stays: it sits inside a release-notes template fence.
quarto render blocks on an interactive chrome-headless-shell install prompt on runners with an empty tool cache, hanging the job. Install the tool explicitly with --no-prompt and cap the job at 15 minutes.
nabramovitz
force-pushed
the
norm/docs/website-modernize
branch
from
d5acb86 to
dcfdf62
Compare
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
2 participants
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.
Completes the documentation-architecture work: removes the dead master-only docs workflows and adds the offline booklet pipeline, then puts the GFM subset's alert and mermaid features to use across docs/.
Changes
CI cleanup
documentation.ymlanddocumentation-versioning.yml(master-only, Node 12, dead since the develop docs lane landed in pr.yml).Booklet pipeline (
docs-build/)_quarto.yml(an ordered chapter spine over thedocs/pool) and anindex.qmdpreface.render.shassembles by copy and renders epub + PDF (typst) todist/booklets/.> [!NOTE]alerts become callouts, and mermaid fences become executable{mermaid}cells (chapters assemble as .qmd; diagrams render to images via Chrome).make build booklets/make clean bookletswired through the make registry.booklets-buildjob in the PR docs lane renders on any docs/ or docs-build/ change and uploads the epub/PDF as an artifact for review; nothing is published. Booklet-only PRs skip the code suite via the existing changes filter.Docs content
> [!NOTE]/[!IMPORTANT]/[!TIP]alerts in four files. These render as styled callouts on GitHub, the website, and in the booklets.Verification
node scripts/lint-docs.mjs: 57 files, 0 problemsmake build bookletsrenders both outputs; epub inspected: cross-chapter links resolve to internal anchors, the mermaid diagram is embedded as an imagebun run buildin website/ succeeds (the two broken-anchor warnings it reports exist on develop and are tracked as content-freshness follow-ups)