mdBook: Build Documentation Sites from Markdown Files

mdBook (the tool people search for as "md book") turns a folder of Markdown files into a searchable, themed documentation site. It's a single binary maintained by the Rust project. You write chapters in .md, list them in SUMMARY.md, and run mdbook build. This guide takes you from install to a deployed GitHub Pages site, explains every line of SUMMARY.md and book.toml, and covers PDF output.

What Is an mdBook (md book)?

An mdBook is a static site generated by the mdbook binary from the rust-lang GitHub organisation. The Rust Book, the Cargo Book, and the Rust Reference are all mdBooks, which is why the tool feels familiar if you've read any Rust documentation. The repo has about 22,000 stars and ships under the MPL-2.0 licence. The current release is v0.5.4 from 6 July 2026.

The output is plain HTML, CSS, and JavaScript with a sidebar table of contents, full-text search, five colour themes, and a print view. No server runtime is required, so the built folder can sit on GitHub Pages, Netlify, an S3 bucket, or a plain nginx directory.

Compared with the alternatives: MkDocs is Python and has the bigger plugin ecosystem, Docusaurus is React and better for marketing-style docs, and GitBook is a hosted product. An md book is a single binary with no runtime dependencies. That's why we reach for it on Rust and systems projects where nobody wants to install Node or Python to fix a typo.

How to Install mdBook

There are two supported routes, and neither needs Rust knowledge.

Prebuilt binary (fastest). The GitHub Releases page attaches archives for six targets: x86_64 and aarch64 macOS, x86_64 Windows (MSVC), and x86_64 and aarch64 Linux (gnu and musl). Download the one for your machine, extract it, and put the mdbook executable somewhere on your PATH. On macOS or Linux:

mkdir -p ~/.local/bin
curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.5.4/mdbook-v0.5.4-aarch64-apple-darwin.tar.gz | tar -xz --directory=$HOME/.local/bin
mdbook --version

Swap the archive name for your platform. The same one-liner is what the official CI guide uses.

Cargo (if you already have Rust). cargo install mdbook compiles it from crates.io and drops it in ~/.cargo/bin. The docs state it needs Rust 1.88 or newer. Run the same command again later to update, or cargo uninstall mdbook to remove it.

Create a Book: init, SUMMARY.md, and book.toml

Run mdbook init my-docs. It asks two questions (a title, and whether to create a .gitignore) and generates this tree:

my-docs/
├── book.toml
├── book/
└── src/
    ├── SUMMARY.md
    └── chapter_1.md

Pass --title="My Docs" --ignore=git to skip the prompts, or --theme to copy the default theme into src/theme for editing.

SUMMARY.md, line by line

SUMMARY.md is the one file mdBook parses strictly. It's a hand-written table of contents, and every chapter in your book must appear in it. Here's a complete example that uses every construct:

# Summary

[Introduction](README.md)

# User Guide

- [Installation](guide/installation.md)
- [Configuration](guide/configuration.md)
  - [Themes](guide/themes.md)
  - [Search](guide/search.md)

---

# Reference

- [CLI](reference/cli.md)
- [Roadmap]()

[Changelog](CHANGELOG.md)

Reading from the top:

• The # Summary heading is ignored by the parser. You can drop it.
• [Introduction](README.md) before any list is a prefix chapter: unnumbered, no nesting, always before the numbered ones.
• # User Guide inside the list area is a part title. It renders as plain text in the sidebar, not a link.
• The - items are numbered chapters. Indent to nest (Themes becomes 2.1). Use - or * but don't mix them in one file.
• --- on its own line is a separator, a visual break in the sidebar.
• [Roadmap]() with an empty link is a draft chapter: it shows as a disabled entry so you can plan structure before writing.
• [Changelog](CHANGELOG.md) after the last list is a suffix chapter, unnumbered, at the end.

If a linked file doesn't exist, mdBook creates it on build (that's the create-missing option, on by default). A SUMMARY.md is the same idea as a hand-written Markdown table of contents, except mdBook enforces it.

book.toml

The config file uses TOML sections. This is a realistic one for a project hosted on GitHub:

[book]
title = "My Docs"
authors = ["Your Name"]
description = "Internal engineering handbook"
language = "en"
src = "src"

[build]
build-dir = "book"
create-missing = true

[output.html]
default-theme = "light"
preferred-dark-theme = "navy"
git-repository-url = "https://github.com/you/my-docs"
edit-url-template = "https://github.com/you/my-docs/edit/main/{path}"
additional-css = ["custom.css"]

[output.html.fold]
enable = true
level = 1

git-repository-url adds a repo icon to the menu bar, edit-url-template adds a "Suggest an edit" button on each page, and additional-css loads your stylesheet after the theme's. The fold block collapses sidebar sections below level 1. Defaults from the docs: default-theme is light, preferred-dark-theme is navy, mathjax-support is false, and [output.html.print] is enabled.

Which Markdown Does mdBook Render?

mdBook parses with pulldown-cmark, a CommonMark parser, plus a fixed set of extensions. Those are tables, footnotes, strikethrough, task lists, smart punctuation, heading attributes (# Title { #custom-id .cls }), and definition lists. Admonitions use the GitHub alert style: > [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], and [!CAUTION]. Admonitions and definition lists are on by default in the current docs and can be turned off in [output.html].

What doesn't work: MkDocs-style !!! note blocks, Obsidian wikilinks, and MDX components. Our Markdown callout guide lists the alert syntax mdBook shares with GitHub. Code blocks get syntax highlighting from highlight.js.

Extending an md book with preprocessors

Anything beyond that list comes from a preprocessor, a small program that rewrites chapters before rendering. Two are built in: links, which expands {{#include file.rs}} helpers, and index, which renames README.md to index.md. Third-party ones install with cargo and register with one table in book.toml:

[preprocessor.mermaid]
command = "mdbook-mermaid"

Naming the table [preprocessor.foo] makes mdBook look for an mdbook-foo binary on your PATH, so the command line is optional when the names match. Add optional = true if you don't want a missing binary to fail the build on a contributor's machine.

Draft each chapter below and check the rendering before dropping it into src/. The sample sticks to the CommonMark and GFM subset that both mdBook and this editor render; mdBook-only extensions such as admonitions, footnotes, and heading attributes are best checked with mdbook serve.

How Do You Preview and Build the Site?

mdbook serve --open builds the book, starts a server on localhost:3000, opens your browser, and rebuilds on every save. Use -p 8000 -n 127.0.0.1 to change the port and host.

mdbook build writes the finished site to book/ (or whatever build-dir says). Copy that folder to any static host. mdbook clean deletes it. If your chapters contain Rust code blocks, mdbook test compiles and runs them, which is how the Rust Book keeps its examples honest.

One limitation to plan for: mdBook has no built-in versioning. If you need docs for v1 and v2 side by side, build each tag into its own subfolder and link them from a landing page.

Deploy an mdBook to GitHub Pages

The mdBook wiki's recommended workflow uses the official Pages actions. Set the repository's Pages source to "GitHub Actions" in Settings, then add .github/workflows/deploy.yml:

name: Deploy
on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install mdBook
        run: |
          mkdir bin
          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.5.4/mdbook-v0.5.4-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
          echo "$PWD/bin" >> $GITHUB_PATH
      - run: mdbook build
      - uses: actions/configure-pages@v4
      - uses: actions/upload-pages-artifact@v3
        with:
          path: book
      - uses: actions/deploy-pages@v4

Pinning the version in the download URL keeps builds reproducible; the wiki's variant fetches the latest tag with jq instead. The site appears at https://you.github.io/my-docs/ after the first green run. Readers who write their project docs on GitHub already will find the same conventions in our README guide.

Can I Convert an mdBook to PDF?

Yes, two ways. The built-in route is the print icon at the top right of every built book. It opens print.html, a single page holding every chapter, which you print to PDF from the browser. The [output.html.print] section controls it, including page-break = true to start each chapter on a new page.

For an automated PDF in CI, install the community backend mdbook-pdf with cargo install mdbook-pdf and add an [output.pdf] section to book.toml. It drives headless Chrome through the DevTools Protocol, so Chrome must be available on the build machine, and it relies on the print page being enabled. For a single chapter rather than the whole book, our Markdown to PDF guide covers the simpler options.

Common mdBook Mistakes

Chapter exists but doesn't show up. mdBook only renders files listed in SUMMARY.md. Add the link; a file sitting in src/ on its own is ignored.

Mixed list markers in SUMMARY.md. Starting with - and switching to * breaks parsing of the chapter list. Pick one.

Assets 404 on GitHub Pages. Relative image paths like images/a.png work from src/, but a leading slash (/images/a.png) points at the domain root, not the /my-docs/ subpath. Keep paths relative.

mdBook FAQ

mdBook gives you a fast, dependency-free path from a folder of Markdown to a hosted docs site. Install one binary, describe the structure in SUMMARY.md, tune book.toml, and let GitHub Actions publish book/ on every push. Write and preview each chapter in the editor first, then paste it into src/. Your md book then stays consistent from the first chapter to the PDF export.