mdBook Markdown books

Version 0.5.4 · source

Postcard A5 A4 A4 landscape A3 A3 landscape Letter Tabloid

Light · Postcard 102 × 152 mm · PDF

Dark · Postcard 102 × 152 mm · PDF

Ink saver · Postcard 102 × 152 mm · PDF

Light · A5 148 × 210 mm · PDF

Dark · A5 148 × 210 mm · PDF

Ink saver · A5 148 × 210 mm · PDF

Light · A4 210 × 297 mm · PDF

Dark · A4 210 × 297 mm · PDF

Ink saver · A4 210 × 297 mm · PDF

Light · A4 landscape 297 × 210 mm · PDF

Dark · A4 landscape 297 × 210 mm · PDF

Ink saver · A4 landscape 297 × 210 mm · PDF

Light · A3 297 × 420 mm · PDF

Dark · A3 297 × 420 mm · PDF

Ink saver · A3 297 × 420 mm · PDF

Light · A3 landscape 420 × 297 mm · PDF

Dark · A3 landscape 420 × 297 mm · PDF

Ink saver · A3 landscape 420 × 297 mm · PDF

Light · Letter 8.5 × 11 in · PDF

Dark · Letter 8.5 × 11 in · PDF

Ink saver · Letter 8.5 × 11 in · PDF

Light · Tabloid 11 × 17 in · PDF

Dark · Tabloid 11 × 17 in · PDF

Ink saver · Tabloid 11 × 17 in · PDF

Start here

mdbook init <dir>

Scaffold a new book

mdbook serve --open

Live preview in browser

mdbook build

Render to book/

mdbook test

Check Rust snippets

mdbook clean

Delete the output

src/SUMMARY.md

Table of contents

book.toml

Book configuration

mdbook watch

Rebuild on change

Concepts

src/*.md chapters
Preprocessors links, index
Renderers html, custom
book/ static site

Create and build

mdbook init

Create a book in the current directory

mdbook init <dir> --title
                    "<title>"

Create a book in a new directory

mdbook init --force

Skip the title and .gitignore prompts

mdbook init --ignore git

Also write a .gitignore for book/

mdbook init --theme

Copy the default theme to edit it

mdbook build

Render the book to book/

mdbook build <dir>

Build a book in another directory

mdbook build -o

Build, then open in the browser

mdbook build -d <dir>

Write output to a different directory

mdbook clean

Delete the rendered output

mdbook clean -d <dir>

Delete a specific output directory

Preview

mdbook serve

Serve and rebuild on every change

mdbook serve -o

Serve and open the browser

mdbook serve -p <port>

Use another port (default 3000)

mdbook serve -n <host>

Bind to another hostname

Use 0.0.0.0 to reach the preview from other machines on the network.

mdbook serve --watcher native

Use OS file events instead of polling

mdbook watch

Rebuild on change without a server

mdbook watch -o

Rebuild on change and open the output

Test and tooling

mdbook test

Compile and run all Rust code blocks

mdbook test -c <chapter>

Test one chapter by name or path

mdbook test -L <deps-dir>

Add a library search path for rustdoc

Point it at target/debug/deps to test snippets that use your crate.

mdbook completions <shell>

Print a shell completion script

mdbook completions bash > <file>

Install bash completions

mdbook help

List commands

mdbook --version

Show the installed version

SUMMARY.md

# Summary

Optional title (ignored by the parser)

[Intro](intro.md)

Prefix chapter, unnumbered, before the list

- [Chapter](chapter.md)

Numbered chapter

- [Sub](sub.md)

Indent four spaces for a sub-chapter

[Title]()

Draft chapter with no file yet

# Part Title

Group the chapters that follow

---

Horizontal separator in the sidebar

[Appendix](app.md)

Suffix chapter, unnumbered, after the list

book.toml

[book] title = "<title>"

Book title

[book] authors = ["<name>"]

Author list

[book] description = "<text>"

Meta description for each page

[book] src = "<dir>"

Source directory (default src)

[book] language = "<code>"

Language for the HTML lang attribute

[build] build-dir = "<dir>"

Output directory (default book)

[build] create-missing = false

Fail on files missing from SUMMARY

[build] extra-watch-dirs = ["<dir>"]

Also watch dirs outside src

[rust] edition = "2021"

Edition for Rust snippets (default 2015)

[output.html] default-theme = "<name>"

Pick the default colour theme

[output.html] git-repository-url =
                    "<url>"

Add a repository link in the header

[output.html] edit-url-template =
                    "<url>"

Per-page edit link, with {path}

[output.html] site-url = "/<path>/"

Base URL when hosted in a subpath

[output.html.search] enable = false

Turn off the search box

[output.html.fold] enable = true

Collapsible sidebar sections

[output.html.redirect]

Map old page paths to new ones

[preprocessor.<name>]

Enable a preprocessor

[output.<name>] command = "<cmd>"

Run a custom backend executable

Markdown and code

{{#include <file>}}

Insert a whole file

{{#include <file>:2:10}}

Insert lines 2 to 10

{{#include <file>:<anchor>}}

Insert the part between ANCHOR markers

{{#rustdoc_include <file>:2}}

Show lines, keep the rest hidden for tests

{{#playground <file>}}

Insert a runnable Rust file

{{#title <text>}}

Set the page title only

```rust,ignore

Highlight, but skip the test

```rust,no_run

Compile in tests, never run

```rust,should_panic

Test expects a panic

```rust,compile_fail

Test expects a compile error

```rust,editable

Make the snippet editable in the page

```rust,noplayground

Remove the play button

# let x = 1;

Hide a Rust line (still compiled)

## text

Show a line that starts with #

```rust,edition2021

Force an edition for one block

python = "~"

hidelines prefix in [output.html.code.hidelines]

Recipes

New book with live preview

mdbook init mybook --title "My Book"cd mybookmdbook serve --open

Test snippets against your crate

cargo buildmdbook test -L target/debug/deps

book.toml for a hosted repo

[book]title = "Guide"src = "src"[rust]edition = "2021"[output.html]git-repository-url = "https://github.com/<user>/<repo>"site-url = "/<repo>/"

Build for CI

mdbook build -d publicmdbook test