2015-08-05 20:36:21 +02:00
|
|
|
# Theme
|
|
|
|
|
|
2018-08-02 21:34:26 -05:00
|
|
|
The default renderer uses a [handlebars](http://handlebarsjs.com/) template to
|
|
|
|
|
render your markdown files and comes with a default theme included in the mdBook
|
|
|
|
|
binary.
|
2015-08-05 20:36:21 +02:00
|
|
|
|
2018-08-02 21:34:26 -05:00
|
|
|
The theme is totally customizable, you can selectively replace every file from
|
|
|
|
|
the theme by your own by adding a `theme` directory next to `src` folder in your
|
|
|
|
|
project root. Create a new file with the name of the file you want to override
|
2015-08-05 20:36:21 +02:00
|
|
|
and now that file will be used instead of the default file.
|
|
|
|
|
|
2015-12-30 15:04:24 +01:00
|
|
|
Here are the files you can override:
|
2015-08-05 20:36:21 +02:00
|
|
|
|
2020-05-10 09:31:30 +02:00
|
|
|
- **_index.hbs_** is the handlebars template.
|
2020-05-10 08:42:45 -07:00
|
|
|
- **_head.hbs_** is appended to the HTML `<head>` section.
|
|
|
|
|
- **_header.hbs_** content is appended on top of every book page.
|
2021-01-06 16:56:20 -08:00
|
|
|
- **_css/_** contains the CSS files for styling the book.
|
|
|
|
|
- **_css/chrome.css_** is for UI elements.
|
|
|
|
|
- **_css/general.css_** is the base styles.
|
|
|
|
|
- **_css/print.css_** is the style for printer output.
|
|
|
|
|
- **_css/variables.css_** contains variables used in other CSS files.
|
2020-05-10 09:31:30 +02:00
|
|
|
- **_book.js_** is mostly used to add client side functionality, like hiding /
|
2018-08-02 21:34:26 -05:00
|
|
|
un-hiding the sidebar, changing the theme, ...
|
2020-05-10 09:31:30 +02:00
|
|
|
- **_highlight.js_** is the JavaScript that is used to highlight code snippets,
|
|
|
|
|
you should not need to modify this.
|
2020-05-10 08:42:45 -07:00
|
|
|
- **_highlight.css_** is the theme used for the code highlighting.
|
2020-05-17 17:34:03 -07:00
|
|
|
- **_favicon.svg_** and **_favicon.png_** the favicon that will be used. The SVG
|
|
|
|
|
version is used by [newer browsers].
|
2015-08-05 20:36:21 +02:00
|
|
|
|
2018-08-02 21:34:26 -05:00
|
|
|
Generally, when you want to tweak the theme, you don't need to override all the
|
|
|
|
|
files. If you only need changes in the stylesheet, there is no point in
|
|
|
|
|
overriding all the other files. Because custom files take precedence over
|
|
|
|
|
built-in ones, they will not get updated with new fixes / features.
|
2015-12-30 15:04:24 +01:00
|
|
|
|
2018-08-02 21:34:26 -05:00
|
|
|
**Note:** When you override a file, it is possible that you break some
|
|
|
|
|
functionality. Therefore I recommend to use the file from the default theme as
|
|
|
|
|
template and only add / modify what you need. You can copy the default theme
|
2021-12-06 08:06:07 -08:00
|
|
|
into your source directory automatically by using `mdbook init --theme` and just
|
2018-08-02 21:34:26 -05:00
|
|
|
remove the files you don't want to override.
|
2020-04-21 10:18:44 -07:00
|
|
|
|
2021-12-19 20:26:37 -08:00
|
|
|
`mdbook init --theme` will not create every file listed above.
|
|
|
|
|
Some files, such as `head.hbs`, do not have built-in equivalents.
|
|
|
|
|
Just create the file if you need it.
|
|
|
|
|
|
2020-04-21 10:18:44 -07:00
|
|
|
If you completely replace all built-in themes, be sure to also set
|
|
|
|
|
[`output.html.preferred-dark-theme`] in the config, which defaults to the
|
|
|
|
|
built-in `navy` theme.
|
|
|
|
|
|
2021-05-23 17:59:52 -07:00
|
|
|
[`output.html.preferred-dark-theme`]: ../configuration/renderers.md#html-renderer-options
|
2020-05-17 17:34:03 -07:00
|
|
|
[newer browsers]: https://caniuse.com/#feat=link-icon-svg
|
