2015-08-06 02:36:21 +08:00
|
|
|
# Theme
|
|
|
|
|
|
2018-08-03 10:34:26 +08: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-06 02:36:21 +08:00
|
|
|
|
2018-08-03 10:34:26 +08: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-06 02:36:21 +08:00
|
|
|
and now that file will be used instead of the default file.
|
|
|
|
|
|
2015-12-30 22:04:24 +08:00
|
|
|
Here are the files you can override:
|
2015-08-06 02:36:21 +08:00
|
|
|
|
2020-05-10 15:31:30 +08:00
|
|
|
- **_index.hbs_** is the handlebars template.
|
2020-05-10 23:42:45 +08:00
|
|
|
- **_head.hbs_** is appended to the HTML `<head>` section.
|
|
|
|
|
- **_header.hbs_** content is appended on top of every book page.
|
2020-05-10 15:31:30 +08:00
|
|
|
- **_book.css_** is the style used in the output. If you want to change the
|
2018-08-03 10:34:26 +08:00
|
|
|
design of your book, this is probably the file you want to modify. Sometimes
|
|
|
|
|
in conjunction with `index.hbs` when you want to radically change the layout.
|
2020-05-10 15:31:30 +08:00
|
|
|
- **_book.js_** is mostly used to add client side functionality, like hiding /
|
2018-08-03 10:34:26 +08:00
|
|
|
un-hiding the sidebar, changing the theme, ...
|
2020-05-10 15:31:30 +08:00
|
|
|
- **_highlight.js_** is the JavaScript that is used to highlight code snippets,
|
|
|
|
|
you should not need to modify this.
|
2020-05-10 23:42:45 +08:00
|
|
|
- **_highlight.css_** is the theme used for the code highlighting.
|
|
|
|
|
- **_favicon.png_** the favicon that will be used.
|
2015-08-06 02:36:21 +08:00
|
|
|
|
2018-08-03 10:34:26 +08: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 22:04:24 +08:00
|
|
|
|
2018-08-03 10:34:26 +08: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
|
|
|
|
|
into your source directory automatically by using `mdbook init --theme` just
|
|
|
|
|
remove the files you don't want to override.
|
