mdBook

mdBook is a utility for creating online books from Markdown files. It produces a clean, navigable static site with a sidebar table of contents, full-text search, syntax highlighting, and theming — all from a directory of plain .md files and a single book.toml config.

It's the tool used to write The Rust Programming Language, The Rustonomicon, the Cargo Book, and many other official Rust documentation projects.

Features

• Markdown-based — write content in standard Markdown; mdBook handles the rest
• Built-in search — full-text search across all chapters, powered by Elasticlunr.js, no server required
• Syntax highlighting — code blocks are highlighted via highlight.js with support for dozens of languages
• Live reloading — mdbook serve watches for changes and reloads the browser automatically
• Themes — ships with several built-in themes (Light, Rust, Coal, Navy, Ayu) and supports full custom themes
• Preprocessors — transform the book content programmatically before rendering (MathJax, link expansion, etc.)
• Backends — the default HTML backend can be supplemented with alternative renderers (e.g. PDF, EPUB)
• Configurable — all behaviour controlled via a single book.toml file

Installation

cargo install mdbook

Or via your system package manager:

# Debian / Ubuntu
apt install mdbook

# Fedora
dnf install mdbook

# macOS
brew install mdbook

# Arch Linux
pacman -S mdbook

# Nix
nix-env -iA nixpkgs.mdbook

Quick Start

# Create a new book in a new directory
mdbook init my-book

# Serve locally with live reload
cd my-book
mdbook serve --open

# Build to the book/ output directory
mdbook build

Project Structure

my-book/
├── book.toml         # Configuration
├── book/             # Generated output (do not edit)
└── src/
    ├── SUMMARY.md    # Table of contents — defines chapter order
    ├── chapter-1.md
    └── chapter-2/
        ├── README.md
        └── section.md

The SUMMARY.md file is the heart of an mdBook project — it defines the structure of the book as a nested list of links:

# Summary

- [Introduction](./chapter-1.md)
- [Chapter 2](./chapter-2/README.md)
  - [A Section](./chapter-2/section.md)
- [Contributing](./contributing.md)

Configuration

book.toml controls everything about the build:

[book]
title = "My Documentation"
authors = ["Alice", "Bob"]
description = "A guide to something useful."
language = "en"
src = "src"

[build]
build-dir = "book"

[output.html]
default-theme = "navy"
git-repository-url = "https://github.com/example/my-book"
edit-url-template = "https://github.com/example/my-book/edit/main/{path}"

[output.html.search]
enable = true
limit-results = 20

Preprocessors

mdBook supports preprocessors that transform content before rendering. Install community preprocessors via cargo:

# Render mathematical equations with MathJax
cargo install mdbook-katex

# Admonition blocks (note, warning, tip)
cargo install mdbook-admonish

# Mermaid diagram support
cargo install mdbook-mermaid

Then enable them in book.toml:

[preprocessor.katex]
[preprocessor.admonish]
[preprocessor.mermaid]