]>
Commit | Line | Data |
---|---|---|
cc61c64b XL |
1 | //! # mdBook |
2 | //! | |
83c7162d XL |
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. | |
cc61c64b | 6 | //! |
2c00a5a8 XL |
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. | |
cc61c64b XL |
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 | |
2c00a5a8 | 16 | //! - Accessing the public API to help create a new Renderer |
cc61c64b XL |
17 | //! - ... |
18 | //! | |
83c7162d XL |
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 | //! | |
2c00a5a8 | 25 | //! # Examples |
cc61c64b | 26 | //! |
2c00a5a8 XL |
27 | //! If creating a new book from scratch, you'll want to get a `BookBuilder` via |
28 | //! the `MDBook::init()` method. | |
cc61c64b | 29 | //! |
2c00a5a8 | 30 | //! ```rust,no_run |
cc61c64b | 31 | //! use mdbook::MDBook; |
2c00a5a8 | 32 | //! use mdbook::config::Config; |
cc61c64b | 33 | //! |
2c00a5a8 | 34 | //! let root_dir = "/path/to/book/root"; |
cc61c64b | 35 | //! |
2c00a5a8 XL |
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()); | |
cc61c64b | 40 | //! |
2c00a5a8 XL |
41 | //! MDBook::init(root_dir) |
42 | //! .create_gitignore(true) | |
43 | //! .with_config(cfg) | |
44 | //! .build() | |
45 | //! .expect("Book generation failed"); | |
cc61c64b | 46 | //! ``` |
cc61c64b | 47 | //! |
2c00a5a8 | 48 | //! You can also load an existing book and build it. |
cc61c64b | 49 | //! |
2c00a5a8 XL |
50 | //! ```rust,no_run |
51 | //! use mdbook::MDBook; | |
cc61c64b | 52 | //! |
2c00a5a8 | 53 | //! let root_dir = "/path/to/book/root"; |
cc61c64b | 54 | //! |
2c00a5a8 XL |
55 | //! let mut md = MDBook::load(root_dir) |
56 | //! .expect("Unable to load the book"); | |
57 | //! md.build().expect("Building failed"); | |
58 | //! ``` | |
cc61c64b | 59 | //! |
2c00a5a8 XL |
60 | //! ## Implementing a new Backend |
61 | //! | |
83c7162d | 62 | //! `mdbook` has a fairly flexible mechanism for creating additional backends |
2c00a5a8 XL |
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 | |
83c7162d | 65 | //! executable will then be called during a build, with an in-memory |
2c00a5a8 | 66 | //! representation ([`RenderContext`]) of the book being passed to the |
83c7162d XL |
67 | //! subprocess via `stdin`. |
68 | //! | |
69 | //! The [`RenderContext`] gives the backend access to the contents of | |
2c00a5a8 XL |
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. | |
83c7162d XL |
73 | //! |
74 | //! To make creating a backend easier, the `mdbook` crate can be imported | |
75 | //! directly, making deserializing the `RenderContext` easy and giving you | |
2c00a5a8 XL |
76 | //! access to the various methods for working with the [`Config`]. |
77 | //! | |
78 | //! [user guide]: https://rust-lang-nursery.github.io/mdBook/ | |
79 | //! [`RenderContext`]: renderer/struct.RenderContext.html | |
80 | //! [relevant chapter]: https://rust-lang-nursery.github.io/mdBook/for_developers/backends.html | |
81 | //! [`Config`]: config/struct.Config.html | |
82 | ||
83 | #![deny(missing_docs)] | |
dc9dc135 | 84 | #![deny(rust_2018_idioms)] |
cc61c64b | 85 | |
cc61c64b | 86 | #[macro_use] |
ea8adc8c | 87 | extern crate error_chain; |
ea8adc8c XL |
88 | #[macro_use] |
89 | extern crate lazy_static; | |
90 | #[macro_use] | |
91 | extern crate log; | |
041b39d2 | 92 | #[macro_use] |
ea8adc8c | 93 | extern crate serde_derive; |
ea8adc8c XL |
94 | #[macro_use] |
95 | extern crate serde_json; | |
2c00a5a8 XL |
96 | |
97 | #[cfg(test)] | |
98 | #[macro_use] | |
99 | extern crate pretty_assertions; | |
ea8adc8c | 100 | |
ea8adc8c XL |
101 | pub mod book; |
102 | pub mod config; | |
9fa01778 | 103 | pub mod preprocess; |
cc61c64b XL |
104 | pub mod renderer; |
105 | pub mod theme; | |
106 | pub mod utils; | |
107 | ||
9fa01778 XL |
108 | /// The current version of `mdbook`. |
109 | /// | |
110 | /// This is provided as a way for custom preprocessors and renderers to do | |
111 | /// compatibility checks. | |
112 | pub const MDBOOK_VERSION: &str = env!("CARGO_PKG_VERSION"); | |
113 | ||
dc9dc135 XL |
114 | pub use crate::book::BookItem; |
115 | pub use crate::book::MDBook; | |
116 | pub use crate::config::Config; | |
117 | pub use crate::renderer::Renderer; | |
ea8adc8c XL |
118 | |
119 | /// The error types used through out this crate. | |
120 | pub mod errors { | |
2c00a5a8 XL |
121 | use std::path::PathBuf; |
122 | ||
dc9dc135 | 123 | error_chain! { |
ea8adc8c | 124 | foreign_links { |
dc9dc135 XL |
125 | Io(std::io::Error) #[doc = "A wrapper around `std::io::Error`"]; |
126 | HandlebarsRender(handlebars::RenderError) #[doc = "Handlebars rendering failed"]; | |
127 | HandlebarsTemplate(Box<handlebars::TemplateError>) #[doc = "Unable to parse the template"]; | |
128 | Utf8(std::string::FromUtf8Error) #[doc = "Invalid UTF-8"]; | |
129 | SerdeJson(serde_json::Error) #[doc = "JSON conversion failed"]; | |
ea8adc8c XL |
130 | } |
131 | ||
132 | errors { | |
2c00a5a8 | 133 | /// A subprocess exited with an unsuccessful return code. |
dc9dc135 | 134 | Subprocess(message: String, output: std::process::Output) { |
ea8adc8c XL |
135 | description("A subprocess failed") |
136 | display("{}: {}", message, String::from_utf8_lossy(&output.stdout)) | |
137 | } | |
2c00a5a8 XL |
138 | |
139 | /// An error was encountered while parsing the `SUMMARY.md` file. | |
140 | ParseError(line: usize, col: usize, message: String) { | |
141 | description("A SUMMARY.md parsing error") | |
142 | display("Error at line {}, column {}: {}", line, col, message) | |
143 | } | |
144 | ||
145 | /// The user tried to use a reserved filename. | |
146 | ReservedFilenameError(filename: PathBuf) { | |
147 | description("Reserved Filename") | |
148 | display("{} is reserved for internal use", filename.display()) | |
149 | } | |
dc9dc135 XL |
150 | |
151 | /// Error with a TOML file. | |
152 | TomlQueryError(inner: toml_query::error::Error) { | |
153 | description("toml_query error") | |
154 | display("{}", inner) | |
155 | } | |
2c00a5a8 XL |
156 | } |
157 | } | |
158 | ||
159 | // Box to halve the size of Error | |
dc9dc135 XL |
160 | impl From<handlebars::TemplateError> for Error { |
161 | fn from(e: handlebars::TemplateError) -> Error { | |
2c00a5a8 | 162 | From::from(Box::new(e)) |
ea8adc8c XL |
163 | } |
164 | } | |
165 | } |