mirrors/mdBook
1
0
Fork 0
mirror of https://github.com/rust-lang/mdBook.git synced 2025-12-27 09:05:40 -05:00
Code Issues Packages Projects Releases Wiki Activity

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
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
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

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
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

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

@@ -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/