book: add configuration docs

6 files changed, 130 insertions, 28 deletions

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index fd3fccd..6943871 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -30,6 +30,8 @@ jobs:
           override: true
       - name: Install mdbook
         run: ./scripts/install-mdbook
+      - name: Install mdbook extras
+        run: ./book/scripts/install-mdbook-extras
       - name: Build book
         run: ./scripts/build-book
       - name: Push docs
diff --git a/README.md b/README.md
index f1d6725..da869cb 100644
--- a/README.md
+++ b/README.md
@@ -123,19 +123,6 @@ Alternatively, pin to a specific version for a reproducible installation:
 cargo install mdbook-admonish --vers "1.5.0" --locked
 ```
 
-### Bail on error
-
-By default, if an adomnition is incorrectly configured, an error will be shown in the book.
-
-You can force it to break the build instead, with the following configuration:
-
-```toml
-[preprocessor.admonish]
-on_failure = "bail"
-```
-
-This may be useful for non-interative workflows.
-
 ### Process included files
 
 You can ensure that content inlined with `{{#include}}` is also processed by [setting the `after` option](https://rust-lang.github.io/mdBook/format/configuration/preprocessors.html#require-a-certain-order):
diff --git a/book/book.toml b/book/book.toml
index 4770288..0fef99f 100644
--- a/book/book.toml
+++ b/book/book.toml
@@ -11,6 +11,10 @@ title = "The mdbook-admonish book"
 command = "mdbook-admonish"
 assets_version = "2.0.0" # do not edit: managed by `mdbook-admonish install`
 
+[preprocessor.toc]
+command = "mdbook-toc"
+renderer = ["html"]
+
 [output]
 
 [output.html]
diff --git a/book/scripts/install-mdbook-extras b/book/scripts/install-mdbook-extras
new file mode 100755
index 0000000..df72e6d
--- /dev/null
+++ b/book/scripts/install-mdbook-extras
@@ -0,0 +1,9 @@
+#!/bin/bash
+
+set -exuo pipefail
+
+cd "$(dirname "$0")"/../..
+
+if ! mdbook-toc --version; then
+  cargo install mdbook-toc --version 0.13.0 --force
+fi
diff --git a/book/src/overview.md b/book/src/overview.md
index 2a112c5..8518140 100644
--- a/book/src/overview.md
+++ b/book/src/overview.md
@@ -1,5 +1,9 @@
 # mdbook-admonish
 
+<!-- toc -->
+
+## Intoduction
+
 [![Latest version](https://img.shields.io/crates/v/mdbook-admonish.svg)](https://crates.io/crates/mdbook-admonish)
 [![docs.rs](https://img.shields.io/docsrs/mdbook-admonish)](https://docs.rs/mdbook-admonish)
 
@@ -21,6 +25,8 @@ A beautifully styled message.
 
 ## Usage
 
+### A basic `admonish` block
+
 Use any [fenced code-block](https://spec.commonmark.org/0.30/#fenced-code-blocks) as you normally would, but annotate it with `admonish <admonition type>`:
 
 ````
@@ -33,7 +39,7 @@ My example is the best!
 My example is the best!
 ```
 
-See the [mkdocs-material docs](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types) for a list of supported admonitions. You'll find:
+See the [list of directives](./reference.md) for a full list of supported admonitions. You'll find:
 
 - `info`
 - `warning`
@@ -54,8 +60,28 @@ A plain note.
 A plain note.
 ```
 
+### Invalid blocks
+
+By default, if an `admonish` block cannot be parsed, an error will be rendered in the output:
+
+````
+```admonish title="\j"
+This block will error
+```
+````
+
+```admonish title="\j"
+This block will error
+```
+
+You can also configure the build to fail loudly, by setting `on_failure = "bail"` in `book.toml`. See the [configuration reference](./reference.md) for more details.
+
 ### Additional Options
 
+You can pass additional options to each block. The options are structured as TOML key-value pairs.
+
+Note that some options can be passed globally, through the `default` section in `book.toml`. See the [configuration reference](./reference.md) for more details.
+
 #### Custom title
 
 A custom title can be provided, contained in a double quoted TOML string.
@@ -150,17 +176,3 @@ Will yield something like the following HTML, which you can then apply styles to
 ```admonish collapsible=true
 Content will be hidden initially.
 ```
-
-#### Invalid blocks
-
-If a rendering error occurs, an error will be rendered in the output:
-
-````
-```admonish title="\j"
-This block will error
-```
-````
-
-```admonish title="\j"
-This block will error
-```
diff --git a/book/src/reference.md b/book/src/reference.md
index 3da9730..2228425 100644
--- a/book/src/reference.md
+++ b/book/src/reference.md
@@ -1,5 +1,93 @@
 # Reference
 
+<!-- toc -->
+
+## `book.toml` configuration
+
+See below for all configuration options available to add in `book.toml`.
+
+The options should all be nested under `preprocessor.admonish`; for example:
+
+```toml
+[preprocessor.admonish]
+on_failure = "bail"
+
+[preprocessor.admonish.default]
+collapsible = true
+
+[preprocessor.admonish.renderer.test]
+render_mode = "strip"
+```
+
+### `on_failure`
+
+Optional. Default value: `continue`.
+
+The action to take when an invalid `admonish` block is encountered:
+
+- `continue` (default): Continue processing future blocks, do not fail the build. If rendering to HTML, an error message will be displayed in the book output.
+- `bail`: Abort the build.
+
+### `default`
+
+Optional.
+
+Default values to use, when not provided in an `admonish` block explicitly.
+
+Subfields:
+
+- `default.title` (optional): Title to use for blocks. Defaults to the directive used in titlecase.
+- `default.collapsible` (optional, default: `false`): Make blocks collapsible by default when set to `true`.
+
+### `renderer`
+
+````admonish tip
+It is recommended that you set:
+
+```toml
+[preprocessor.admonish.renderer.test]
+render_mode = "strip"
+```
+
+This allows `mdbook test` to find and test rust examples within `admonish` blocks.
+
+This will be the default behaviour in the next `mdbook-admonish` major version.
+````
+
+Optional.
+
+Additional settings to apply, depending on the renderer that is running.
+
+The most common renderers used are:
+
+- `html`: Used by `mdbook build` to build the final book output.
+- `test`: Used by `mdbook test` to find and run doctests.
+
+Subfields:
+
+- `renderer.<renderer_name>.render_mode` (optional): The action `mdbook-admonish` should take when running with this renderer.
+  - Valid values:
+    - `html`: Convert `admonish` blocks into HTML output.
+    - `preserve`: Do nothing. Leave the book untouched.
+    - `strip`: Strip `admonish`-specific syntax, leaving the inner content untouched.
+  - Default values:
+    - For the `html` renderer, the default value is `html`.
+    - For all other renderers, the default value is `preserve`.
+
+### `command`
+
+Required.
+
+Used by `mdbook` to know how to call the `mdbook-admonish` plugin.
+
+Running this command with the `--version` flag from your shell should work, for the plugin to function.
+
+### `assets_version`
+
+Optional.
+
+This is automatically updated by `mdbook-admonish install` and should not be edited.
+
 ## Directives
 
 All supported directives are listed below.