mdbook

Create an mdbook project in the current directory

$ mdbook init

$ mdbook init [path/to/directory]

$ mdbook clean

$ mdbook serve

$ mdbook watch

mdbook <SUBCOMMAND> [OPTIONS]

Common Subcommands:
mdbook init [DIRECTORY]
mdbook build [DIRECTORY]
mdbook serve [DIRECTORY]
mdbook watch [DIRECTORY]
mdbook clean [DIRECTORY]
mdbook test [DIRECTORY]

init --force, -f
    Overwrite existing files when initializing a new book.

init --theme
    Include the default theme files in the new book's directory.

init --title <TITLE>
    Set the title of the new book.

init --description <DESCRIPTION>
    Set a short description for the new book.

init --language <LANG>
    Set the primary language of the new book (e.g., 'en').

init --authors <AUTHORS>
    Set the author(s) of the new book (comma-separated).

init --src <DIR>
    Specify the source directory for Markdown files (default: 'src').

build --dest-dir <DIR>, -d <DIR>
    Specify the output directory for the built book (default: 'book').

build --open, -o
    Open the built book in your default web browser.

serve --port <PORT>, -p <PORT>
    Specify the port for the development server to listen on (default: 3000).

serve --hostname <HOSTNAME>
    Specify the hostname for the development server (default: 'localhost').

serve --open, -o
    Open the served book in your default web browser.

serve --watch, -w
    Watch for file changes and automatically rebuild/reload the book.

watch --open, -o
    Open the book in your default web browser after the first build.

watch --port <PORT>, -p <PORT>
    Specify the port for the live-reloading server (default: 3000).

watch --hostname <HOSTNAME>
    Specify the hostname for the live-reloading server (default: 'localhost').

mdbook is a powerful command-line tool written in Rust, designed to transform Markdown files into a static, navigable HTML website, often referred to as a "book." Inspired by GitBook, it offers a fast, simple, and opinionated way to generate documentation, tutorials, or online books. Key features include automatic table of contents generation, a built-in search function, extensive theming capabilities, and multi-language support. It leverages a book.toml configuration file to define project metadata and build settings, and a SUMMARY.md file to structure the book's content. mdbook also provides a development server with live-reloading, making the authoring process highly efficient. It has become a popular choice within the Rust community for project documentation, including the official Rust programming language book itself.

mdbook is highly optimized for Markdown content; while extensible, it may require custom development for very complex document features or non-Markdown sources.
Theming customization requires knowledge of web technologies like HTML, CSS, and JavaScript. Error messages for configuration issues can sometimes be concise.

An mdbook project is defined by a book.toml file at its root, which configures metadata (title, authors, language), build options (source and output directories), and more advanced settings like preprocessors and renderers.
The book's content resides primarily in the 'src' directory, with SUMMARY.md playing a crucial role in defining the book's structure and table of contents, mapping chapter titles to Markdown files.

mdbook ships with a functional default theme, but it offers extensive customization options. Users can override any part of the default theme (CSS, JavaScript, HTML templates) by placing custom files in a 'theme' directory within the book's root.
This flexibility allows for complete control over the book's appearance and behavior, enabling users to brand their documentation or tailor it to specific visual requirements.

mdbook originated within the Rust community, initially championed by the Rust Language Documentation team, to create a robust and efficient documentation tool. It was conceived as an alternative to existing solutions like GitBook, which faced performance and maintenance challenges. First released around 2016, its development in Rust ensured high performance, memory safety, and easy cross-platform compilation. It rapidly became the standard for Rust projects, including the official Rust book, solidifying its role as a key documentation generator in the open-source ecosystem.

pandoc(1), sphinx(1)