Updated the documentation for new preprocessor format (#787)

* Updated the documentation for new preprocessor format

* adjusted the descriptions for preprocessors
This commit is contained in:
Ramon Buckland 2018-09-10 20:58:55 +10:00 committed by Michael Bryan
parent 18a36ec1fa
commit a00ccf8c72
2 changed files with 68 additions and 14 deletions

View File

@ -18,7 +18,10 @@ A preprocessor is represented by the `Preprocessor` trait.
```rust
pub trait Preprocessor {
fn name(&self) -> &str;
fn run(&self, ctx: &PreprocessorContext, book: &mut Book) -> Result<()>;
fn run(&self, ctx: &PreprocessorContext, book: Book) -> Result<Book>;
fn supports_renderer(&self, _renderer: &str) -> bool {
true
}
}
```
@ -28,9 +31,13 @@ Where the `PreprocessorContext` is defined as
pub struct PreprocessorContext {
pub root: PathBuf,
pub config: Config,
/// The `Renderer` this preprocessor is being used with.
pub renderer: String,
}
```
The `renderer` value allows you react accordingly, for example, PDF or HTML.
## A complete Example
The magic happens within the `run(...)` method of the
@ -68,8 +75,12 @@ The following code block shows how to remove all emphasis from markdown, and do
so safely.
```rust
fn remove_emphasis(num_removed_items: &mut i32, chapter: &mut Chapter) -> Result<String> {
fn remove_emphasis(
num_removed_items: &mut usize,
chapter: &mut Chapter,
) -> Result<String> {
let mut buf = String::with_capacity(chapter.content.len());
let events = Parser::new(&chapter.content).filter(|e| {
let should_keep = match *e {
Event::Start(Tag::Emphasis)
@ -83,15 +94,16 @@ fn remove_emphasis(num_removed_items: &mut i32, chapter: &mut Chapter) -> Result
}
should_keep
});
cmark(events, &mut buf, None)
.map(|_| buf)
.map_err(|err| Error::from(format!("Markdown serialization failed: {}", err)))
cmark(events, &mut buf, None).map(|_| buf).map_err(|err| {
Error::from(format!("Markdown serialization failed: {}", err))
})
}
```
For everything else, have a look [at the complete example][example].
[preprocessor-docs]: https://docs.rs/mdbook/0.1.3/mdbook/preprocess/trait.Preprocessor.html
[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
[example]: https://github.com/rust-lang-nursery/mdBook/blob/master/examples/de-emphasize.rs

View File

@ -14,6 +14,10 @@ description = "The example book covers examples."
build-dir = "my-example-book"
create-missing = false
[preprocess.index]
[preprocess.links]
[output.html]
additional-css = ["custom.css"]
@ -27,7 +31,6 @@ It is important to note that **any** relative path specified in the in the
configuration will always be taken relative from the root of the book where the
configuration file is located.
### General metadata
This is general information about your book.
@ -59,15 +62,25 @@ This controls the build process of your book.
will be created when the book is built (i.e. `create-missing = true`). If this
is `false` then the build process will instead exit with an error if any files
do not exist.
- **preprocess:** Specify which preprocessors to be applied. Default is
`["links", "index"]`. To disable default preprocessors, pass an empty array
`[]` in.
- **use-default-preprocessors:** Disable the default preprocessors of (`links` &
`index`) by setting this option to `false`.
If you have the same, and/or other preprocessors declared via their table
of configuration, they will run instead.
- For clarity, with no preprocessor configuration, the default `links` and
`index` will run.
- Setting `use-default-preprocessors = false` will disable these
default preprocessors from running.
- Adding `[preprocessor.links]`, for example, will ensure, regardless of
`use-default-preprocessors` that `links` it will run.
## Configuring Preprocessors
The following preprocessors are available and included by default:
- `links`: Expand the `{{# playpen}}` and `{{# include}}` handlebars helpers in
a chapter.
- `links`: Expand the `{{ #playpen }}` and `{{ #include }}` handlebars helpers in
a chapter to include the contents of a file.
- `index`: Convert all chapter files named `README.md` into `index.md`. That is
to say, all `README.md` would be rendered to an index file `index.html` in the
rendered book.
@ -78,10 +91,39 @@ The following preprocessors are available and included by default:
[build]
build-dir = "build"
create-missing = false
preprocess = ["links", "index"]
[preprocess.links]
[preprocess.index]
```
### Custom Preprocessor Configuration
Like renderers, preprocessor will need to be given its own table (e.g. `[preprocessor.mathjax]`).
In the section, you may then pass extra configuration to the preprocessor by adding key-value pairs to the table.
For example
```
[preprocess.links]
# set the renderers this preprocessor will run for
renderers = ["html"]
some_extra_feature = true
```
#### Locking a Preprocessor dependency to a renderer
You can explicitly specify that a preprocessor should run for a renderer by binding the two together.
```
[preprocessor.mathjax]
renderers = ["html"] # mathjax only makes sense with the HTML renderer
```
## Configuring Renderers
### HTML renderer options
The HTML renderer has a couple of options as well. All the options for the
renderer need to be specified under the TOML table `[output.html]`.
@ -214,4 +256,4 @@ book's title without needing to touch your `book.toml`.
The latter case may be useful in situations where `mdbook` is invoked from a
script or CI, where it sometimes isn't possible to update the `book.toml` before
building.
building.