A preprocessor and a backend to config theme for mdbook, especially making a pagetoc on the right and setting full color themes from the offical ace editor.
mdbook-theme
This preprocessor does a little more work to integrate mdBook-pagetoc (pure js/css/hbs files) with mdBook which currently lacks a pagetoc (to jump within titles of the opened page) .
And it makes some modification of css easily done just via a few lines in book.toml ( fine with or without pagetoc
), for example, common layout, fontsize and color settings.
- If you just want a pagetoc on the right, use this in
book.timl
:
[]
= true
[]
= ["theme/pagetoc.css"]
= ["theme/pagetoc.js"]
- If you want to config more by yourself, refer to the fully supported configs as listed below:
[]
# enable pagetoc (toc on the left)
= true
# some variables related (defined in theme/css/variables.css)
# `content-max-width` + `pagetoc-width` = 95% seems the best
= "13%"
= "82%"
= "14.5px"
= "300px"
= "40px" # memu-bar = the bar on the top
= "15px"
= "98%"
# layout
= "0 10px"
= "2%"
= "2%"
= "auto"
= "auto"
= "2em"
= "1.5em"
# modify some fontsizes
= "70%" # control the main font-size
= "1.5rem"
= "0.9em"
= "1em" # sidebar = toc on the left
# modify some colors under ayu/coal/light/navy/rust theme
= "#ffb454"
= "#F42C4C"
= "#ffb454"
= "#F42C4C"
= "#1f1fff"
= "#1f1fff"
# if true, never read and touch the files in theme dir
= false
# If you set `pagetoc = true`, you need to set the following as well:
[]
= "theme" # this is the default if not explicitly set
= ["theme/pagetoc.css"] # This tool will produce it!
= ["theme/pagetoc.js"] # This tool will produce it!
You are informed that this preprocessor can be utterly replaced by simply modifying files involved.
mdbook-theme-ace
This backend mainly deals with the rendered theme files that may not be handled during preprocess, specifically to modify the js/css of the ace editor.
# here is a must to load ace editor in mdbook
[]
[]
= true
[]
= "dawn"
= "tomorrow_night"
= true
supported the official ace theme names :
ambiance | chaos | chrome | clouds | clouds_midnight | cobalt |
crimson_editor | dawn | dracula | dreamweaver | eclipse | github |
gob | gruvbox | idle_fingers | iplastic | katzenmilch | kr_theme |
kuroir | merbivore | merbivore_soft | mono_industrial | monokai | nord_dark |
one_dark | pastel_on_dark | solarized_dark | solarized_light | sqlserver | terminal |
textmate | tomorrow | tomorrow_night_blue | tomorrow_night_bright | tomorrow_night |
tomorrow_night_eighties | twilight | vibrant_ink | xcode |
Note: for simplicity, this tool just directly modify the cssText
in theme-dawn.js and theme-tomorrow_night.js . That is to say, if you set theme-white = "xcode"
, you may find there is no theme-xcode.js ortheme-xcode.js in the build_dir .
You are allowed to provide the ace-dark.css
and ace-white.css
in the theme
dir which accords with output.html
table to shadow the default given by the official ace. And the theme-white/dark
configs beneath output.theme-ace
are ignored.
Besides, for convenience, if you provide a single ace.css
, both dark and white themes will use it! This is useful when you try the same ace config on both themes. But you're informed that ace-dark.css
or ace-white.css
is firstly used whenever there is ace.css
or not . For instance, the bundle of ace-white.css
and ace.css
actually works as the combination of ace-white.css
and ace-dark.css
; the bundle of ace-white.css
, ace-dark.css
and ace.css
actually works as the combination of ace-white.css
and ace-dark.css
.
In short, you can download a css file form ace theme , rename it ace.css
or ace-dark.css
/ ace-white.css
, do minor modification about colors and put it into the theme
dir.
below-build-dir = true
is the default to make output files in html
right below build_dir
in stead of build_dir/html
, and there is no build_dir/theme-post
automatically generated by mdbook. If you set below-build-dir = false
, there will be html
and theme-post
dirs under build_dir (usually book/
), and the theme-post
should be empty for now.
details about the preprocessor
when pagetoc = true
[]
= true
pagetoc css
Much appreciation for JorelAli's handy mdBook-pagetoc !
- automatically add pagetoc in
index.hbs
:
<!-- before in `index.hbs` │after in `index.hbs` -->
│
│
│ <!-- Page table of contents -->
│
│
{{{ content }}} │ {{{ content }}}
│
- automatically add
pagetoc.js
andpagetoc.css
files
css/variables.css
[]
= true
# variables
= "13%"
= "14.5px"
= "300px"
= "82%"
= "40px" # memu-bar = the bar on the top
= "15px"
= "98%"
:root variables |
default value |
---|---|
--sidebar-width | 300px |
--page-padding | 15px |
--content-max-width | 750px |
--menu-bar-height | 50px |
by using mdbook-theme
, you can particularly specify the pagetoc width and fontsize:
:root variables |
info | set pagetoc = true |
---|---|---|
--sidebar-width | default | 140px |
--page-padding | default | 15px |
--content-max-width | default | 82% |
--menu-bar-height | default | 40px |
--pagetoc-width | added | 13% |
--pagetoc-fontsize | added | 14.5px |
Besides, this tool automatically makes content width larger if max-width:1439px
(i.e. on the mobile device screen) when pagetoc = true
is set in book.toml.
{
}
}
layout
[]
= true
# layout
= "0 10px"
= "2%"
= "2%"
= "auto"
= "auto"
= "2em"
= "1.5em"
/* before in `css/general.css` │ after in `css/general.css` */
} │ }
} │ }
/* before in `css/chrome.css` │ after in `css/chrome.css` */
} │ }
│
} │ }
│
} │ }
set some fontsizes
To modify the fontsize in css/general.css
:
/* before in `css/general.css` │ after in `css/general.css` */
} │ }
│
} │ }
│
} │ }
and modify the fontsize of .sidebar
in css/chrome.css
,
/* before in `css/chrome.css` │ after in `css/chrome.css` */
} │ }
you can add *-font-size = "value"
in book.toml:
[]
= "70%"
= "1.5rem"
= "0.9em"
= "1em"
set some colors
--links
and --inline-code-color
in light
theme (in css/variables.css
) can be simply modified via this preprocessor.
These colors draws little attention to recognition for myself : )
[]
# you'are allowed to change the prefix within ayu/coal/light/navy/rust
= "#1f1fff"
= "#F42C4C"
if not set pagetoc = true
If a user did not set pagetoc = true
(or equivalently pagetoc = false
), Ready
will get en empty default, meaning this tool completely acts with user's configs.
The user can still set anything that only works with pagetoc's presence, though that setting will not work (and it will lie in css files).
More likely, a user may actually set pagetoc = "true"
, then Ready
will get a full default, meaning he/she don't have to set most of the configs.
Both circumstances are ready to go!
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. 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 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.
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.