Document not found (404)
+This URL is invalid, sorry. Try the search instead!
+ +Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+This URL is invalid, sorry. Try the search instead!
+ +Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+The build command is used to render your book:
+mdbook build
+It will try to parse your SUMMARY.md file to understand the structure of your
+book and fetch the corresponding files. Note that this will also create files
+mentioned in SUMMARY.md which are not yet present.
The rendered output will maintain the same directory structure as the source for +convenience. Large books will therefore remain structured when rendered.
+The build command can take a directory as an argument to use as the book’s
+root instead of the current working directory.
mdbook build path/to/book
+--openWhen you use the --open (-o) flag, mdbook will open the rendered book in
+your default web browser after building it.
--dest-dirThe --dest-dir (-d) option allows you to change the output directory for the
+book. Relative paths are interpreted relative to the current directory. If
+not specified it will default to the value of the build.build-dir key in
+book.toml, or to ./book.
Note: The build command copies all files (excluding files with .md extension) from the source directory
+into the build directory.
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+The clean command is used to delete the generated book and any other build +artifacts.
+mdbook clean
+The clean command can take a directory as an argument to use as the book’s
+root instead of the current working directory.
mdbook clean path/to/book
+--dest-dirThe --dest-dir (-d) option allows you to override the book’s output
+directory, which will be deleted by this command. Relative paths are interpreted
+relative to the current directory. If not specified it will default to the
+value of the build.build-dir key in book.toml, or to ./book.
mdbook clean --dest-dir=path/to/book
+path/to/book could be absolute or relative.
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+The completions command is used to generate auto-completions for some common shells.
+This means when you type mdbook in your shell, you can then press your shell’s auto-complete key (usually the Tab key) and it may display what the valid options are, or finish partial input.
The completions first need to be installed for your shell:
+# bash
+mdbook completions bash > ~/.local/share/bash-completion/completions/mdbook
+# oh-my-zsh
+mdbook completions zsh > ~/.oh-my-zsh/completions/_mdbook
+autoload -U compinit && compinit
+The command prints a completion script for the given shell.
+Run mdbook completions --help for a list of supported shells.
Where to place the completions depend on which shell you are using and your operating system. +Consult your shell’s documentation for more information one where to place the script.
+ +Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+The mdbook command-line tool is used to create and build books.
+After you have installed mdbook, you can run the mdbook help command in your terminal to view the available commands.
This following sections provide in-depth information on the different commands available.
+mdbook init <directory> — Creates a new book with minimal boilerplate to start with.mdbook build — Renders the book.mdbook watch — Rebuilds the book any time a source file changes.mdbook serve — Runs a web server to view the book, and rebuilds on changes.mdbook test — Tests Rust code samples.mdbook clean — Deletes the rendered output.mdbook completions — Support for shell auto-completion.Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+There is some minimal boilerplate that is the same for every new book. It’s for
+this purpose that mdBook includes an init command.
The init command is used like this:
mdbook init
+When using the init command for the first time, a couple of files will be set
+up for you:
book-test/
+├── book
+└── src
+ ├── chapter_1.md
+ └── SUMMARY.md
+The src directory is where you write your book in markdown. It contains all
+the source files, configuration files, etc.
The book directory is where your book is rendered. All the output is ready
+to be uploaded to a server to be seen by your audience.
The SUMMARY.md is the skeleton of your
+book, and is discussed in more detail in another
+chapter.
When a SUMMARY.md file already exists, the init command will first parse it
+and generate the missing files according to the paths used in the SUMMARY.md.
+This allows you to think and create the whole structure of your book and then
+let mdBook generate it for you.
The init command can take a directory as an argument to use as the book’s root
+instead of the current working directory.
mdbook init path/to/book
+--themeWhen you use the --theme flag, the default theme will be copied into a
+directory called theme in your source directory so that you can modify it.
The theme is selectively overwritten, this means that if you don’t want to +overwrite a specific file, just delete it and the default file will be used.
+--titleSpecify a title for the book. If not supplied, an interactive prompt will ask for +a title.
+mdbook init --title="my amazing book"
+--ignoreCreate a .gitignore file configured to ignore the book directory created when building a book.
+If not supplied, an interactive prompt will ask whether it should be created.
mdbook init --ignore=none
+mdbook init --ignore=git
+--forceSkip the prompts to create a .gitignore and for the title for the book.
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+The serve command is used to preview a book by serving it via HTTP at
+localhost:3000 by default:
mdbook serve
+The serve command watches the book’s src directory for
+changes, rebuilding the book and refreshing clients for each change; this includes
+re-creating deleted files still mentioned in SUMMARY.md! A websocket
+connection is used to trigger the client-side refresh.
Note: The serve command is for testing a book’s HTML output, and is not
+intended to be a complete HTTP server for a website.
The serve command can take a directory as an argument to use as the book’s
+root instead of the current working directory.
mdbook serve path/to/book
+The serve hostname defaults to localhost, and the port defaults to 3000. Either option can be specified on the command line:
mdbook serve path/to/book -p 8000 -n 127.0.0.1
+--openWhen you use the --open (-o) flag, mdbook will open the book in your
+default web browser after starting the server.
--dest-dirThe --dest-dir (-d) option allows you to change the output directory for the
+book. Relative paths are interpreted relative to the current directory. If
+not specified it will default to the value of the build.build-dir key in
+book.toml, or to ./book.
--watcherThere are different backends used to determine when a file has changed.
+poll (default) — Checks for file modifications by scanning the filesystem every second.native — Uses the native operating system facilities to receive notifications when files change.
+This can have less constant overhead, but may not be as reliable as the poll based watcher. See these issues for more information: #383 #1441 #1707 #2035 #2102The serve command will not automatically trigger a build for files listed in
+the .gitignore file in the book root directory. The .gitignore file may
+contain file patterns described in the gitignore
+documentation. This can be useful for
+ignoring temporary files created by some editors.
Note: Only the .gitignore from the book root directory is used. Global
+$HOME/.gitignore or .gitignore files in parent directories are not used.
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+When writing a book, you sometimes need to automate some tests. For example, +The Rust Programming Book uses a lot +of code examples that could get outdated. Therefore it is very important for +them to be able to automatically test these code examples.
+mdBook supports a test command that will run all available tests in a book. At
+the moment, only Rust tests are supported.
rustdoc doesn’t test code blocks which contain the ignore attribute:
```rust,ignore
+fn main() {}
+```
+rustdoc also doesn’t test code blocks which specify a language other than Rust:
+```markdown
+**Foo**: _bar_
+```
+rustdoc does test code blocks which have no language specified:
+```
+This is going to cause an error!
+```
+The test command can take a directory as an argument to use as the book’s root
+instead of the current working directory.
mdbook test path/to/book
+--library-pathThe --library-path (-L) option allows you to add directories to the library
+search path used by rustdoc when it builds and tests the examples. Multiple
+directories can be specified with multiple options (-L foo -L bar) or with a
+comma-delimited list (-L foo,bar). The path should point to the Cargo
+build cache deps directory that
+contains the build output of your project. For example, if your Rust project’s book is in a directory
+named my-book, the following command would include the crate’s dependencies when running test:
mdbook test my-book -L target/debug/deps/
+See the rustdoc command-line documentation
+for more information.
--chapterThe --chapter (-c) option allows you to test a specific chapter of the
+book using the chapter name or the relative path to the chapter.
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+The watch command is useful when you want your book to be rendered on every
+file change. You could repeatedly issue mdbook build every time a file is
+changed. But using mdbook watch once will watch your files and will trigger a
+build automatically whenever you modify a file; this includes re-creating
+deleted files still mentioned in SUMMARY.md!
The watch command can take a directory as an argument to use as the book’s
+root instead of the current working directory.
mdbook watch path/to/book
+--openWhen you use the --open (-o) option, mdbook will open the rendered book in
+your default web browser.
--dest-dirThe --dest-dir (-d) option allows you to change the output directory for the
+book. Relative paths are interpreted relative to the current directory. If
+not specified it will default to the value of the build.build-dir key in
+book.toml, or to ./book.
--watcherThere are different backends used to determine when a file has changed.
+poll (default) — Checks for file modifications by scanning the filesystem every second.native — Uses the native operating system facilities to receive notifications when files change.
+This can have less constant overhead, but may not be as reliable as the poll based watcher. See these issues for more information: #383 #1441 #1707 #2035 #2102The watch command will not automatically trigger a build for files listed in
+the .gitignore file in the book root directory. The .gitignore file may
+contain file patterns described in the gitignore
+documentation. This can be useful for
+ignoring temporary files created by some editors.
Note: Only .gitignore from book root directory is used. Global
+$HOME/.gitignore or .gitignore files in parent directories are not used.
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+mdbook in continuous integrationThere are a variety of services such as GitHub Actions or GitLab CI/CD which can be used to test and deploy your book automatically.
+The following provides some general guidelines on how to configure your service to run mdBook. +Specific recipes can be found at the Automated Deployment wiki page.
+There are several different strategies for installing mdBook. +The particular method depends on your needs and preferences.
+Perhaps the easiest method is to use the pre-compiled binaries found on the GitHub Releases page.
+A simple approach would be to use the popular curl CLI tool to download the executable:
mkdir bin
+curl -sSL https://github.com/rust-lang/mdBook/releases/download/0.5.2/mdbook-0.5.2-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
+bin/mdbook build
+Some considerations for this approach:
+Building from source will require having Rust installed. +Some services have Rust pre-installed, but if your service does not, you will need to add a step to install it.
+After Rust is installed, cargo install can be used to build and install mdBook.
+We recommend using a SemVer version specifier so that you get the latest non-breaking version of mdBook.
+For example:
cargo install mdbook --no-default-features --features search --vers "^0.4" --locked
+This includes several recommended options:
+--no-default-features — Disables features like the HTTP server used by mdbook serve that is likely not needed on CI.
+This will speed up the build time significantly.--features search — Disabling default features means you should then manually enable features that you want, such as the built-in search capability.--vers "^0.4" — This will install the most recent version of the 0.4 series.
+However, versions after like 0.5.0 won’t be installed, as they may break your build.
+Cargo will automatically upgrade mdBook if you have an older version already installed.--locked — This will use the dependencies that were used when mdBook was released.
+Without --locked, it will use the latest version of all dependencies, which may include some fixes since the last release, but may also (rarely) cause build problems.You will likely want to investigate caching options, as building mdBook can be somewhat slow.
+You may want to run tests using mdbook test every time you push a change or create a pull request.
+This can be used to validate Rust code examples in the book.
This will require having Rust installed. +Some services have Rust pre-installed, but if your service does not, you will need to add a step to install it.
+Other than making sure the appropriate version of Rust is installed, there’s not much more than just running mdbook test from the book directory.
You may also want to consider running other kinds of tests, like mdbook-linkcheck which will check for broken links. +Or if you have your own style checks, spell checker, or any other tests it might be good to run them in CI.
+You may want to automatically deploy your book. +Some may want to do this every time a change is pushed, and others may want to only deploy when a specific release is tagged.
+You’ll also need to understand the specifics on how to push a change to your web service. +For example, GitHub Pages just requires committing the output onto a specific git branch. +Other services may require using something like SSH to connect to a remote server.
+The basic outline is that you need to run mdbook build to generate the output, and then transfer the files (which are in the book directory) to the correct location.
You may then want to consider if you need to invalidate any caches on your web service.
+See the Automated Deployment wiki page for examples of various different services.
+mdBook automatically generates a 404 page to be used for broken links.
+The default output is a file named 404.html at the root of the book.
+Some services like GitHub Pages will automatically use this page for broken links.
+For other services, you may want to consider configuring the web server to use this page as it will provide the reader navigation to get back to the book.
If your book is not deployed at the root of the domain, then you should set the output.html.site-url setting so that the 404 page works correctly.
+It needs to know where the book is deployed in order to load the static files (like CSS) correctly.
+For example, this guide is deployed at https://rust-lang.github.io/mdBook/, and the site-url setting is configured like this:
# book.toml
+[output.html]
+site-url = "/mdBook/"
+You can customize the look of the 404 page by creating a file named src/404.md in your book.
+If you want to use a different filename, you can set output.html.input-404 to a different filename.