Skip to content

ci: build docs from SUMMARY.md rather than by walking the directory - #960

Merged
AlexMikhalev merged 1 commit into
mainfrom
docs/md-book-summary-mode
Aug 12, 2026
Merged

ci: build docs from SUMMARY.md rather than by walking the directory#960
AlexMikhalev merged 1 commit into
mainfrom
docs/md-book-summary-mode

Conversation

@AlexMikhalev

Copy link
Copy Markdown
Contributor

What

deploy-docs.yml invokes md-book as md-book -i . -o book. That points at the docs root, which has no SUMMARY.md, so md-book falls 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 declared order, with the part titles and the [output.html.fold] 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 green job and a stale artefact.

Why now

terraphim/md-book#27 just landed, adding the SUMMARY.md book model and the build [dir] subcommand. This workflow clones md-book from main, so it picks that up automatically.

That PR also fixes two things visible on docs.terraphim.ai today:

  • git-repository-url and edit-url-template are set in docs/book.toml but md-book knew only its own key names, so the repository and edit links have been silently missing. Both mdBook spellings are now accepted.
  • A SUMMARY.md entry pointing at ../CLOUDFLARE_DEPLOYMENT.md (a file beside book.toml) used to abort the summary-driven build; containment is now scoped to the book directory rather than src/.

Verification

Built this repo's docs with the merged md-book:

md-book build .   ->  Total pages: 59, into docs/book/

Sidebar carries the SUMMARY part titles (Crates Overview, Components, Integrations); orphaned files under docs/src are reported rather than silently published.

Note mathjax-support = true in docs/book.toml warns as unimplemented — no content in docs/src uses maths, so nothing is lost; remove the key or leave it as a marker.

`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>
@AlexMikhalev
AlexMikhalev merged commit 1383fe9 into main Aug 12, 2026
1 check passed
@AlexMikhalev
AlexMikhalev deleted the docs/md-book-summary-mode branch August 12, 2026 10:06
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