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]
|
2017-11-30 23:26:30 +08:00
|
|
|
build-dir = "my-example-book"
|
2017-11-30 12:02:58 +08:00
|
|
|
create-missing = false
|
|
|
|
|
|
2017-05-20 21:03:10 +08:00
|
|
|
[output.html]
|
|
|
|
|
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.
|
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`
|
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.
|
|
|
|
|
|
2017-11-30 23:26:30 +08:00
|
|
|
- **build-dir:** The directory to put the rendered book in. By default this is
|
|
|
|
|
`book/` in the book's root directory.
|
2017-11-30 12:02:58 +08:00
|
|
|
- **create-missing:** By default, any missing files specified in `SUMMARY.md`
|
2017-11-30 23:26:30 +08:00
|
|
|
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.
|
2017-11-30 12:02:58 +08:00
|
|
|
|
|
|
|
|
**book.toml**
|
|
|
|
|
```toml
|
|
|
|
|
[build]
|
2017-11-30 23:26:30 +08:00
|
|
|
build-dir = "build"
|
2017-11-30 12:02:58 +08:00
|
|
|
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
|
|
|
- **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
|
|
|
```
|
