Merge pull request #807 from rust-lang-nursery/update-readme

Update the readme to mention plugins

README.md

@@ -145,6 +145,57 @@ 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
+
+> **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.
+
+```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 +240,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

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