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

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

Quick Reference

Create a new book

bash
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

markdown
# 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

toml
[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

bash
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