mdbook

mdBook Documentation

Complete reference for mdBook, the Rust-based tool for creating books from Markdown. Auto-generated from the official guide at https://github.com/rust-lang/mdBook.

The references/ directory contains the full, unmodified guide markdown, updated daily.

Directives

Base all answers on the official mdBook documentation in the reference files below.
Use correct book.toml (TOML) syntax for configuration examples.
Use correct SUMMARY.md format for table of contents structure.
Distinguish between built-in preprocessors (links, index) and custom preprocessors.
Distinguish between built-in renderers (HTML) and alternative backends (pdf, epub, etc.).

Reference Files

Identify the topic from the user's question, then read the matching reference file:

Getting Started

Topic	File
Overview and introduction	`references/overview.md`
Installation (cargo, binaries)	`references/installation.md`
Creating a new book	`references/creating-a-book.md`
Reading / navigating books	`references/reading-books.md`

CLI

Topic	File
All CLI commands (init, build, watch, serve, test, clean, completions)	`references/cli.md`

Book Format

Topic	File
SUMMARY.md structure and syntax	`references/summary-format.md`
Markdown features and extensions	`references/markdown.md`
mdBook-specific features (hiding code, include, playground)	`references/mdbook-specific.md`
MathJax support	`references/mathjax.md`

Configuration

Topic	File
book.toml (general, preprocessors, renderers, environment variables)	`references/configuration.md`

Theme

Topic	File
Theme customization (index.hbs, syntax highlighting, editor)	`references/theme.md`

For Developers

Topic	File
Writing preprocessors and backends (Rust API)	`references/for-developers.md`

Deployment

Topic	File
CI/CD (GitHub Actions, GitLab CI)	`references/continuous-integration.md`

Live Fetching

When reference files are insufficient, fetch the latest docs from raw GitHub:

https://raw.githubusercontent.com/rust-lang/mdBook/main/guide/src/<path>.md

Examples:

https://raw.githubusercontent.com/rust-lang/mdBook/main/guide/src/format/configuration/general.md
https://raw.githubusercontent.com/rust-lang/mdBook/main/guide/src/cli/build.md
https://raw.githubusercontent.com/rust-lang/mdBook/main/guide/src/format/theme/syntax-highlighting.md

Strategy

Identify the topic from the user's question.
Read the matching reference file from the tables above.
Answer with correct TOML syntax for book.toml and Markdown for SUMMARY.md.
If more detail is needed, fetch from the corresponding raw GitHub URL.
For custom preprocessors/backends, reference references/for-developers.md.
For CI deployment, check references/continuous-integration.md.

Quick Reference

Create a new book

mdbook init my-book
cd my-book
mdbook serve --open    # preview at http://localhost:3000

Project structure

my-book/
├── book.toml          # Configuration
├── src/
│   ├── SUMMARY.md     # Table of contents
│   ├── chapter_1.md
│   └── chapter_2/
│       ├── section_1.md
│       └── section_2.md
└── book/              # Generated output (after build)

SUMMARY.md syntax

# Summary

[Introduction](README.md)

- [Chapter 1](chapter_1.md)
  - [Section 1.1](chapter_1/section_1.md)
- [Chapter 2](chapter_2.md)

---

[Appendix](appendix.md)

book.toml basics

[book]
title = "My Book"
authors = ["Author Name"]
language = "en"
src = "src"

[build]
build-dir = "book"

[output.html]
default-theme = "light"
preferred-dark-theme = "ayu"
git-repository-url = "https://github.com/user/repo"

Build commands

mdbook build              # build to book/
mdbook serve              # live preview server
mdbook watch              # rebuild on changes
mdbook test               # test Rust code samples
mdbook clean              # remove build artifacts