avoid repeating call on this tool when mdbook watch
Once mdbook watch
detects your files changed, freshing leads to invoke preprocessor.theme
, and preprocessor.theme
reads from book.toml
and Theme
dir. When preprocessor.theme
finds your css/js files are not consistent with what it computes, it'll cover everything concerned. (Of course, if they are consistent, no file will be rewritten.) The procedure holds back and forth, in the backyard ...
The point is that this tool, unlike the preprocessors aiming to deal with contents in md files and obliged to keep up with revision, produces theme files that are needless to check (compute and compare) as long as nothing concerned changes. Sadly, this tool are incapable of doing this kind of check, beacuse I haven't found a solution, causing whether to check is at the user's explicit option (see the following suggestions).
Since all theme configs are written into files under theme
dir or appended only once, mdbook build
will not cause repeating .
Therefore, if you don't modify the theme when mdbook watch
, run once mdbook build
and do one of the followings to avoid repeating:
-
set
turn-off = true
beneath[preprocessor.theme]
to let this tool do nothing (such as not comparing local files with computed ones), or equivalently set the shell env :export MDBOOK_preprocessor__theme__turn_off=true #export MDBOOK_output__html__additional_css="[]" # if the theme dir no longer exists, don't forget to tell mdbook about it #export MDBOOK_output__html__additional_js="[]" # if the theme dir no longer exists, don't forget to tell mdbook about it mdbook watch
and you can restore these values:
export MDBOOK_preprocessor__theme__turn_off=false #export MDBOOK_output__html__additional_css='["theme/pagetoc.css"]' # if you have set this empty, don't forget to fetch it now #export MDBOOK_output__html__additional_js='["theme/pagetoc.js"]' # if you have set this empty, don't forget to fetch it now mdbook watch
Remember a env variable always outstrips your configs counterpart in
book.toml
, so prefer to delete the env values to restore configs:unset MDBOOK_preprocessor__theme__turn_off MDBOOK_output__html__additional_css MDBOOK_output__html__additional_js
- comment the table header (i.e.
#[preprocessor.theme]
) to skip this preprocessor (turn-off = true
actually does not prevent running this preprocessor ); if you are certain that you will never need this tool to generate files agian, it's fine to delete the whole[preprocessor.theme]
table and keep thetheme
dir. - add
theme
in your.gitignore
file to skipmdbook watch
's check ontheme
dir: this is a simple but useful way if you don't mind thetheme
dir;mdbook build
will check thetheme
dir no matter whether it's in.gitignore
or not : )
Fisrt two suggestions also suits more-than-once mdbook build
in order to reduce/ban computation this tool produces during preprocess.
examples
Rust Book
[output.html]
-additional-css = ["ferris.css", "theme/2018-edition.css"]
-additional-js = ["ferris.js"]
+additional-css = ["ferris.css", "theme/2018-edition.css", "theme/pagetoc.css"]
+additional-js = ["ferris.js", "theme/pagetoc.js"]
+[preprocessor.theme]
+pagetoc = true
+sidebar-width = "280px"
+content-max-width = "75%"
+content-main-margin-left = "5%"
+content-main-margin-right = "5%"
+root-font-size = "80%"
+sidebar-font-size = "0.85em"
before : https://doc.rust-lang.org/book
after :
Rust Reference
[output.html]
-additional-css = ["theme/reference.css"]
+additional-css = ["theme/reference.css", "theme/pagetoc.css"]
+additional-js = ["theme/pagetoc.js"]
...
+[preprocessor.theme]
+pagetoc = true
+sidebar-width = "240px"
before : https://doc.rust-lang.org/nightly/reference
after :
Rust by Example
Change the code editor theme
+[preprocessor.theme]
+pagetoc = false
+sidebar-width = "290px"
+content-max-width = "85%"
+root-font-size = "75%"
+[output.html]
+[output.theme-ace]
+theme-white = "ambiance"
+theme-dark = "solarized_dark"
before : https://doc.rust-lang.org/stable/rust-by-example
after :
Others
Rust API Guidelines (Chinese Version): https://zjp-cn.github.io/api-guidelines
The Little Book of Rust Macros (Updated & Chinese Version): https://zjp-cn.github.io/tlborm