From 6f7e489a7e4dd4f7ce0ad79971586414a86cd3f5 Mon Sep 17 00:00:00 2001 From: Ramon Buckland Date: Sun, 9 Sep 2018 11:18:46 +1000 Subject: [PATCH 1/2] Updated the documentation for new preprocessor format --- .../src/for_developers/preprocessors.md | 24 ++++++++--- book-example/src/format/config.md | 40 +++++++++++++++---- 2 files changed, 51 insertions(+), 13 deletions(-) diff --git a/book-example/src/for_developers/preprocessors.md b/book-example/src/for_developers/preprocessors.md index 16bd8e8800..abd1b0f163 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/0.2.2/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 312e4ebbf2..8a17765c64 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 = true +linkes = true + [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,10 +62,8 @@ 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. +### Configuring Preprocessors The following preprocessors are available and included by default: @@ -71,14 +72,39 @@ The following preprocessors are available and included by default: - `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. - +- `emoji`: Convert `:emoji:` text into Emojis. eg: `:smile:` to :smile: **book.toml** ```toml [build] build-dir = "build" create-missing = false -preprocess = ["links", "index"] + +[preprocess] +links = true +index = true +emoji = 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 +``` + +#### Nested Configuration + +Where a preprocessor has more complex configuration available to it, use the +following style of configuration. + +``` +[preprocess.links] +# set the renderers this preprocessor will run for +renderers = ["html"] +some_extra_feature = true ``` ### HTML renderer options @@ -214,4 +240,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 From 582c44491a1faaa57fcad51c64f3ebc5c336090c Mon Sep 17 00:00:00 2001 From: Ramon Buckland Date: Sun, 9 Sep 2018 21:38:21 +1000 Subject: [PATCH 2/2] adjusted the descriptions for preprocessors --- .../src/for_developers/preprocessors.md | 2 +- book-example/src/format/config.md | 60 ++++++++++++------- 2 files changed, 39 insertions(+), 23 deletions(-) diff --git a/book-example/src/for_developers/preprocessors.md b/book-example/src/for_developers/preprocessors.md index abd1b0f163..03c915bbc1 100644 --- a/book-example/src/for_developers/preprocessors.md +++ b/book-example/src/for_developers/preprocessors.md @@ -103,7 +103,7 @@ fn remove_emphasis( For everything else, have a look [at the complete example][example]. -[preprocessor-docs]: https://docs.rs/mdbook/0.2.2/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 8a17765c64..3f0fa2786f 100644 --- a/book-example/src/format/config.md +++ b/book-example/src/format/config.md @@ -14,9 +14,9 @@ description = "The example book covers examples." build-dir = "my-example-book" create-missing = false -[preprocess] -index = true -linkes = true +[preprocess.index] + +[preprocess.links] [output.html] additional-css = ["custom.css"] @@ -62,17 +62,29 @@ 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. +- **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 +## 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. -- `emoji`: Convert `:emoji:` text into Emojis. eg: `:smile:` to :smile: + **book.toml** ```toml @@ -80,25 +92,17 @@ The following preprocessors are available and included by default: build-dir = "build" create-missing = false -[preprocess] -links = true -index = true -emoji = 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. +[preprocess.links] +[preprocess.index] ``` -[preprocessor.mathjax] -renderers = ["html"] # mathjax only makes sense with the HTML renderer -``` -#### Nested Configuration +### 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. -Where a preprocessor has more complex configuration available to it, use the -following style of configuration. +For example ``` [preprocess.links] @@ -107,7 +111,19 @@ 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]`.