Skip to content
Notes

autosummary mdbook extention

keep SUMMARY.md up to date automatically (drop-in configs) mdBook: SUMMARY.md

TL;DR
Use the mdbook-autosummary preprocessor. It rebuilds SUMMARY.md from your folder tree on every mdbook build/serve. Make it the first preprocessor, set create-missing=false, and start with an empty md/SUMMARY.md that you optionally .gitignore. mdbook-autosummary README mdBook: Preprocessors mdBook: SUMMARY.md

Why not rely on mdbook-toc?
mdbook-toc inserts per-page tables of contents; it does not manage the book-level SUMMARY.md navigation. You still need a valid SUMMARY.md or something to generate it. mdBook: SUMMARY.md

Option A — mdbook-autosummary (recommended) mdbook-autosummary README

  1. Install: cargo install mdbook-autosummary
  2. Create an empty file at md/SUMMARY.md (since your src = "md").
  3. Update book.toml so autosummary runs first and others run after it:

[build] create-missing = false # let autosummary control SUMMARY.md generation

[preprocessor.autosummary]

Your existing preprocessors should declare they run after autosummary:

Section titled “Your existing preprocessors should declare they run after autosummary:”

[preprocessor.callouts] command = “mdbook-callouts” after = [“autosummary”]

[preprocessor.mermaid] command = “mdbook-mermaid” after = [“autosummary”]

[preprocessor.toc] command = “mdbook-toc” marker = "" after = [“autosummary”]

Notes:

  • Autosummary expects each directory you want in the nav to contain an index.md, and it prefers the top-level # Heading in each file as the title. mdbook-autosummary README
  • Because mdBook parses SUMMARY.md before preprocessors, autosummary uses a reload trick; keep SUMMARY.md present (possibly empty) and consider adding it to .gitignore. mdBook: SUMMARY.md mdbook-autosummary README

Option B — mdbook-auto-gen-summary (preprocessor or CLI) mdbook-auto-gen-summary README Prefer a simpler tool? This one can run as a preprocessor or be called once as a CLI step in CI to rewrite SUMMARY.md.

As a preprocessor: [build] create-missing = false

[preprocessor.auto-gen-summary] first-line-as-link-text = true # use the first line of each page as nav text

CLI in CI: mdbook-auto-gen-summary gen md # writes md/SUMMARY.md mdbook build

Other options (less common, YMMV)

  • mdbook-fs-summary: generate the summary from the filesystem instead of keeping an explicit file. mdbook-fs-summary
  • mdbook-summary-generate: another preprocessor that builds SUMMARY.md from directories/filenames with ordering rules. mdbook-summary-generate

CI tip (keep humans out of SUMMARY.md conflicts)
Add md/SUMMARY.md to .gitignore, and in your pipeline run the generator before mdbook build. That avoids churn in PRs while guaranteeing navigation matches your tree. mdbook-autosummary README mdBook: Preprocessors