fd7e8d1b7b
* Added a mechanism for creating alternate backends * Added a CmdRenderer and the ability to have multiple renderers * Made MDBook::load() autodetect renderers * Added a couple methods to RenderContext * Converted RenderContext.version to a String * Made sure all alternate renderers are invoked as `mdbook-*` * Factored out the logic for determining which renderer to use * Added tests for renderer detection * Made it so `mdbook test` works on the book-example again * Updated the "For Developers" docs * Removed `[output.epub]` from the example book's book.toml * Added a bit more info on how backends should work * Added a `destination` key to the RenderContext * Altered how we wait for an alternate backend to finish * Refactored the Renderer trait to not use MDBook and moved livereload to the template * Moved info for developers out of the book.toml format chapter * MOAR docs * MDBook::build() no longer takes &mut self * Replaced a bunch of println!()'s with proper log macros * Cleaned up the build() method and backend discovery * Added a couple notes and doc-comments * Found a race condition when backends exit really quickly * Added support for backends with arguments * Fixed a funny doc-comment
3.3 KiB
3.3 KiB
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:
[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"]
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
srcdirectly under the root folder. But this is configurable with thesrckey in the configuration file.
book.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.mdwill be created when the book is built (i.e.create-missing = true). If this isfalsethen the build process will instead exit with an error if any files do not exist.
book.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.
- playpen: A subtable for configuring various playpen settings.
book.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