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
2017-08-10 23:39:28 +08:00
>**Note:**
JSON configuration files were previously supported but have been deprecated in favor of
2017-05-20 21:03:10 +08:00
the TOML configuration file. If you are still using JSON we strongly encourage you to migrate to
the TOML configuration because JSON support will be removed in the future.
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
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
[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.
### General metadata
- **title:** The title of the book
- **author:** The author of the book
- **description:** A description for the book, which is added as meta information in the html `<head>` of each page
**book.toml**
```toml
title = "Example book"
author = "John Doe"
description = "The example book covers examples."
```
Some books may have multiple authors, there is an alternative key called `authors` plural that lets you specify an array
of authors.
**book.toml**
```toml
title = "Example book"
authors = ["John Doe", "Jane Doe"]
description = "The example book covers examples."
```
### Source directory
By default, the source directory is found in the directory named `src` directly under the root folder. But this is configurable
with the `source` key in the configuration file.
**book.toml**
```toml
title = "Example book"
authors = ["John Doe", "Jane Doe"]
description = "The example book covers examples."
source = "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-05-20 21:03:10 +08:00
### HTML renderer options
The HTML renderer has a couple of options aswell. All the options for the renderer need to be specified under the TOML table `[output.html]` .
The following configuration options are available:
2015-08-03 20:23:32 +08:00
2017-08-10 23:39:28 +08:00
- **`destination`:** By default, the HTML book will be rendered in the `root/book` directory, but this option lets you specify another
2017-05-20 21:03:10 +08:00
destination fodler.
2017-08-10 23:39:28 +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.
2016-12-07 22:22:32 +08:00
2017-05-20 21:03:10 +08:00
**book.toml**
```toml
title = "Example book"
authors = ["John Doe", "Jane Doe"]
description = "The example book covers examples."
[output.html]
destination = "my-book" # the output files will be generated in `root/my-book` instead of `root/book`
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-05-20 21:03:10 +08:00
```
2015-08-06 21:24:34 +08:00
