mdBook/book-example/src/format/theme/README.md

# Theme

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.

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
and now that file will be used instead of the default file.

Here are the files you can override:

- ***index.hbs*** is the handlebars template.
- ***book.css*** is the style used in the output. If you want to change the 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.
- ***book.js*** is mostly used to add client side functionality, like hiding / un-hiding the sidebar, changing the theme, ...
- ***highlight.js*** is the JavaScript that is used to highlight code snippets, you should not need to modify this.  
- ***highlight.css*** is the theme used for the code highlighting
- ***favicon.png*** the favicon that will be used

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.

**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.
Added some chapters for the documentation #30 + tweaked the syntax highlighting theme 2015-08-06 02:36:21 +08:00			`# Theme`

Update documentation, Closes #80 2015-12-30 22:04:24 +08:00			`The default renderer uses a [handlebars](http://handlebarsjs.com/) template to render your markdown files and comes with a default theme`
Added some chapters for the documentation #30 + tweaked the syntax highlighting theme 2015-08-06 02:36:21 +08:00			`included in the mdBook binary.`

Update documentation, Closes #80 2015-12-30 22:04:24 +08:00			`The theme is totally customizable, you can selectively replace every file from the theme by your own by adding a`
Now changes to `theme` directory trigger rebuild for `mdbook serve` As `theme` dir is no longer under `src`. Updates to "theme" did not trigger book rebuild. Also fixed misleading docs about `theme` dir being located in `src` 2017-06-01 19:11:39 +08:00			`theme` directory next to `src` folder in your project root. Create a new file with the name of the file you want to override
Added some chapters for the documentation #30 + tweaked the syntax highlighting theme 2015-08-06 02:36:21 +08:00			`and now that file will be used instead of the default file.`

Update documentation, Closes #80 2015-12-30 22:04:24 +08:00			`Here are the files you can override:`
Added some chapters for the documentation #30 + tweaked the syntax highlighting theme 2015-08-06 02:36:21 +08:00
			`- *index.hbs* is the handlebars template.`
			- *book.css* is the style used in the output. If you want to change the 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.
update docs 2015-09-25 04:19:14 +08:00			`- *book.js* is mostly used to add client side functionality, like hiding / un-hiding the sidebar, changing the theme, ...`
			`- *highlight.js* is the JavaScript that is used to highlight code snippets, you should not need to modify this.`
			`- *highlight.css* is the theme used for the code highlighting`
Add an entry about the favicon in the docs 2016-02-23 01:01:36 +08:00			`- *favicon.png* the favicon that will be used`
Added some chapters for the documentation #30 + tweaked the syntax highlighting theme 2015-08-06 02:36:21 +08:00
Update documentation, Closes #80 2015-12-30 22:04:24 +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.`

			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.