2015-08-03 20:23:32 +08:00
|
|
|
# Configuration
|
|
|
|
|
|
2016-12-23 16:17:04 +08:00
|
|
|
You can configure the parameters for your book in the ***book.toml*** file.
|
2015-08-03 20:23:32 +08:00
|
|
|
|
2016-12-23 16:17:04 +08:00
|
|
|
Here is an example of what a ***book.toml*** file might look like:
|
|
|
|
|
|
|
|
|
|
```toml
|
2017-11-12 03:35:10 +08:00
|
|
|
[book]
|
2016-12-23 16:17:04 +08:00
|
|
|
title = "Example book"
|
2017-05-20 21:03:10 +08:00
|
|
|
author = "John Doe"
|
2016-12-23 16:17:04 +08:00
|
|
|
description = "The example book covers examples."
|
2017-05-20 21:03:10 +08:00
|
|
|
|
2017-11-30 12:02:58 +08:00
|
|
|
[build]
|
|
|
|
|
create-missing = false
|
|
|
|
|
|
2017-05-20 21:03:10 +08:00
|
|
|
[output.html]
|
|
|
|
|
destination = "my-example-book"
|
|
|
|
|
additional-css = ["custom.css"]
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Supported configuration options
|
|
|
|
|
|
|
|
|
|
It is important to note that **any** relative path specified in the in the configuration will
|
|
|
|
|
always be taken relative from the root of the book where the configuration file is located.
|
|
|
|
|
|
|
|
|
|
|
2017-11-12 03:35:10 +08:00
|
|
|
### General metadata
|
2017-05-20 21:03:10 +08:00
|
|
|
|
2017-11-12 03:35:10 +08:00
|
|
|
This is general information about your book.
|
2017-05-20 21:03:10 +08:00
|
|
|
|
2017-11-12 03:35:10 +08:00
|
|
|
- **title:** The title of the book
|
|
|
|
|
- **authors:** The author(s) of the book
|
|
|
|
|
- **description:** A description for the book, which is added as meta
|
|
|
|
|
information in the html `<head>` of each page
|
|
|
|
|
- **src:** By default, the source directory is found in the directory named
|
|
|
|
|
`src` directly under the root folder. But this is configurable with the `src`
|
|
|
|
|
key in the configuration file.
|
|
|
|
|
- **build-dir:** The directory to put the rendered book in. By default this is
|
|
|
|
|
`book/` in the book's root directory.
|
2017-05-20 21:03:10 +08:00
|
|
|
|
|
|
|
|
**book.toml**
|
|
|
|
|
```toml
|
2017-11-12 03:35:10 +08:00
|
|
|
[book]
|
2017-05-20 21:03:10 +08:00
|
|
|
title = "Example book"
|
|
|
|
|
authors = ["John Doe", "Jane Doe"]
|
|
|
|
|
description = "The example book covers examples."
|
2017-11-12 03:35:10 +08:00
|
|
|
src = "my-src" # the source files will be found in `root/my-src` instead of `root/src`
|
|
|
|
|
build-dir = "build"
|
2015-08-03 20:23:32 +08:00
|
|
|
```
|
|
|
|
|
|
2017-11-30 12:02:58 +08:00
|
|
|
### Build options
|
|
|
|
|
|
|
|
|
|
This controls the build process of your book.
|
|
|
|
|
|
|
|
|
|
- **create-missing:** By default, any missing files specified in `SUMMARY.md`
|
|
|
|
|
will be created when the book is built. If this is `false` then the build
|
|
|
|
|
process will instead exit with an error if any files do not exist.
|
|
|
|
|
|
|
|
|
|
**book.toml**
|
|
|
|
|
```toml
|
|
|
|
|
[build]
|
|
|
|
|
create-missing = false
|
|
|
|
|
```
|
|
|
|
|
|
2017-05-20 21:03:10 +08:00
|
|
|
### HTML renderer options
|
2017-11-12 03:35:10 +08:00
|
|
|
The HTML renderer has a couple of options as well. All the options for the
|
|
|
|
|
renderer need to be specified under the TOML table `[output.html]`.
|
|
|
|
|
|
2017-05-20 21:03:10 +08:00
|
|
|
The following configuration options are available:
|
2015-08-03 20:23:32 +08:00
|
|
|
|
2017-11-12 03:35:10 +08:00
|
|
|
pub playpen: Playpen,
|
|
|
|
|
|
|
|
|
|
- **theme:** mdBook comes with a default theme and all the resource files
|
|
|
|
|
needed for it. But if this option is set, mdBook will selectively overwrite
|
|
|
|
|
the theme files with the ones found in the specified folder.
|
|
|
|
|
- **curly-quotes:** Convert straight quotes to curly quotes, except for
|
|
|
|
|
those that occur in code blocks and code spans. Defaults to `false`.
|
|
|
|
|
- **google-analytics:** If you use Google Analytics, this option lets you
|
|
|
|
|
enable it by simply specifying your ID in the configuration file.
|
|
|
|
|
- **additional-css:** If you need to slightly change the appearance of your
|
|
|
|
|
book without overwriting the whole style, you can specify a set of
|
|
|
|
|
stylesheets that will be loaded after the default ones where you can
|
|
|
|
|
surgically change the style.
|
|
|
|
|
- **additional-js:** If you need to add some behaviour to your book without
|
|
|
|
|
removing the current behaviour, you can specify a set of javascript files
|
|
|
|
|
that will be loaded alongside the default one.
|
|
|
|
|
- **playpen:** A subtable for configuring various playpen settings.
|
2016-12-07 22:22:32 +08:00
|
|
|
|
2017-05-20 21:03:10 +08:00
|
|
|
**book.toml**
|
|
|
|
|
```toml
|
2017-11-12 03:35:10 +08:00
|
|
|
[book]
|
2017-05-20 21:03:10 +08:00
|
|
|
title = "Example book"
|
|
|
|
|
authors = ["John Doe", "Jane Doe"]
|
|
|
|
|
description = "The example book covers examples."
|
|
|
|
|
|
|
|
|
|
[output.html]
|
|
|
|
|
theme = "my-theme"
|
2017-06-01 13:28:08 +08:00
|
|
|
curly-quotes = true
|
2017-05-20 21:03:10 +08:00
|
|
|
google-analytics = "123456"
|
|
|
|
|
additional-css = ["custom.css", "custom2.css"]
|
2017-08-10 23:39:28 +08:00
|
|
|
additional-js = ["custom.js"]
|
2017-11-12 03:35:10 +08:00
|
|
|
|
|
|
|
|
[output.html.playpen]
|
|
|
|
|
editor = "./path/to/editor"
|
|
|
|
|
editable = false
|
2017-05-20 21:03:10 +08:00
|
|
|
```
|
2015-08-06 21:24:34 +08:00
|
|
|
|
2017-11-12 03:35:10 +08:00
|
|
|
|
|
|
|
|
## For Developers
|
|
|
|
|
|
|
|
|
|
If you are developing a plugin or alternate backend then whenever your code is
|
|
|
|
|
called you will almost certainly be passed a reference to the book's `Config`.
|
|
|
|
|
This can be treated roughly as a nested hashmap which lets you call methods like
|
|
|
|
|
`get()` and `get_mut()` to get access to the config's contents.
|
|
|
|
|
|
|
|
|
|
By convention, plugin developers will have their settings as a subtable inside
|
|
|
|
|
`plugins` (e.g. a link checker would put its settings in `plugins.link_check`)
|
|
|
|
|
and backends should put their configuration under `output`, like the HTML
|
|
|
|
|
renderer does in the previous examples.
|
|
|
|
|
|
|
|
|
|
As an example, some hypothetical `random` renderer would typically want to load
|
|
|
|
|
its settings from the `Config` at the very start of its rendering process. The
|
|
|
|
|
author can take advantage of serde to deserialize the generic `toml::Value`
|
|
|
|
|
object retrieved from `Config` into a struct specific to its use case.
|
|
|
|
|
|
|
|
|
|
```rust
|
|
|
|
|
#[derive(Debug, Deserialize, PartialEq)]
|
|
|
|
|
struct RandomOutput {
|
|
|
|
|
foo: u32,
|
|
|
|
|
bar: String,
|
|
|
|
|
baz: Vec<bool>,
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
let src = r#"
|
|
|
|
|
[output.random]
|
|
|
|
|
foo = 5
|
|
|
|
|
bar = "Hello World"
|
|
|
|
|
baz = [true, true, false]
|
|
|
|
|
"#;
|
|
|
|
|
|
|
|
|
|
let book_config = Config::from_str(src)?; // usually passed in by mdbook
|
|
|
|
|
let random: Value = book_config.get("output.random").unwrap_or_default();
|
|
|
|
|
let got: RandomOutput = random.try_into()?;
|
|
|
|
|
|
|
|
|
|
assert_eq!(got, should_be);
|
|
|
|
|
|
|
|
|
|
if let Some(baz) = book_config.get_deserialized::<Vec<bool>>("output.random.baz") {
|
|
|
|
|
println!("{:?}", baz); // prints [true, true, false]
|
|
|
|
|
|
|
|
|
|
// do something interesting with baz
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// start the rendering process
|
2017-11-30 12:02:58 +08:00
|
|
|
```
|
