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:
parent
18a36ec1fa
commit
a00ccf8c72
|
@ -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
|
||||||
|
|
|
@ -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]`.
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue