mdBook is a tool for rendering a collection of markdown documents into a form more suitable for end users like HTML or EPUB. It offers a command line interface, but this crate can be used if more control is required.
This is the API doc, the user guide is also available if you want information about the command line tool, format, structure etc. It is also rendered with mdBook to showcase the features and default theme.
Some reasons why you would want to use the crate (over the cli):
- Integrate mdbook in a current project
- Extend the capabilities of mdBook
- Do some processing or test before building your book
- Accessing the public API to help create a new Renderer
Note: While we try to ensure
mdbook’s command-line interface and behaviour are backwards compatible, the tool’s internals are still evolving and being iterated on. If you wish to prevent accidental breakages it is recommended to pin any tools building on top of the
mdbookcrate to a specific release.
If creating a new book from scratch, you’ll want to get a
use mdbook::MDBook; use mdbook::config::Config; let root_dir = "/path/to/book/root"; // create a default config and change a couple things let mut cfg = Config::default(); cfg.book.title = Some("My Book".to_string()); cfg.book.authors.push("Michael-F-Bryan".to_string()); MDBook::init(root_dir) .create_gitignore(true) .with_config(cfg) .build() .expect("Book generation failed");
You can also load an existing book and build it.
use mdbook::MDBook; let root_dir = "/path/to/book/root"; let mut md = MDBook::load(root_dir) .expect("Unable to load the book"); md.build().expect("Building failed");
Implementing a new Backend
mdbook has a fairly flexible mechanism for creating additional backends
for your book. The general idea is you’ll add an extra table in the book’s
book.toml which specifies an executable to be invoked by
executable will then be called during a build, with an in-memory
RenderContext) of the book being passed to the
RenderContext gives the backend access to the contents of
book.toml and lets it know which directory all generated artefacts should
be placed in. For a much more in-depth explanation, consult the relevant
chapter in the For Developers section of the user guide.
To make creating a backend easier, the
mdbook crate can be imported
directly, making deserializing the
RenderContext easy and giving you
access to the various methods for working with the
- The internal representation of a book and infrastructure for loading it from disk and building it.
- Mdbook’s configuration system.
- The error types used through out this crate.
- Book preprocessing.
mdbook’s low level rendering interface.
- Enum representing any type of item which can be added to a book.
- The current version of