From ced74ca4dd87ff7e0d9618b757e3536a6a472910 Mon Sep 17 00:00:00 2001 From: Ramon Buckland Date: Mon, 10 Sep 2018 20:58:55 +1000 Subject: [PATCH] Updated the documentation for new preprocessor format (#787) * Updated the documentation for new preprocessor format * adjusted the descriptions for preprocessors --- .../src/for_developers/preprocessors.md | 24 ++++++-- book-example/src/format/config.md | 58 ++++++++++++++++--- 2 files changed, 68 insertions(+), 14 deletions(-) diff --git a/book-example/src/for_developers/preprocessors.md b/book-example/src/for_developers/preprocessors.md index 16bd8e88..03c915bb 100644 --- a/book-example/src/for_developers/preprocessors.md +++ b/book-example/src/for_developers/preprocessors.md @@ -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; + 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 { +fn remove_emphasis( + num_removed_items: &mut usize, + chapter: &mut Chapter, +) -> Result { 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 diff --git a/book-example/src/format/config.md b/book-example/src/format/config.md index 312e4ebb..3f0fa278 100644 --- a/book-example/src/format/config.md +++ b/book-example/src/format/config.md @@ -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. \ No newline at end of file