ci: build docs from SUMMARY.md rather than by walking the directory - #960
Merged
Conversation
`md-book -i . -o book` pointed at the docs root, which has no SUMMARY.md, so md-book fell back to walking the directory: 574 pages in path order, publishing archive/, artifacts/ and research notes alongside the real documentation. `md-book build .` reads book.toml, so it honours `src = "src"` and the 118-line SUMMARY.md: 59 pages, in the order the summary declares, with the part titles and the folding the config already asks for. Output still lands in docs/book, which is what the upload step expects. Also drops the `|| true`, which was hiding build failures behind a successful job and a stale artefact. Requires terraphim/md-book#27, which the workflow clones from main. Co-Authored-By: Claude Opus 5 (1M context) <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.
What
deploy-docs.ymlinvokes md-book asmd-book -i . -o book. That points at the docs root, which has noSUMMARY.md, so md-book falls back to walking the directory: 574 pages in path order, publishingarchive/,artifacts/and research notes alongside the real documentation.md-book build .readsbook.toml, so it honourssrc = "src"and the 118-lineSUMMARY.md: 59 pages, in the declared order, with the part titles and the[output.html.fold]the config already asks for. Output still lands indocs/book/, which is what the upload step expects.Also drops the
|| true, which was hiding build failures behind a green job and a stale artefact.Why now
terraphim/md-book#27 just landed, adding the
SUMMARY.mdbook model and thebuild [dir]subcommand. This workflow clones md-book frommain, so it picks that up automatically.That PR also fixes two things visible on docs.terraphim.ai today:
git-repository-urlandedit-url-templateare set indocs/book.tomlbut md-book knew only its own key names, so the repository and edit links have been silently missing. Both mdBook spellings are now accepted.SUMMARY.mdentry pointing at../CLOUDFLARE_DEPLOYMENT.md(a file besidebook.toml) used to abort the summary-driven build; containment is now scoped to the book directory rather thansrc/.Verification
Built this repo's docs with the merged md-book:
Sidebar carries the SUMMARY part titles (Crates Overview, Components, Integrations); orphaned files under
docs/srcare reported rather than silently published.Note
mathjax-support = trueindocs/book.tomlwarns as unimplemented — no content indocs/srcuses maths, so nothing is lost; remove the key or leave it as a marker.