You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
It is important to note that **any** relative path specified in the in the configuration will
25
21
always be taken relative from the root of the book where the configuration file is located.
26
22
27
-
### General metadata
28
23
29
-
-**title:** The title of the book
30
-
-**author:** The author of the book
31
-
-**description:** A description for the book, which is added as meta information in the html `<head>` of each page
32
-
33
-
**book.toml**
34
-
```toml
35
-
title = "Example book"
36
-
author = "John Doe"
37
-
description = "The example book covers examples."
38
-
```
24
+
### General metadata
39
25
40
-
Some books may have multiple authors, there is an alternative key called `authors` plural that lets you specify an array
41
-
of authors.
26
+
This is general information about your book.
42
27
43
-
**book.toml**
44
-
```toml
45
-
title = "Example book"
46
-
authors = ["John Doe", "Jane Doe"]
47
-
description = "The example book covers examples."
48
-
```
49
-
50
-
### Source directory
51
-
By default, the source directory is found in the directory named `src` directly under the root folder. But this is configurable
52
-
with the `source` key in the configuration file.
28
+
-**title:** The title of the book
29
+
-**authors:** The author(s) of the book
30
+
-**description:** A description for the book, which is added as meta
31
+
information in the html `<head>` of each page
32
+
-**src:** By default, the source directory is found in the directory named
33
+
`src` directly under the root folder. But this is configurable with the `src`
34
+
key in the configuration file.
35
+
-**build-dir:** The directory to put the rendered book in. By default this is
36
+
`book/` in the book's root directory.
53
37
54
38
**book.toml**
55
39
```toml
40
+
[book]
56
41
title = "Example book"
57
42
authors = ["John Doe", "Jane Doe"]
58
43
description = "The example book covers examples."
59
-
60
-
source = "my-src"# the source files will be found in `root/my-src` instead of `root/src`
44
+
src = "my-src"# the source files will be found in `root/my-src` instead of `root/src`
45
+
build-dir = "build"
61
46
```
62
47
63
48
### HTML renderer options
64
-
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]`.
49
+
The HTML renderer has a couple of options as well. All the options for the
50
+
renderer need to be specified under the TOML table `[output.html]`.
51
+
65
52
The following configuration options are available:
66
53
67
-
-**`destination`:** By default, the HTML book will be rendered in the `root/book` directory, but this option lets you specify another
68
-
destination fodler.
69
-
-**`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.
70
-
-**`curly-quotes`:** Convert straight quotes to curly quotes, except for those that occur in code blocks and code spans. Defaults to `false`.
71
-
-**`google-analytics`:** If you use Google Analytics, this option lets you enable it by simply specifying your ID in the configuration file.
72
-
-**`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.
73
-
-**`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.
54
+
pub playpen: Playpen,
55
+
56
+
-**theme:** mdBook comes with a default theme and all the resource files
57
+
needed for it. But if this option is set, mdBook will selectively overwrite
58
+
the theme files with the ones found in the specified folder.
59
+
-**curly-quotes:** Convert straight quotes to curly quotes, except for
60
+
those that occur in code blocks and code spans. Defaults to `false`.
61
+
-**google-analytics:** If you use Google Analytics, this option lets you
62
+
enable it by simply specifying your ID in the configuration file.
63
+
-**additional-css:** If you need to slightly change the appearance of your
64
+
book without overwriting the whole style, you can specify a set of
65
+
stylesheets that will be loaded after the default ones where you can
66
+
surgically change the style.
67
+
-**additional-js:** If you need to add some behaviour to your book without
68
+
removing the current behaviour, you can specify a set of javascript files
69
+
that will be loaded alongside the default one.
70
+
-**playpen:** A subtable for configuring various playpen settings.
74
71
75
72
**book.toml**
76
73
```toml
74
+
[book]
77
75
title = "Example book"
78
76
authors = ["John Doe", "Jane Doe"]
79
77
description = "The example book covers examples."
80
78
81
79
[output.html]
82
-
destination = "my-book"# the output files will be generated in `root/my-book` instead of `root/book`
83
80
theme = "my-theme"
84
81
curly-quotes = true
85
82
google-analytics = "123456"
86
83
additional-css = ["custom.css", "custom2.css"]
87
84
additional-js = ["custom.js"]
85
+
86
+
[output.html.playpen]
87
+
editor = "./path/to/editor"
88
+
editable = false
88
89
```
89
90
91
+
92
+
## For Developers
93
+
94
+
If you are developing a plugin or alternate backend then whenever your code is
95
+
called you will almost certainly be passed a reference to the book's `Config`.
96
+
This can be treated roughly as a nested hashmap which lets you call methods like
97
+
`get()` and `get_mut()` to get access to the config's contents.
98
+
99
+
By convention, plugin developers will have their settings as a subtable inside
100
+
`plugins` (e.g. a link checker would put its settings in `plugins.link_check`)
101
+
and backends should put their configuration under `output`, like the HTML
102
+
renderer does in the previous examples.
103
+
104
+
As an example, some hypothetical `random` renderer would typically want to load
105
+
its settings from the `Config` at the very start of its rendering process. The
106
+
author can take advantage of serde to deserialize the generic `toml::Value`
107
+
object retrieved from `Config` into a struct specific to its use case.
108
+
109
+
```rust
110
+
#[derive(Debug, Deserialize, PartialEq)]
111
+
structRandomOutput {
112
+
foo:u32,
113
+
bar:String,
114
+
baz:Vec<bool>,
115
+
}
116
+
117
+
letsrc=r#"
118
+
[output.random]
119
+
foo = 5
120
+
bar = "Hello World"
121
+
baz = [true, true, false]
122
+
"#;
123
+
124
+
letbook_config=Config::from_str(src)?; // usually passed in by mdbook
0 commit comments