docs(zeronym): publish The Zeronym Book to GitHub Pages - #31
Merged
Conversation
Renders zeronym/book/ on every push to main that touches it and deploys to https://shieldedlabs.github.io/zero/zeronym/, with pull requests building but not deploying so a book that stops compiling blocks the merge. The book is staged into a zeronym/ subdirectory of the Pages artifact rather than at its root: a repo gets one Pages site, and this one should not be spent entirely on one book. book.toml gains a matching site-url, which only 404.html consumes (every other page links relatively) but which sends every not-found visitor nowhere if the two disagree. The build must run `mdbook-mermaid install` before `mdbook build`. book.toml already lists mermaid.min.js and mermaid-init.js in additional-js, both are generated and gitignored, and skipping the step fails silently: the pages render, reference two scripts that do not exist, and show the three architecture diagrams as raw code blocks. Co-Authored-By: Claude Opus 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
1 participant
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.
Publishes The Zeronym Book at https://shieldedlabs.github.io/zero/zeronym/.
.github/workflows/zeronym-book.ymlbuilds the mdBook on every push tomainthat toucheszeronym/book/**, and deploys it to GitHub Pages. Pull requests build but do not deploy, so a book that stops compiling blocks the merge instead of the publish.Layout
The book is staged into a
zeronym/subdirectory of the Pages artifact rather than at its root: a repo gets exactly one Pages site, and this one should not be spent entirely on one book. The site root gets a redirect into the book, to be replaced with a real index when Zero publishes a second one.book.tomlgains a matchingsite-url, which only404.htmlconsumes (every other page links relatively) but which sends every not-found visitor nowhere if the two disagree.The mermaid step is not optional
The build runs
mdbook-mermaid installbeforemdbook build.book.tomlalready listsmermaid.min.jsandmermaid-init.jsinadditional-js, both are generated files that.gitignoreexcludes, and skipping the step fails silently: the pages render, reference two scripts that do not exist, and show the three architecture diagrams as raw code blocks.Tool versions are pinned to what the book was written against (mdbook 0.5.4, mdbook-mermaid 0.17.0). Bump them here and in the local toolchain together.
Verified locally
mdbook build: all 9 chapters render, 3 mermaid diagrams emitclass="mermaid"blocks with both scripts wired.404.htmlemitshref="/zero/zeronym/"; no other page references an absolute path._site/index.html+_site/zeronym/.Pages is enabled on the repo with source GitHub Actions; the site 404s until this merges and the first deploy runs.
🤖 Generated with Claude Code