Crate mdbook [−] [src]

mdBook

mdBook is similar to Gitbook but implemented in Rust. It offers a command line interface, but can also be used as a regular crate.

This is the API doc, but you can find a less "low-level" documentation here that contains 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
  • Write a new Renderer
  • ...

Example

extern crate mdbook;

use mdbook::MDBook;

fn main() {
    let mut book =  MDBook::new("my-book")        // Path to root
                        .with_source("src")       // Path from root to source directory
                        .with_destination("book") // Path from root to output directory
                        .read_config()            // Parse book.toml configuration file
                        .expect("I don't handle configuration file errors, but you should!");

    book.build().unwrap();                        // Render the book
}

Implementing a new Renderer

If you want to create a new renderer for mdBook, the only thing you have to do is to implement the Renderer trait

And then you can swap in your renderer like this:

let book = MDBook::new("my-book").set_renderer(Box::new(your_renderer));

If you make a renderer, you get the book constructed in form of Vec<BookItems> and you get the book config in a BookConfig struct.

It's your responsability to create the necessary files in the correct directories.

utils

I have regrouped some useful functions in the utils module, like the following function utils::fs::create_file(path: &Path)

This function creates a file and returns it. But before creating the file it checks every directory in the path to see if it exists, and if it does not it will be created.

Make sure to take a look at it.

Reexports

pub use book::MDBook;
pub use book::BookItem;
pub use renderer::Renderer;

Modules

book
config
errors

The error types used through out this crate.
renderer
theme
utils