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 ```rust
pub trait Preprocessor { pub trait Preprocessor {
fn name(&self) -> &str; 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 struct PreprocessorContext {
pub root: PathBuf, pub root: PathBuf,
pub config: Config, 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 ## A complete Example
The magic happens within the `run(...)` method of the 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. so safely.
```rust ```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 mut buf = String::with_capacity(chapter.content.len());
let events = Parser::new(&chapter.content).filter(|e| { let events = Parser::new(&chapter.content).filter(|e| {
let should_keep = match *e { let should_keep = match *e {
Event::Start(Tag::Emphasis) Event::Start(Tag::Emphasis)
@ -83,15 +94,16 @@ fn remove_emphasis(num_removed_items: &mut i32, chapter: &mut Chapter) -> Result
} }
should_keep should_keep
}); });
cmark(events, &mut buf, None)
.map(|_| buf) cmark(events, &mut buf, None).map(|_| buf).map_err(|err| {
.map_err(|err| Error::from(format!("Markdown serialization failed: {}", err))) Error::from(format!("Markdown serialization failed: {}", err))
})
} }
``` ```
For everything else, have a look [at the complete example][example]. 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 [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
[example]: https://github.com/rust-lang-nursery/mdBook/blob/master/examples/de-emphasize.rs [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" build-dir = "my-example-book"
create-missing = false create-missing = false
[preprocess.index]
[preprocess.links]
[output.html] [output.html]
additional-css = ["custom.css"] 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 will always be taken relative from the root of the book where the
configuration file is located. configuration file is located.
### General metadata ### General metadata
This is general information about your book. 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 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 is `false` then the build process will instead exit with an error if any files
do not exist. do not exist.
- **preprocess:** Specify which preprocessors to be applied. Default is - **use-default-preprocessors:** Disable the default preprocessors of (`links` &
`["links", "index"]`. To disable default preprocessors, pass an empty array `index`) by setting this option to `false`.
`[]` in.
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: The following preprocessors are available and included by default:
- `links`: Expand the `{{ #playpen }}` and `{{ #include }}` handlebars helpers in - `links`: Expand the `{{ #playpen }}` and `{{ #include }}` handlebars helpers in
a chapter. a chapter to include the contents of a file.
- `index`: Convert all chapter files named `README.md` into `index.md`. That is - `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 to say, all `README.md` would be rendered to an index file `index.html` in the
rendered book. rendered book.
@ -78,10 +91,39 @@ The following preprocessors are available and included by default:
[build] [build]
build-dir = "build" build-dir = "build"
create-missing = false 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 ### HTML renderer options
The HTML renderer has a couple of options as well. All the options for the 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]`. renderer need to be specified under the TOML table `[output.html]`.