diff --git a/guide/src/for_developers/README.md b/guide/src/for_developers/README.md index d8b97709..ea9ed116 100644 --- a/guide/src/for_developers/README.md +++ b/guide/src/for_developers/README.md @@ -1,7 +1,7 @@ # For Developers While `mdbook` is mainly used as a command line tool, you can also import the -underlying library directly and use that to manage a book. It also has a fairly +underlying libraries directly and use those to manage a book. It also has a fairly flexible plugin mechanism, allowing you to create your own custom tooling and consumers (often referred to as *backends*) if you need to do some analysis of the book or render it in a different format. @@ -14,7 +14,6 @@ The two main ways a developer can hook into the book's build process is via, - [Preprocessors](preprocessors.md) - [Alternative Backends](backends.md) - ## The Build Process The process of rendering a book project goes through several steps. @@ -28,20 +27,18 @@ The process of rendering a book project goes through several steps. 1. Run all the preprocessors. 2. Call the backend to render the processed result. - ## Using `mdbook` as a Library -The `mdbook` binary is just a wrapper around the `mdbook` crate, exposing its -functionality as a command-line program. As such it is quite easy to create your -own programs which use `mdbook` internally, adding your own functionality (e.g. -a custom preprocessor) or tweaking the build process. +The `mdbook` binary is just a wrapper around the underlying mdBook crates, +exposing their functionality as a command-line program. If you want to +programmatically drive mdBook, you can use the [`mdbook-driver`] crate. +This can be used to add your own functionality or tweak the build process. -The easiest way to find out how to use the `mdbook` crate is by looking at the +The easiest way to find out how to use the `mdbook-driver` crate is by looking at the [API Docs]. The top level documentation explains how one would use the [`MDBook`] type to load and build a book, while the [config] module gives a good explanation on the configuration system. - -[`MDBook`]: https://docs.rs/mdbook/*/mdbook/book/struct.MDBook.html -[API Docs]: https://docs.rs/mdbook/*/mdbook/ -[config]: https://docs.rs/mdbook/*/mdbook/config/index.html +[`MDBook`]: https://docs.rs/mdbook-driver/latest/mdbook_driver/struct.MDBook.html +[API Docs]: https://docs.rs/mdbook-driver/latest/mdbook_driver/ +[config]: https://docs.rs/mdbook-driver/latest/mdbook_driver/config/index.html diff --git a/guide/src/for_developers/backends.md b/guide/src/for_developers/backends.md index 72f8263e..c49381d9 100644 --- a/guide/src/for_developers/backends.md +++ b/guide/src/for_developers/backends.md @@ -16,13 +16,13 @@ This page will step you through creating your own alternative backend in the for of a simple word counting program. Although it will be written in Rust, there's no reason why it couldn't be accomplished using something like Python or Ruby. -First you'll want to create a new binary program and add `mdbook` as a +First you'll want to create a new binary program and add `mdbook-renderer` as a dependency. ```shell $ cargo new --bin mdbook-wordcount $ cd mdbook-wordcount -$ cargo add mdbook +$ cargo add mdbook-renderer ``` When our `mdbook-wordcount` plugin is invoked, `mdbook` will send it a JSON @@ -33,10 +33,8 @@ This is all the boilerplate necessary for our backend to load the book. ```rust // src/main.rs -extern crate mdbook; - use std::io; -use mdbook::renderer::RenderContext; +use mdbook_renderer::RenderContext; fn main() { let mut stdin = io::stdin(); @@ -45,13 +43,12 @@ fn main() { ``` > **Note:** The `RenderContext` contains a `version` field. This lets backends - figure out whether they are compatible with the version of `mdbook` it's being - called by. This `version` comes directly from the corresponding field in - `mdbook`'s `Cargo.toml`. - - It is recommended that backends use the [`semver`] crate to inspect this field - and emit a warning if there may be a compatibility issue. - +> figure out whether they are compatible with the version of `mdbook` it's being +> called by. This `version` comes directly from the corresponding field in +> `mdbook`'s `Cargo.toml`. +> +> It is recommended that backends use the [`semver`] crate to inspect this field +> and emit a warning if there may be a compatibility issue. ## Inspecting the Book @@ -183,9 +180,7 @@ $ cargo add serde serde_derive And then you can create the config struct, ```rust -extern crate serde; -#[macro_use] -extern crate serde_derive; +use serde_derive::{Serialize, Deserialize}; ... @@ -337,10 +332,10 @@ the source code or ask questions. [Third Party Plugins]: https://github.com/rust-lang/mdBook/wiki/Third-party-plugins -[`RenderContext`]: https://docs.rs/mdbook/*/mdbook/renderer/struct.RenderContext.html -[`RenderContext::from_json()`]: https://docs.rs/mdbook/*/mdbook/renderer/struct.RenderContext.html#method.from_json +[`RenderContext`]: https://docs.rs/mdbook-renderer/latest/mdbook_renderer/struct.RenderContext.html +[`RenderContext::from_json()`]: https://docs.rs/mdbook-renderer/latest/mdbook_renderer/struct.RenderContext.html#method.from_json [`semver`]: https://crates.io/crates/semver -[`Book`]: https://docs.rs/mdbook/*/mdbook/book/struct.Book.html -[`Book::iter()`]: https://docs.rs/mdbook/*/mdbook/book/struct.Book.html#method.iter -[`Config`]: https://docs.rs/mdbook/*/mdbook/config/struct.Config.html +[`Book`]: https://docs.rs/mdbook-renderer/latest/mdbook_renderer/book/struct.Book.html +[`Book::iter()`]: https://docs.rs/mdbook-renderer/latest/mdbook_renderer/book/struct.Book.html#method.iter +[`Config`]: https://docs.rs/mdbook-renderer/latest/mdbook_renderer/config/struct.Config.html [issue tracker]: https://github.com/rust-lang/mdBook/issues diff --git a/guide/src/for_developers/preprocessors.md b/guide/src/for_developers/preprocessors.md index 1455aceb..1abd39cc 100644 --- a/guide/src/for_developers/preprocessors.md +++ b/guide/src/for_developers/preprocessors.md @@ -45,7 +45,7 @@ be adapted for other preprocessors. ## Hints For Implementing A Preprocessor -By pulling in `mdbook` as a library, preprocessors can have access to the +By pulling in `mdbook-preprocessor` as a library, preprocessors can have access to the existing infrastructure for dealing with books. For example, a custom preprocessor could use the @@ -60,9 +60,7 @@ chapters) or via the `Book::for_each_mut()` convenience method. The `chapter.content` is just a string which happens to be markdown. While it's entirely possible to use regular expressions or do a manual find & replace, you'll probably want to process the input into something more computer-friendly. -The [`pulldown-cmark`][pc] crate implements a production-quality event-based -Markdown parser, with the [`pulldown-cmark-to-cmark`][pctc] crate allowing you to -translate events back into markdown text. +The [`mdbook-markdown`] crate exposes the [`pulldown-cmark`][pc] crate used by mdBook to parse Markdown. The [`pulldown-cmark-to-cmark`][pctc] crate can be used to translate events back into markdown text. The following code block shows how to remove all emphasis from markdown, without accidentally breaking the document. @@ -100,11 +98,11 @@ if __name__ == '__main__': [emphasis-example]: https://github.com/rust-lang/mdBook/tree/master/examples/remove-emphasis/ -[preprocessor-docs]: https://docs.rs/mdbook/latest/mdbook/preprocess/trait.Preprocessor.html [pc]: https://crates.io/crates/pulldown-cmark [pctc]: https://crates.io/crates/pulldown-cmark-to-cmark [an example no-op preprocessor]: https://github.com/rust-lang/mdBook/blob/master/examples/nop-preprocessor.rs -[`CmdPreprocessor::parse_input()`]: https://docs.rs/mdbook/latest/mdbook/preprocess/trait.Preprocessor.html#method.parse_input -[`Book::for_each_mut()`]: https://docs.rs/mdbook/latest/mdbook/book/struct.Book.html#method.for_each_mut -[`PreprocessorContext`]: https://docs.rs/mdbook/latest/mdbook/preprocess/struct.PreprocessorContext.html -[`Book`]: https://docs.rs/mdbook/latest/mdbook/book/struct.Book.html +[`CmdPreprocessor::parse_input()`]: https://docs.rs/mdbook-preprocessor/latest/mdbook_preprocessor/trait.Preprocessor.html#method.parse_input +[`Book::for_each_mut()`]: https://docs.rs/mdbook-preprocessor/latest/mdbook_preprocessor/book/struct.Book.html#method.for_each_mut +[`PreprocessorContext`]: https://docs.rs/mdbook-preprocessor/latest/mdbook_preprocessor/struct.PreprocessorContext.html +[`Book`]: https://docs.rs/mdbook-preprocessor/latest/mdbook_preprocessor/book/struct.Book.html +[`mdbook-markdown`]: https://docs.rs/mdbook-markdown/latest/mdbook_markdown/