1//! # mdBook
2//!
3//! **mdBook** is a tool for rendering a collection of markdown documents into
4//! a form more suitable for end users like HTML or EPUB. It offers a command
5//! line interface, but this crate can be used if more control is required.
6//!
7//! This is the API doc, the [user guide] is also available if you want
8//! information about the command line tool, format, structure etc. It is also
9//! rendered with mdBook to showcase the features and default theme.
10//!
11//! Some reasons why you would want to use the crate (over the cli):
12//!
13//! - Integrate mdbook in a current project
14//! - Extend the capabilities of mdBook
15//! - Do some processing or test before building your book
16//! - Accessing the public API to help create a new Renderer
17//! - ...
18//!
19//! > **Note:** While we try to ensure `mdbook`'s command-line interface and
20//! > behaviour are backwards compatible, the tool's internals are still
21//! > evolving and being iterated on. If you wish to prevent accidental
22//! > breakages it is recommended to pin any tools building on top of the
23//! > `mdbook` crate to a specific release.
24//!
25//! # Examples
26//!
27//! If creating a new book from scratch, you'll want to get a `BookBuilder` via
28//! the `MDBook::init()` method.
29//!
30//! ```rust,no_run
31//! use mdbook::MDBook;
32//! use mdbook::config::Config;
33//!
34//! let root_dir = "/path/to/book/root";
35//!
36//! // create a default config and change a couple things
37//! let mut cfg = Config::default();
38//! cfg.book.title = Some("My Book".to_string());
39//! cfg.book.authors.push("Michael-F-Bryan".to_string());
40//!
41//! MDBook::init(root_dir)
42//! .create_gitignore(true)
43//! .with_config(cfg)
44//! .build()
45//! .expect("Book generation failed");
46//! ```
47//!
48//! You can also load an existing book and build it.
49//!
50//! ```rust,no_run
51//! use mdbook::MDBook;
52//!
53//! let root_dir = "/path/to/book/root";
54//!
55//! let mut md = MDBook::load(root_dir)
56//! .expect("Unable to load the book");
57//! md.build().expect("Building failed");
58//! ```
59//!
60//! ## Implementing a new Backend
61//!
62//! `mdbook` has a fairly flexible mechanism for creating additional backends
63//! for your book. The general idea is you'll add an extra table in the book's
64//! `book.toml` which specifies an executable to be invoked by `mdbook`. This
65//! executable will then be called during a build, with an in-memory
66//! representation ([`RenderContext`]) of the book being passed to the
67//! subprocess via `stdin`.
68//!
69//! The [`RenderContext`] gives the backend access to the contents of
70//! `book.toml` and lets it know which directory all generated artefacts should
71//! be placed in. For a much more in-depth explanation, consult the [relevant
72//! chapter] in the *For Developers* section of the user guide.
73//!
74//! To make creating a backend easier, the `mdbook` crate can be imported
75//! directly, making deserializing the `RenderContext` easy and giving you
76//! access to the various methods for working with the [`Config`].
77//!
78//! [user guide]: https://rust-lang.github.io/mdBook/
79//! [`RenderContext`]: renderer::RenderContext
80//! [relevant chapter]: https://rust-lang.github.io/mdBook/for_developers/backends.html
81//! [`Config`]: config::Config
82
83#![deny(missing_docs)]
84#![deny(rust_2018_idioms)]
85
86pub mod book;
87pub mod config;
88pub mod preprocess;
89pub mod renderer;
90pub mod theme;
91pub mod utils;
92
93/// The current version of `mdbook`.
94///
95/// This is provided as a way for custom preprocessors and renderers to do
96/// compatibility checks.
97pub const MDBOOK_VERSION: &str = env!("CARGO_PKG_VERSION");
98
99pub use crate::book::BookItem;
100pub use crate::book::MDBook;
101pub use crate::config::Config;
102pub use crate::renderer::Renderer;
103
104/// The error types used through out this crate.
105pub mod errors {
106 pub(crate) use anyhow::{bail, ensure, Context};
107 pub use anyhow::{Error, Result};
108}
109