jesus/mdbook
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

Update guide to accommodate crate split

Browse source 
This updates the docs now that the crate has been split into multiple
crates.
This commit is contained in:
Eric Huss 2025-07-23 16:32:49 -07:00
parent dcfb527342
commit fad53f720f
3 changed files with 31 additions and 41 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

21
guide/src/for_developers/README.md
View file

@ -1,7 +1,7 @@
# For Developers # For Developers
While `mdbook` is mainly used as a command line tool, you can also import the 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 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 consumers (often referred to as *backends*) if you need to do some analysis of
the book or render it in a different format. 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) - [Preprocessors](preprocessors.md)
- [Alternative Backends](backends.md) - [Alternative Backends](backends.md)
## The Build Process ## The Build Process
The process of rendering a book project goes through several steps. 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. 1. Run all the preprocessors.
2. Call the backend to render the processed result. 2. Call the backend to render the processed result.
## Using `mdbook` as a Library ## Using `mdbook` as a Library
The `mdbook` binary is just a wrapper around the `mdbook` crate, exposing its The `mdbook` binary is just a wrapper around the underlying mdBook crates,
functionality as a command-line program. As such it is quite easy to create your exposing their functionality as a command-line program. If you want to
own programs which use `mdbook` internally, adding your own functionality (e.g. programmatically drive mdBook, you can use the [`mdbook-driver`] crate.
a custom preprocessor) or tweaking the build process. 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 [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 [`MDBook`] type to load and build a book, while the [config] module gives a good
explanation on the configuration system. explanation on the configuration system.
[`MDBook`]: https://docs.rs/mdbook-driver/latest/mdbook_driver/struct.MDBook.html
[`MDBook`]: https://docs.rs/mdbook/*/mdbook/book/struct.MDBook.html [API Docs]: https://docs.rs/mdbook-driver/latest/mdbook_driver/
[API Docs]: https://docs.rs/mdbook/*/mdbook/ [config]: https://docs.rs/mdbook-driver/latest/mdbook_driver/config/index.html
[config]: https://docs.rs/mdbook/*/mdbook/config/index.html

35
guide/src/for_developers/backends.md
View file

@ -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 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. 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. dependency.
```shell ```shell
$ cargo new --bin mdbook-wordcount $ cargo new --bin mdbook-wordcount
$ cd 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 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 ```rust
// src/main.rs // src/main.rs
extern crate mdbook;
use std::io; use std::io;
use mdbook::renderer::RenderContext; use mdbook_renderer::RenderContext;
fn main() { fn main() {
let mut stdin = io::stdin(); let mut stdin = io::stdin();
@ -45,13 +43,12 @@ fn main() {
``` ```
> **Note:** The `RenderContext` contains a `version` field. This lets backends > **Note:** The `RenderContext` contains a `version` field. This lets backends
figure out whether they are compatible with the version of `mdbook` it's being > 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 > called by. This `version` comes directly from the corresponding field in
`mdbook`'s `Cargo.toml`. > `mdbook`'s `Cargo.toml`.
>
It is recommended that backends use the [`semver`] crate to inspect this field > It is recommended that backends use the [`semver`] crate to inspect this field
and emit a warning if there may be a compatibility issue. > and emit a warning if there may be a compatibility issue.
## Inspecting the Book ## Inspecting the Book
@ -183,9 +180,7 @@ $ cargo add serde serde_derive
And then you can create the config struct, And then you can create the config struct,
```rust ```rust
extern crate serde; use serde_derive::{Serialize, Deserialize};
#[macro_use]
extern crate serde_derive;
... ...
@ -337,10 +332,10 @@ the source code or ask questions.
[Third Party Plugins]: https://github.com/rust-lang/mdBook/wiki/Third-party-plugins [Third Party Plugins]: https://github.com/rust-lang/mdBook/wiki/Third-party-plugins
[`RenderContext`]: https://docs.rs/mdbook/*/mdbook/renderer/struct.RenderContext.html [`RenderContext`]: https://docs.rs/mdbook-renderer/latest/mdbook_renderer/struct.RenderContext.html
[`RenderContext::from_json()`]: https://docs.rs/mdbook/*/mdbook/renderer/struct.RenderContext.html#method.from_json [`RenderContext::from_json()`]: https://docs.rs/mdbook-renderer/latest/mdbook_renderer/struct.RenderContext.html#method.from_json
[`semver`]: https://crates.io/crates/semver [`semver`]: https://crates.io/crates/semver
[`Book`]: https://docs.rs/mdbook/*/mdbook/book/struct.Book.html [`Book`]: https://docs.rs/mdbook-renderer/latest/mdbook_renderer/book/struct.Book.html
[`Book::iter()`]: https://docs.rs/mdbook/*/mdbook/book/struct.Book.html#method.iter [`Book::iter()`]: https://docs.rs/mdbook-renderer/latest/mdbook_renderer/book/struct.Book.html#method.iter
[`Config`]: https://docs.rs/mdbook/*/mdbook/config/struct.Config.html [`Config`]: https://docs.rs/mdbook-renderer/latest/mdbook_renderer/config/struct.Config.html
[issue tracker]: https://github.com/rust-lang/mdBook/issues [issue tracker]: https://github.com/rust-lang/mdBook/issues

16
guide/src/for_developers/preprocessors.md
View file

@ -45,7 +45,7 @@ be adapted for other preprocessors.
## Hints For Implementing A Preprocessor ## 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. existing infrastructure for dealing with books.
For example, a custom preprocessor could use the 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 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, 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. you'll probably want to process the input into something more computer-friendly.
The [`pulldown-cmark`][pc] crate implements a production-quality event-based 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.
Markdown parser, with the [`pulldown-cmark-to-cmark`][pctc] crate allowing you to
translate events back into markdown text.
The following code block shows how to remove all emphasis from markdown, The following code block shows how to remove all emphasis from markdown,
without accidentally breaking the document. 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/ [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 [pc]: https://crates.io/crates/pulldown-cmark
[pctc]: https://crates.io/crates/pulldown-cmark-to-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 [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 [`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/latest/mdbook/book/struct.Book.html#method.for_each_mut [`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/latest/mdbook/preprocess/struct.PreprocessorContext.html [`PreprocessorContext`]: https://docs.rs/mdbook-preprocessor/latest/mdbook_preprocessor/struct.PreprocessorContext.html
[`Book`]: https://docs.rs/mdbook/latest/mdbook/book/struct.Book.html [`Book`]: https://docs.rs/mdbook-preprocessor/latest/mdbook_preprocessor/book/struct.Book.html
[`mdbook-markdown`]: https://docs.rs/mdbook-markdown/latest/mdbook_markdown/