mdBook/book-example/src/format/config.md

# Configuration

You can configure the parameters for your book in the ***book.toml*** file.

Here is an example of what a ***book.toml*** file might look like:

```toml
[book]
title = "Example book"
author = "John Doe"
description = "The example book covers examples."

[build]
build-dir = "my-example-book"
create-missing = false

[output.html]
additional-css = ["custom.css"]

[output.html.search]
limit-results = 15
```

## 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

This is general information about your book.

- **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.

**book.toml**
```toml
[book]
title = "Example book"
authors = ["John Doe", "Jane Doe"]
description = "The example book covers examples."
src = "my-src"  # the source files will be found in `root/my-src` instead of `root/src`
```

### Build options

This controls the build process of your book.

- **build-dir:** The directory to put the rendered book in. By default this is
  `book/` in the book's root directory.
- **create-missing:** By default, any missing files specified in `SUMMARY.md`
  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.

**book.toml**
```toml
[build]
build-dir = "build"
create-missing = false
```

### HTML renderer options
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]`.

The following configuration options are available:

- **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.
- **no-section-label:** mdBook by defaults adds section label in table of
  contents column. For example, "1.", "2.1". Set this option to true to
  disable those labels. Defaults to `false`.
- **playpen:** A subtable for configuring various playpen settings.
- **search:** A subtable for configuring the in-browser search
  functionality. mdBook must be compiled with the `search` feature enabled
  (on by default).

Available configuration options for the `[output.html.playpen]` table:

- **editable:** Allow editing the source code. Defaults to `false`.
- **copy-js:** Copy JavaScript files for the editor to the output directory.
  Defaults to `true`.

[Ace]: https://ace.c9.io/

Available configuration options for the `[output.html.search]` table:

- **limit-results:** The maximum number of search results. Defaults to `30`.
- **teaser-word-count:** The number of words used for a search result teaser. 
  Defaults to `30`.
- **use-boolean-and:** Define the logical link between multiple search words. 
  If true, all search words must appear in each result. Defaults to `true`.
- **boost-title:** Boost factor for the search result score if a search word
  appears in the header. Defaults to `2`.
- **boost-hierarchy:** Boost factor for the search result score if a search
  word appears in the hierarchy. The hierarchy contains all titles of the
  parent documents and all parent headings. Defaults to `1`.
- **boost-paragraph:** Boost factor for the search result score if a search 
  word appears in the text. Defaults to `1`.
- **expand:** True if search should match longer results e.g. search `micro` 
  should match `microwave`. Defaults to `true`.
- **heading-split-level:** Search results will link to a section of the document
  which contains the result. Documents are split into sections by headings
  this level or less.
  Defaults to `3`. (`### This is a level 3 heading`)
- **copy-js:** Copy JavaScript files for the search implementation to the
  output directory. Defaults to `true`.

This shows all available options in the **book.toml**:
```toml
[book]
title = "Example book"
authors = ["John Doe", "Jane Doe"]
description = "The example book covers examples."

[output.html]
theme = "my-theme"
curly-quotes = true
google-analytics = "123456"
additional-css = ["custom.css", "custom2.css"]
additional-js = ["custom.js"]

[output.html.playpen]
editor = "./path/to/editor"
editable = false

[output.html.search]
enable = true
searcher = "./path/to/searcher"
limit-results = 30
teaser-word-count = 30
use-boolean-and = true
boost-title = 2
boost-hierarchy = 1
boost-paragraph = 1
expand = true
heading-split-level = 3
```


## Environment Variables

All configuration values can be overridden from the command line by setting the
corresponding environment variable. Because many operating systems restrict
environment variables to be alphanumeric characters or `_`, the configuration
key needs to be formatted slightly differently to the normal `foo.bar.baz` form.

Variables starting with `MDBOOK_` are used for configuration. The key is
created by removing the `MDBOOK_` prefix and turning the resulting
string into `kebab-case`. Double underscores (`__`) separate nested
keys, while a single underscore (`_`) is replaced with a dash (`-`).

For example:

- `MDBOOK_foo` -> `foo`
- `MDBOOK_FOO` -> `foo`
- `MDBOOK_FOO__BAR` -> `foo.bar`
- `MDBOOK_FOO_BAR` -> `foo-bar`
- `MDBOOK_FOO_bar__baz` -> `foo-bar.baz`

So by setting the `MDBOOK_BOOK__TITLE` environment variable you can
override the book's title without needing to touch your `book.toml`.

> **Note:** To facilitate setting more complex config items, the value
> of an environment variable is first parsed as JSON, falling back to a
> string if the parse fails.
>
> This means, if you so desired, you could override all book metadata
> when building the book with something like
>
> ```text
> $ export MDBOOK_BOOK="{'title': 'My Awesome Book', authors: ['Michael-F-Bryan']}"
> $ mdbook build
> ```

The latter case may be useful in situations where `mdbook` is invoked
from a script or CI, where it sometimes isn't possible to update the
`book.toml` before building.
Added author and dest field in book.json, fixed bug when output directory did not exist. Closes #7 2015-08-03 20:23:32 +08:00			`# Configuration`

update example to encourage using book.toml 2016-12-23 16:17:04 +08:00			`You can configure the parameters for your book in the *book.toml* file.`
Added author and dest field in book.json, fixed bug when output directory did not exist. Closes #7 2015-08-03 20:23:32 +08:00
update example to encourage using book.toml 2016-12-23 16:17:04 +08:00			`Here is an example of what a *book.toml* file might look like:`

			```toml
Updated the configuration chapter in the book-example 2017-11-12 03:35:10 +08:00			`[book]`
update example to encourage using book.toml 2016-12-23 16:17:04 +08:00			`title = "Example book"`
Document the TOML configuration file 2017-05-20 21:03:10 +08:00			`author = "John Doe"`
update example to encourage using book.toml 2016-12-23 16:17:04 +08:00			`description = "The example book covers examples."`
Document the TOML configuration file 2017-05-20 21:03:10 +08:00
Add a create-missing option to book.toml. 2017-11-30 12:02:58 +08:00			`[build]`
Clean up build configuration. This rolls all "create missing" handling into BuildConfig, and moves the build-dir option from the "book" table to the "build" table. Some documentation cleanup surrounding the build table is also updated. 2017-11-30 23:26:30 +08:00			`build-dir = "my-example-book"`
Add a create-missing option to book.toml. 2017-11-30 12:02:58 +08:00			`create-missing = false`

Document the TOML configuration file 2017-05-20 21:03:10 +08:00			`[output.html]`
			`additional-css = ["custom.css"]`
Search with Elasticlunr, updated (#604) * Add search with elasticlunr.js This commit adds search functionality to mdBook, based on work done by @phaiax. The in-browser search code uses elasticlunr.js to execute the search, using an index generated at book build time by elasticlunr-rs. * Add generator comment Someone on Reddit was wondering how the rust book was generated and said they checked the source. Thought I'd put this here. Might be a good idea to have a little footer "made with mdBook", but this'll do for now. * Remove search/editor file override behavior * Use for loop for book iterator * Improve HTML regex * Fix search CORS in file URIs * Use ammonia to sanitize HTML * Filter html5ever log messages 2018-03-07 21:02:06 +08:00
			`[output.html.search]`
			`limit-results = 15`
Document the TOML configuration file 2017-05-20 21:03:10 +08:00			```

			`## 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.`


Updated the configuration chapter in the book-example 2017-11-12 03:35:10 +08:00			`### General metadata`
Document the TOML configuration file 2017-05-20 21:03:10 +08:00
Updated the configuration chapter in the book-example 2017-11-12 03:35:10 +08:00			`This is general information about your book.`
Document the TOML configuration file 2017-05-20 21:03:10 +08:00
Updated the configuration chapter in the book-example 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.`
Document the TOML configuration file 2017-05-20 21:03:10 +08:00
			`book.toml`
			```toml
Updated the configuration chapter in the book-example 2017-11-12 03:35:10 +08:00			`[book]`
Document the TOML configuration file 2017-05-20 21:03:10 +08:00			`title = "Example book"`
			`authors = ["John Doe", "Jane Doe"]`
			`description = "The example book covers examples."`
Updated the configuration chapter in the book-example 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`
Added author and dest field in book.json, fixed bug when output directory did not exist. Closes #7 2015-08-03 20:23:32 +08:00			```

Add a create-missing option to book.toml. 2017-11-30 12:02:58 +08:00			`### Build options`

			`This controls the build process of your book.`

Clean up build configuration. This rolls all "create missing" handling into BuildConfig, and moves the build-dir option from the "book" table to the "build" table. Some documentation cleanup surrounding the build table is also updated. 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.
Add a create-missing option to book.toml. 2017-11-30 12:02:58 +08:00			- create-missing: By default, any missing files specified in `SUMMARY.md`
Clean up build configuration. This rolls all "create missing" handling into BuildConfig, and moves the build-dir option from the "book" table to the "build" table. Some documentation cleanup surrounding the build table is also updated. 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.`
Add a create-missing option to book.toml. 2017-11-30 12:02:58 +08:00
			`book.toml`
			```toml
			`[build]`
Clean up build configuration. This rolls all "create missing" handling into BuildConfig, and moves the build-dir option from the "book" table to the "build" table. Some documentation cleanup surrounding the build table is also updated. 2017-11-30 23:26:30 +08:00			`build-dir = "build"`
Add a create-missing option to book.toml. 2017-11-30 12:02:58 +08:00			`create-missing = false`
			```

Document the TOML configuration file 2017-05-20 21:03:10 +08:00			`### HTML renderer options`
Updated the configuration chapter in the book-example 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]`.

Document the TOML configuration file 2017-05-20 21:03:10 +08:00			`The following configuration options are available:`
Added author and dest field in book.json, fixed bug when output directory did not exist. Closes #7 2015-08-03 20:23:32 +08:00
Updated the configuration chapter in the book-example 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`
Search with Elasticlunr, updated (#604) * Add search with elasticlunr.js This commit adds search functionality to mdBook, based on work done by @phaiax. The in-browser search code uses elasticlunr.js to execute the search, using an index generated at book build time by elasticlunr-rs. * Add generator comment Someone on Reddit was wondering how the rust book was generated and said they checked the source. Thought I'd put this here. Might be a good idea to have a little footer "made with mdBook", but this'll do for now. * Remove search/editor file override behavior * Use for loop for book iterator * Improve HTML regex * Fix search CORS in file URIs * Use ammonia to sanitize HTML * Filter html5ever log messages 2018-03-07 21:02:06 +08:00			`removing the current behaviour, you can specify a set of JavaScript files`
Updated the configuration chapter in the book-example 2017-11-12 03:35:10 +08:00			`that will be loaded alongside the default one.`
Search with Elasticlunr, updated (#604) * Add search with elasticlunr.js This commit adds search functionality to mdBook, based on work done by @phaiax. The in-browser search code uses elasticlunr.js to execute the search, using an index generated at book build time by elasticlunr-rs. * Add generator comment Someone on Reddit was wondering how the rust book was generated and said they checked the source. Thought I'd put this here. Might be a good idea to have a little footer "made with mdBook", but this'll do for now. * Remove search/editor file override behavior * Use for loop for book iterator * Improve HTML regex * Fix search CORS in file URIs * Use ammonia to sanitize HTML * Filter html5ever log messages 2018-03-07 21:02:06 +08:00			`- no-section-label: mdBook by defaults adds section label in table of`
Add option to disable section label in html (#533) 2018-01-08 00:31:46 +08:00			`contents column. For example, "1.", "2.1". Set this option to true to`
			disable those labels. Defaults to `false`.
Search with Elasticlunr, updated (#604) * Add search with elasticlunr.js This commit adds search functionality to mdBook, based on work done by @phaiax. The in-browser search code uses elasticlunr.js to execute the search, using an index generated at book build time by elasticlunr-rs. * Add generator comment Someone on Reddit was wondering how the rust book was generated and said they checked the source. Thought I'd put this here. Might be a good idea to have a little footer "made with mdBook", but this'll do for now. * Remove search/editor file override behavior * Use for loop for book iterator * Improve HTML regex * Fix search CORS in file URIs * Use ammonia to sanitize HTML * Filter html5ever log messages 2018-03-07 21:02:06 +08:00			`- playpen: A subtable for configuring various playpen settings.`
			`- search: A subtable for configuring the in-browser search`
			functionality. mdBook must be compiled with the `search` feature enabled
			`(on by default).`

			Available configuration options for the `[output.html.playpen]` table:

			- editable: Allow editing the source code. Defaults to `false`.
			`- copy-js: Copy JavaScript files for the editor to the output directory.`
			Defaults to `true`.

			`[Ace]: https://ace.c9.io/`

			Available configuration options for the `[output.html.search]` table:

			- limit-results: The maximum number of search results. Defaults to `30`.
			`- teaser-word-count: The number of words used for a search result teaser.`
			Defaults to `30`.
			`- use-boolean-and: Define the logical link between multiple search words.`
			If true, all search words must appear in each result. Defaults to `true`.
			`- boost-title: Boost factor for the search result score if a search word`
			appears in the header. Defaults to `2`.
			`- boost-hierarchy: Boost factor for the search result score if a search`
			`word appears in the hierarchy. The hierarchy contains all titles of the`
			parent documents and all parent headings. Defaults to `1`.
			`- boost-paragraph: Boost factor for the search result score if a search`
			word appears in the text. Defaults to `1`.
			- expand: True if search should match longer results e.g. search `micro`
			should match `microwave`. Defaults to `true`.
			`- heading-split-level: Search results will link to a section of the document`
			`which contains the result. Documents are split into sections by headings`
			`this level or less.`
			Defaults to `3`. (`### This is a level 3 heading`)
			`- copy-js: Copy JavaScript files for the search implementation to the`
			output directory. Defaults to `true`.

			`This shows all available options in the book.toml:`
Document the TOML configuration file 2017-05-20 21:03:10 +08:00			```toml
Updated the configuration chapter in the book-example 2017-11-12 03:35:10 +08:00			`[book]`
Document the TOML configuration file 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"`
Add an option to convert to curly quotes when rendering to HTML 2017-06-01 13:28:08 +08:00			`curly-quotes = true`
Document the TOML configuration file 2017-05-20 21:03:10 +08:00			`google-analytics = "123456"`
			`additional-css = ["custom.css", "custom2.css"]`
Add documentation about additional-js 2017-08-10 23:39:28 +08:00			`additional-js = ["custom.js"]`
Updated the configuration chapter in the book-example 2017-11-12 03:35:10 +08:00
			`[output.html.playpen]`
			`editor = "./path/to/editor"`
			`editable = false`
Search with Elasticlunr, updated (#604) * Add search with elasticlunr.js This commit adds search functionality to mdBook, based on work done by @phaiax. The in-browser search code uses elasticlunr.js to execute the search, using an index generated at book build time by elasticlunr-rs. * Add generator comment Someone on Reddit was wondering how the rust book was generated and said they checked the source. Thought I'd put this here. Might be a good idea to have a little footer "made with mdBook", but this'll do for now. * Remove search/editor file override behavior * Use for loop for book iterator * Improve HTML regex * Fix search CORS in file URIs * Use ammonia to sanitize HTML * Filter html5ever log messages 2018-03-07 21:02:06 +08:00
			`[output.html.search]`
			`enable = true`
			`searcher = "./path/to/searcher"`
			`limit-results = 30`
			`teaser-word-count = 30`
			`use-boolean-and = true`
			`boost-title = 2`
			`boost-hierarchy = 1`
			`boost-paragraph = 1`
			`expand = true`
			`heading-split-level = 3`
Document the TOML configuration file 2017-05-20 21:03:10 +08:00			```
Override configuration using environment variables (#541) * Added the ability to update config settings from env vars * Added tests * Documented that you can override configuration with environment variables * Refactored the config get() methods to use toml-query * Made the `Updateable` trait more generic 2018-01-14 02:38:43 +08:00

			`## Environment Variables`

Fix typo in format configuration 2018-02-05 20:00:41 +08:00			`All configuration values can be overridden from the command line by setting the`
Override configuration using environment variables (#541) * Added the ability to update config settings from env vars * Added tests * Documented that you can override configuration with environment variables * Refactored the config get() methods to use toml-query * Made the `Updateable` trait more generic 2018-01-14 02:38:43 +08:00			`corresponding environment variable. Because many operating systems restrict`
			environment variables to be alphanumeric characters or `_`, the configuration
			key needs to be formatted slightly differently to the normal `foo.bar.baz` form.

			Variables starting with `MDBOOK_` are used for configuration. The key is
			created by removing the `MDBOOK_` prefix and turning the resulting
			string into `kebab-case`. Double underscores (`__`) separate nested
			keys, while a single underscore (`_`) is replaced with a dash (`-`).

			`For example:`

			- `MDBOOK_foo` -> `foo`
			- `MDBOOK_FOO` -> `foo`
			- `MDBOOK_FOO__BAR` -> `foo.bar`
			- `MDBOOK_FOO_BAR` -> `foo-bar`
			- `MDBOOK_FOO_bar__baz` -> `foo-bar.baz`

			So by setting the `MDBOOK_BOOK__TITLE` environment variable you can
			override the book's title without needing to touch your `book.toml`.

			`> Note: To facilitate setting more complex config items, the value`
			`> of an environment variable is first parsed as JSON, falling back to a`
			`> string if the parse fails.`
			`>`
			`> This means, if you so desired, you could override all book metadata`
			`> when building the book with something like`
			`>`
			> ```text
			`> $ export MDBOOK_BOOK="{'title': 'My Awesome Book', authors: ['Michael-F-Bryan']}"`
			`> $ mdbook build`
			> ```

			The latter case may be useful in situations where `mdbook` is invoked
			`from a script or CI, where it sometimes isn't possible to update the`
Search with Elasticlunr, updated (#604) * Add search with elasticlunr.js This commit adds search functionality to mdBook, based on work done by @phaiax. The in-browser search code uses elasticlunr.js to execute the search, using an index generated at book build time by elasticlunr-rs. * Add generator comment Someone on Reddit was wondering how the rust book was generated and said they checked the source. Thought I'd put this here. Might be a good idea to have a little footer "made with mdBook", but this'll do for now. * Remove search/editor file override behavior * Use for loop for book iterator * Improve HTML regex * Fix search CORS in file URIs * Use ammonia to sanitize HTML * Filter html5ever log messages 2018-03-07 21:02:06 +08:00			`book.toml` before building.