diff --git a/book-example/src/for_developers/backends.md b/book-example/src/for_developers/backends.md index 1b289c5f..605c2191 100644 --- a/book-example/src/for_developers/backends.md +++ b/book-example/src/for_developers/backends.md @@ -331,7 +331,7 @@ the usual `RUST_LOG` to control logging verbosity. ## Handling missing backends -If you should enable a backend that isn't installed, the default behavior is to throw an error: +If you enable a backend that isn't installed, the default behavior is to throw an error: ```text The command wasn't found, is the "wordcount" backend installed? diff --git a/book-example/src/format/config.md b/book-example/src/format/config.md index 82c896c3..d8be13e8 100644 --- a/book-example/src/format/config.md +++ b/book-example/src/format/config.md @@ -306,11 +306,17 @@ specify which preprocessors should run before the Markdown renderer. 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. +rendering. See the [alternative backends] chapter for more detail. -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. +The custom renderer has access to all the fields within its table (i.e. +anything under `[output.foo]`). mdBook checks for two common fields: + +- **command:** The command to execute for this custom renderer. Defaults to + the name of the renderer with the `mdbook-` prefix (such as `mdbook-foo`). +- **optional:** If `true`, then the command will be ignored if it is not + installed, otherwise mdBook will fail with an error. Defaults to `false`. + +[alternative backends]: ../for_developers/backends.md ## Environment Variables diff --git a/src/renderer/mod.rs b/src/renderer/mod.rs index 02244ae2..318e7da3 100644 --- a/src/renderer/mod.rs +++ b/src/renderer/mod.rs @@ -166,15 +166,17 @@ impl CmdRenderer { }; if is_optional { - warn!("The command was not found, but was marked as optional."); - warn!("\tCommand: {}", self.cmd); + warn!( + "The command `{}` for backend `{}` was not found, \ + but was marked as optional.", + self.cmd, self.name + ); return Ok(()); } else { error!( - "The command wasn't found, is the \"{}\" backend installed?", - self.name + "The command `{}` wasn't found, is the `{}` backend installed?", + self.cmd, self.name ); - error!("\tCommand: {}", self.cmd); } } _ => {}