Expand description
The object used to manage and build a book.
Fields§
§root: PathBuf
The book’s root directory.
config: Config
The configuration used to tweak now a book is built.
book: Book
A representation of the book’s contents in memory.
Implementations§
source§impl MDBook
impl MDBook
sourcepub fn load<P: Into<PathBuf>>(book_root: P) -> Result<MDBook>
pub fn load<P: Into<PathBuf>>(book_root: P) -> Result<MDBook>
Load a book from its root directory on disk.
Examples found in repository?
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96
pub fn build(&self) -> Result<MDBook> {
info!("Creating a new book with stub content");
self.create_directory_structure()
.with_context(|| "Unable to create directory structure")?;
self.create_stub_files()
.with_context(|| "Unable to create stub files")?;
if self.create_gitignore {
self.build_gitignore()
.with_context(|| "Unable to create .gitignore")?;
}
if self.copy_theme {
self.copy_across_theme()
.with_context(|| "Unable to copy across the theme")?;
}
self.write_book_toml()?;
match MDBook::load(&self.root) {
Ok(book) => Ok(book),
Err(e) => {
error!("{}", e);
panic!(
"The BookBuilder should always create a valid book. If you are seeing this it \
is a bug and should be reported."
);
}
}
}
sourcepub fn load_with_config<P: Into<PathBuf>>(
book_root: P,
config: Config
) -> Result<MDBook>
pub fn load_with_config<P: Into<PathBuf>>(
book_root: P,
config: Config
) -> Result<MDBook>
Load a book from its root directory using a custom Config
.
Examples found in repository?
51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95
pub fn load<P: Into<PathBuf>>(book_root: P) -> Result<MDBook> {
let book_root = book_root.into();
let config_location = book_root.join("book.toml");
// the book.json file is no longer used, so we should emit a warning to
// let people know to migrate to book.toml
if book_root.join("book.json").exists() {
warn!("It appears you are still using book.json for configuration.");
warn!("This format is no longer used, so you should migrate to the");
warn!("book.toml format.");
warn!("Check the user guide for migration information:");
warn!("\thttps://rust-lang.github.io/mdBook/format/config.html");
}
let mut config = if config_location.exists() {
debug!("Loading config from {}", config_location.display());
Config::from_disk(&config_location)?
} else {
Config::default()
};
config.update_from_env();
if config
.html_config()
.map_or(false, |html| html.google_analytics.is_some())
{
warn!(
"The output.html.google-analytics field has been deprecated; \
it will be removed in a future release.\n\
Consider placing the appropriate site tag code into the \
theme/head.hbs file instead.\n\
The tracking code may be found in the Google Analytics Admin page.\n\
"
);
}
if log_enabled!(log::Level::Trace) {
for line in format!("Config: {:#?}", config).lines() {
trace!("{}", line);
}
}
MDBook::load_with_config(book_root, config)
}
sourcepub fn load_with_config_and_summary<P: Into<PathBuf>>(
book_root: P,
config: Config,
summary: Summary
) -> Result<MDBook>
pub fn load_with_config_and_summary<P: Into<PathBuf>>(
book_root: P,
config: Config,
summary: Summary
) -> Result<MDBook>
Load a book from its root directory using a custom Config
and a custom summary.
sourcepub fn iter(&self) -> BookItems<'_> ⓘ
pub fn iter(&self) -> BookItems<'_> ⓘ
Returns a flat depth-first iterator over the elements of the book,
it returns a BookItem
enum:
(section: String, bookitem: &BookItem)
for item in book.iter() {
match *item {
BookItem::Chapter(ref chapter) => {},
BookItem::Separator => {},
BookItem::PartTitle(ref title) => {}
}
}
// would print something like this:
// 1. Chapter 1
// 1.1 Sub Chapter
// 1.2 Sub Chapter
// 2. Chapter 2
//
// etc.
sourcepub fn init<P: Into<PathBuf>>(book_root: P) -> BookBuilder
pub fn init<P: Into<PathBuf>>(book_root: P) -> BookBuilder
init()
gives you a BookBuilder
which you can use to setup a new book
and its accompanying directory structure.
The BookBuilder
creates some boilerplate files and directories to get
you started with your book.
book-test/
├── book
└── src
├── chapter_1.md
└── SUMMARY.md
It uses the path provided as the root directory for your book, then adds
in a src/
directory containing a SUMMARY.md
and chapter_1.md
file
to get you started.
sourcepub fn build(&self) -> Result<()>
pub fn build(&self) -> Result<()>
Tells the renderer to build our book and put it in the build directory.
sourcepub fn execute_build_process(&self, renderer: &dyn Renderer) -> Result<()>
pub fn execute_build_process(&self, renderer: &dyn Renderer) -> Result<()>
Run the entire build process for a particular Renderer
.
sourcepub fn with_renderer<R: Renderer + 'static>(&mut self, renderer: R) -> &mut Self
pub fn with_renderer<R: Renderer + 'static>(&mut self, renderer: R) -> &mut Self
You can change the default renderer to another one by using this method.
The only requirement is that your renderer implement the Renderer
trait.
sourcepub fn with_preprocessor<P: Preprocessor + 'static>(
&mut self,
preprocessor: P
) -> &mut Self
pub fn with_preprocessor<P: Preprocessor + 'static>(
&mut self,
preprocessor: P
) -> &mut Self
Register a Preprocessor
to be used when rendering the book.
sourcepub fn test(&mut self, library_paths: Vec<&str>) -> Result<()>
pub fn test(&mut self, library_paths: Vec<&str>) -> Result<()>
Run rustdoc
tests on the book, linking against the provided libraries.
sourcepub fn test_chapter(
&mut self,
library_paths: Vec<&str>,
chapter: Option<&str>
) -> Result<()>
pub fn test_chapter(
&mut self,
library_paths: Vec<&str>,
chapter: Option<&str>
) -> Result<()>
Run rustdoc
tests on a specific chapter of the book, linking against the provided libraries.
If chapter
is None
, all tests will be run.
sourcepub fn build_dir_for(&self, backend_name: &str) -> PathBuf
pub fn build_dir_for(&self, backend_name: &str) -> PathBuf
The logic for determining where a backend should put its build artefacts.
If there is only 1 renderer, put it in the directory pointed to by the
build.build_dir
key in Config
. If there is more than one then the
renderer gets its own directory within the main build dir.
i.e. If there were only one renderer (in this case, the HTML renderer):
- build/
- index.html
- …
Otherwise if there are multiple:
- build/
- epub/
- my_awesome_book.epub
- html/
- index.html
- …
- latex/
- my_awesome_book.tex
- epub/
Examples found in repository?
200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232
pub fn execute_build_process(&self, renderer: &dyn Renderer) -> Result<()> {
let mut preprocessed_book = self.book.clone();
let preprocess_ctx = PreprocessorContext::new(
self.root.clone(),
self.config.clone(),
renderer.name().to_string(),
);
for preprocessor in &self.preprocessors {
if preprocessor_should_run(&**preprocessor, renderer, &self.config) {
debug!("Running the {} preprocessor.", preprocessor.name());
preprocessed_book = preprocessor.run(&preprocess_ctx, preprocessed_book)?;
}
}
let name = renderer.name();
let build_dir = self.build_dir_for(name);
let mut render_context = RenderContext::new(
self.root.clone(),
preprocessed_book,
self.config.clone(),
build_dir,
);
render_context
.chapter_titles
.extend(preprocess_ctx.chapter_titles.borrow_mut().drain());
info!("Running the {} backend", renderer.name());
renderer
.render(&render_context)
.with_context(|| "Rendering failed")
}
sourcepub fn source_dir(&self) -> PathBuf
pub fn source_dir(&self) -> PathBuf
Get the directory containing this book’s source files.