#mdbook #keeper

bin+lib mdbook-keeper

An improved testing experience for mdbook

9 releases

0.2.4 Feb 26, 2023
0.2.3 Feb 26, 2023
0.2.0 Jan 6, 2023
0.1.3 Oct 17, 2022

#445 in Text processing

Download history 2/week @ 2022-11-27 7/week @ 2022-12-04 5/week @ 2022-12-11 5/week @ 2022-12-18 9/week @ 2022-12-25 31/week @ 2023-01-01 14/week @ 2023-01-08 1/week @ 2023-01-15 5/week @ 2023-01-22 10/week @ 2023-01-29 58/week @ 2023-02-05 31/week @ 2023-02-12 14/week @ 2023-02-19 62/week @ 2023-02-26 5/week @ 2023-03-05 13/week @ 2023-03-12

96 downloads per month


878 lines


"Book-keeping for your testcases."

mdBook-keeper adds more testing features to mdBook, specifically support for third-party crates, and testing while compiling. My hope is that it will be merged into mdBook at some point in the future.

Current goals of this project include:

  • Specifying third-party crates to include when testing a mdbook. (DONE)
  • Running tests as part of the build, rather than as a seperate command. (DONE)
  • Only running tests on code that has changed. (DONE)
  • The ability to see compilation or build output as part of the book (both to aid in debugging, and possibly also as a permanent output). (TODO)


To install this tool, run:

$ cargo install mdbook-keeper

Then add it as a pre-processor. Add this snippet to the bottom of your book.toml

command = "mdbook-keeper"

Finally, build your book as normal:

$ mdbook build path/to/book

Using Crates From An Existing Project

Many use-cases of mdbook involve the documentation being a sub-folder of a project. To make it easy to support this use-case, you can simply tell mdbook-keeper which directory the Cargo.toml (and Cargo.lock, if present) exists in. To do this, add the following line after the [preprocessor.keeper] line in your book.toml:

# NOTE: the file Cargo.toml should exist at this path.
manifest_dir = "../../path/to/project/"

Because rustc does not read a Cargo.toml file, it requires that any crates you want to use be declared with either extern crate <name>; or its --extern option. To simplify things, if you always want to extern a crate, simply write the following under [preprocessor.keeper]. This will pass the --extern option to rustc.

externs = ["my_crate", "name_here"]

If you have built the existing project already, you may find it useful to get mdbook-keeper to use the same target directory as the project. This means that packages don't need to get re-built in two different locations when building the book and the project. Add the following line after the [preprocessor.keeper] line in your book.toml:

# NOTE: the `debug` folder should exist at this path.
target_dir = "../../path/to/target/"

Using Extra Crates When In A Stand-Alone Book

If you don't have an existing project, the current solution is to create a minimal project inside the book repo. The project need only contain Cargo.toml, Cargo.lock, and src/main.rs (or src/lib.rs). Place all required dependencies in the Cargo.toml.

Then, point manifest_dir to that directory, as shown above.

Other Configuration Options

All of these options can be placed in the book.toml file, after [preprocessor.keeper].

  • test_dir this directory is where all intermediate work is stored, including a target/ folder if one is not specified. If you don't like the default location (./doctest_cache/), you can change it here.
  • terminal_colors sets whether to show ANSI terminal colours in rustc output. It defaults to true only if you are on a TTY, and false otherwise.

Note on differences to DocTest

mdbook-keeper is not a perfect replacement to doctest. This is for a few reasons:

  • Because much of the code is based on rust-skeptic, we use their rules for parsing markdown files. See their project for a detailed list of rules, but in short; we don't automatically insert a main() function for you, and you must tag codeblocks as rust to have them run.
  • The output format is different, mainly because replicating doctest seemed unnecessary, complex, and brittle.
  • This runs on mdbook build, rather than as a seperate command.

Thanks to Skeptic

Some of the code in this project was taken from the rust-skeptic project. Indeed, this project was briefly named mdbook-skeptic to acknowledge the code they wrote which was incredibly useful in writing this crate.


All the code in this repository is released under the APACHE-2.0 or MIT licenses.


~784K SLoC