Skip to content

Commit 1747677

Browse files
committed
Update mdbook configuration
This commits explicitly sets many configuration options for the mdbook generation. In particular, for generic options (see https://rust-lang.github.io/mdBook/format/configuration/general.html#build-options): - 'create-missing' is set to false. This will make the build process exit with an error if any files do not exist in 'SUMMARY.md'. - 'use-default-preprocessors' is set to false. This disables the default preprocessors ('links' & 'index'). The 'index' preprocessor converts all chapter files named 'README.md' into 'index.md', but there is a catch: relative links are not dynamically updated (see rust-lang/mdBook#1921), leading to errors at build generation. We can live just fine without that plugin. The 'links' preprocessor expands the {{ #playground }}, {{ #include }}, and {{ #rustdoc_include }} handlebars helpers in a chapter to include the contents of a file. We can probably live without too (although it could be re-enabled). And for specific "linkcheck" options (see https://github.com/Michael-F-Bryan/mdbook-linkcheck/blob/v0.7.7/README.md?plain=1#L64-L125): - 'optional' is set to true. This will output a warning if the plugin is not installed, rather than failing to build entirely. - 'warning-policy is set to 'warn'. This changes the level of messages to warnings, rather than errors that interrupt the build process. - 'traverse-parent-directories' is set to false. This disallows linking to files outside of the book's root directory. - 'exclude' is set to some links. This excludes the linkchecking from running on those. They were chosen after trial and error.
1 parent 11b8cc8 commit 1747677

File tree

2 files changed

+9
-3
lines changed

2 files changed

+9
-3
lines changed

docs/README-for-doc.zonemaster.net.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,5 +49,5 @@ The public documentation is divided into the following main categories:
4949
[The Swedish Internet Foundation]: https://internetstiftelsen.se/en/
5050
[Zonemaster.net]: https://zonemaster.net
5151

52-
<!-- Location on doc.zonemaster.net: -->
52+
<!-- Location on doc.zonemaster.net: -->
5353
[Zonemaster-logo]: ../zonemaster_logo_2021_color.png

docs/public/book.toml

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,20 @@ description = "Zonemaster documentation"
44
language = "en"
55
src = "./"
66

7+
[build]
8+
create-missing = false
9+
use-default-preprocessors = false
10+
711
[output.html]
812
no-section-label = true
913

1014
[output.html.fold]
1115
enable = true
1216
level = 1
1317

14-
[preprocessor.index]
15-
1618
[output.linkcheck]
19+
optional = true
20+
warning-policy= "warn"
1721
follow-web-links = false
22+
traverse-parent-directories = false
23+
exclude = [ 'SUMMARY.md', 'LICENSE.md', 'zonemaster_logo_2021_color.png', 'localhost' ]

0 commit comments

Comments
 (0)