mdBook
mdBook 0.5.4 builds Markdown chapters into a searchable online book with a table of contents, theme and local preview, producing static HTML for publication.
What mdBook does
mdBook turns a set of Markdown chapters into a static book with navigation, search, themes and generated HTML. It fits technical manuals, course notes and project documentation; it is not a dynamic blog CMS and does not provide accounts, comments or a database.
Project structure
A book normally uses book.toml, a src directory and src/SUMMARY.md. SUMMARY.md controls the navigation tree and relative chapter paths. A Markdown file placed in src does not automatically become a visible chapter.
Preview versus publishing
mdbook serve watches files and refreshes a development preview. The release artifact comes from mdbook build and should be served by a reliable static web server or hosting platform rather than exposing the preview process to the public network.
Reproducible output
Keep the source and configuration under version control, pin the mdBook version in automation and check broken links, images, warnings and generated output before publishing.
Maintenance note
Review date: 2026-08-23. The page was checked against mdBook 0.5.4, Windows x64 packaging, SUMMARY.md navigation, local preview, static output and release boundaries.
Save to your cloud drive
Open the cloud drive to get the file directly, or save it for convenient access on another device.
Quark Cloud Drive
RecommendedSave mdBook to this cloud drive
Baidu Netdisk
Save mdBook to this cloud drive
mdBook 0.5.4 Windows documentation build and publish guide
Create a minimal book with init, understand book.toml and SUMMARY.md, preview the chapters locally and build a static directory for a separate publishing service.
Before you start
- Prepare an independent version-controlled directory with a few non-sensitive Markdown chapters.
- Decide the final path, link case and Web server root; a Windows preview does not prove that a Linux host will resolve paths identically.
- Keep local preview separate from production hosting and never expose a development watcher as the permanent public service.
Installation steps
- 01
Unpack the mdBook executable
Put the Windows x64 archive in a fixed tools directory, check the version by full path and add it to the user PATH only after the test succeeds.
- 02
Initialize a test book
Run mdbook init in a new directory, answer the setup questions and inspect book.toml, src/SUMMARY.md and the generated chapter files.
- 03
Add the project to version control
Commit source Markdown and configuration, treat the generated book directory as a build artifact and agree on link, image and chapter naming rules.
Quick start
- 01
Edit navigation and chapters
List relative chapter paths in src/SUMMARY.md with the intended hierarchy, then edit those Markdown files and check filename case.
- 02
Preview locally
Run mdbook serve --open from the directory containing book.toml, edit a chapter and verify live rebuild, navigation, search and internal links.
- 03
Build static output
Run mdbook build, inspect the generated book directory with a static server and upload that artifact instead of the preview process.
Usage tips
- SUMMARY.md has strict formatting. Check paths, indentation, list markers and final URLs after every hierarchy change.
- Non-Markdown files in src can be copied to output. Review copyright, size and sensitive data before placing images or downloads there.
- In continuous integration, pin mdBook and run link, warning and generated-output checks before release.
Troubleshooting and uninstall
Why did mdBook create an empty chapter file?
It creates a file for a chapter listed in SUMMARY.md when the path does not exist. Inspect the relative path and remove accidental entries before committing.
Why do images or links work in preview but fail after deployment?
Check relative paths, filename case, the site subpath and the Web server root, then test the generated directory with a production-like static server.
- Keep source and configurationRemove the tools directory from PATH and delete the executable only after confirming that source Markdown, book.toml and backup copies are stored elsewhere.
- Clean generated output selectivelyRemove the generated book directory when no release depends on it; it can be rebuilt from the version-controlled source.
Frequently asked questions
What is mdBook best used for?
It is suited to technical manuals, course notes and project documentation made from multiple Markdown chapters. It does not provide a dynamic blog, accounts, comments or a database.
Why is a new chapter missing from navigation?
Add it to src/SUMMARY.md with the correct relative path, indentation, list marker and filename case. Merely placing a file in src does not add a navigation entry.
Can mdbook serve be a production server?
Treat serve as a development preview that watches files. Run mdbook build and give the static output to a reliable Web server or hosting platform for production.