From e73928f933a1d13d57b275c38852d86a3691a352 Mon Sep 17 00:00:00 2001 From: Michael Bryan Date: Sat, 20 Oct 2018 14:01:51 +0800 Subject: [PATCH 1/2] Mentioned plugins in the README --- README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/README.md b/README.md index a945f7f2..5a24d0d5 100644 --- a/README.md +++ b/README.md @@ -145,6 +145,54 @@ explanation, check out the [User Guide]. Delete directory in which generated book is located. +### 3rd Party Plugins + +The way a book is loaded and rendered can be configured by the user via third +party plugins. These plugins are just programs which will be invoked during the +build process and are split into roughly two categories, *preprocessors* and +*renderers*. + +Preprocessors are used to transform a book before it is sent to a renderer. +One example would be to replace all occurrences of +`{{#include some_file.ext}}` with the contents of that file. Some existing +preprocessors are: + +- `index` - a built-in preprocessor (enabled by default) which will transform + all `README.md` chapters to `index.md` so `foo/README.md` can be accessed via + the url `foo/` when published to a browser +- `links` - a built-in preprocessor (enabled by default) for expanding the + `{{# playpen}}` and `{{# include}}` helpers in a chapter. + +Renderers are given the final book so they can do something with it. This is +typically used for, as the name suggests, rendering the document in a particular +format, however there's nothing stopping a renderer from doing static analysis +of a book in order to validate links or run tests. Some existing renderers are: + +- `html` - the built-in renderer which will generate a HTML version of the book +- [`linkcheck`] - a backend which will check that all links are valid +- [`epub`] - an experimental EPUB generator + +A preprocessor or renderer is enabled by installing the appropriate program and +then mentioning it in the book's `book.toml` file. + +```console +$ cargo install mdbook-linkcheck +$ edit book.toml && cat book.toml +[book] +title = "My Awesome Book" +authors = ["Michael-F-Bryan"] + +[output.html] + +[output.linkcheck] # enable the "mdbook-linkcheck" renderer + +$ mdbook build +2018-10-20 13:57:51 [INFO] (mdbook::book): Book building has started +2018-10-20 13:57:51 [INFO] (mdbook::book): Running the html backend +2018-10-20 13:57:53 [INFO] (mdbook::book): Running the linkcheck backend +``` + +For more information on the plugin system, consult the [User Guide]. ### As a library @@ -189,3 +237,5 @@ All the code in this repository is released under the ***Mozilla Public License [Rust]: https://www.rust-lang.org/ [CLI docs]: http://rust-lang-nursery.github.io/mdBook/cli/init.html [master-docs]: http://rust-lang-nursery.github.io/mdBook/mdbook/ +[`linkcheck`]: https://crates.io/crates/mdbook-linkcheck +[`epub`]: https://crates.io/crates/mdbook-epub \ No newline at end of file From cffc385b0cf6c00b285a8b65af16bfca5628fc49 Mon Sep 17 00:00:00 2001 From: Michael Bryan Date: Sat, 20 Oct 2018 14:16:07 +0800 Subject: [PATCH 2/2] Updated the user guide's config section to mention specifying plugin commands --- README.md | 3 +++ book-example/src/format/config.md | 37 ++++++++++++++++++++++++++----- 2 files changed, 34 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 5a24d0d5..0af7e5b6 100644 --- a/README.md +++ b/README.md @@ -172,6 +172,9 @@ of a book in order to validate links or run tests. Some existing renderers are: - [`linkcheck`] - a backend which will check that all links are valid - [`epub`] - an experimental EPUB generator +> **Note for Developers:** Feel free to send us a PR if you've developed your +> own plugin and want it mentioned here. + A preprocessor or renderer is enabled by installing the appropriate program and then mentioning it in the book's `book.toml` file. diff --git a/book-example/src/format/config.md b/book-example/src/format/config.md index 3f0fa278..f74e3bf1 100644 --- a/book-example/src/format/config.md +++ b/book-example/src/format/config.md @@ -79,8 +79,8 @@ This controls the build process of your book. The following preprocessors are available and included by default: -- `links`: Expand the `{{ #playpen }}` and `{{ #include }}` handlebars helpers in - a chapter to include the contents of a file. +- `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. @@ -99,8 +99,9 @@ create-missing = false ### 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. +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 @@ -113,13 +114,26 @@ 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. +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 ``` +### Provide Your Own Command + +By default when you add a `[preprocessor.foo]` table to your `book.toml` file, +`mdbook` will try to invoke the `mdbook-foo` executa`ble. If you want to use a +different program name or pass in command-line arguments, this behaviour can +be overridden by adding a `command` field. + +```toml +[preprocessor.random] +command = "python random.py" +``` + ## Configuring Renderers ### HTML renderer options @@ -181,7 +195,8 @@ Available configuration options for the `[output.html.search]` table: - **copy-js:** Copy JavaScript files for the search implementation to the output directory. Defaults to `true`. -This shows all available options in the **book.toml**: +This shows all available HTML output options in the **book.toml**: + ```toml [book] title = "Example book" @@ -218,6 +233,16 @@ heading-split-level = 3 copy-js = true ``` +### Custom Renderers + +A custom renderer can be enabled by adding a `[output.foo]` table to your +`book.toml`. Similar to [preprocessors](#configuring-preprocessors) this will +instruct `mdbook` to pass a representation of the book to `mdbook-foo` for +rendering. + +Custom renderers will have access to all configuration within their table +(i.e. anything under `[output.foo]`), and the command to be invoked can be +manually specified with the `command` field. ## Environment Variables