Updated the documentation for new preprocessor format #787
Conversation
book-example/src/format/config.md
Outdated
| @@ -14,6 +14,10 @@ description = "The example book covers examples." | |||
| build-dir = "my-example-book" | |||
| create-missing = false | |||
|
|
|||
| [preprocess] | |||
| index = true | |||
There was a problem hiding this comment.
I don't think this is correct. Each preprocessor gets its own table and you can enable/disable inserting the default preprocessors by setting build.use-default-preprocessors to true.
| @@ -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 | |||
There was a problem hiding this comment.
We'll need to mention the use-default-preprocessors flag here. It's used to enable/disable including the default preprocessors and defaults to true.
I've also added a couple tests in 18a36ec to make sure the build.use-default-preprocessors flag works as intended.
book-example/src/format/config.md
Outdated
| @@ -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: | |||
There was a problem hiding this comment.
Ooh, there's an emoji preprocessors? That's really cool!
book-example/src/format/config.md
Outdated
| renderers = ["html"] # mathjax only makes sense with the HTML renderer | ||
| ``` | ||
|
|
||
| #### Nested Configuration |
There was a problem hiding this comment.
This section will probably need to mention that, like renderers, each preprocessor will always need to be given its own table (e.g. [preprocessor.mathjax]). From there, passing extra configuration to the preprocessor is just a case of adding key-value pairs to the table, so there isn't really a separate "style of configuration".
book-example/src/format/config.md
Outdated
|
|
||
| **book.toml** | ||
| ```toml | ||
| [build] | ||
| build-dir = "build" | ||
| create-missing = false | ||
| preprocess = ["links", "index"] | ||
|
|
||
| [preprocess] |
There was a problem hiding this comment.
This will need to be changed to something like:
[preprocess.links]
[preprocess.index]
[preprocess.emoji]Although those three preprocessors will be enabled by default, so it's kinda redundant to even mention them...
|
@rbuckland about the https://docs.rs/mdbook/latest/mdbook/preprocess/trait.Preprocessor.html |
|
@Michael-F-Bryan wrote:
oops - I didn't mean to include the text yet. Sorry. I will PR that once this change comes through. That is for issue #771 |
|
I have updated that documentation - please take a read - and make sure I got it right :-D |
|
LGTM 👍 |
* Updated the documentation for new preprocessor format * adjusted the descriptions for preprocessors
* Updated the documentation for new preprocessor format * adjusted the descriptions for preprocessors
* Updated the documentation for new preprocessor format * adjusted the descriptions for preprocessors
@Michael-F-Bryan This is the documentation you require for the preprocessor change.
The link -
[preprocessor-docs]is forward looking