2015-08-05 20:36:21 +02:00
# index.hbs
2015-08-05 18:28:59 +02:00
2018-08-02 21:34:26 -05:00
`index.hbs` is the handlebars template that is used to render the book. The
markdown files are processed to html and then injected in that template.
2015-08-05 18:28:59 +02:00
2018-08-02 21:34:26 -05:00
If you want to change the layout or style of your book, chances are that you
will have to modify this template a little bit. Here is what you need to know.
2015-08-05 18:28:59 +02:00
2015-08-05 20:36:21 +02:00
## Data
2015-08-05 18:28:59 +02:00
2018-08-02 21:34:26 -05:00
A lot of data is exposed to the handlebars template with the "context". In the
handlebars template you can access this information by using
2015-08-05 18:28:59 +02:00
```handlebars
{{name_of_property}}
```
Here is a list of the properties that are exposed:
2019-05-30 11:53:49 +09:00
- ***language*** Language of the book in the form `en` , as specified in `book.toml` (if not specified, defaults to `en` ). To use in < code
2024-05-13 13:43:00 -07:00
class="language-html">\<html lang=\"{{ language }}\"></ code > for example.
2020-12-22 22:36:58 +01:00
- ***title*** Title used for the current page. This is identical to `{{ chapter_title }} - {{ book_title }}` unless `book_title` is not set in which case it just defaults to the `chapter_title` .
2020-07-16 16:43:46 +02:00
- ***book_title*** Title of the book, as specified in `book.toml`
2016-12-31 10:34:15 -08:00
- ***chapter_title*** Title of the current chapter, as listed in `SUMMARY.md`
2015-08-05 18:28:59 +02:00
2018-08-02 21:34:26 -05:00
- ***path*** Relative path to the original markdown file from the source
directory
2015-08-05 18:28:59 +02:00
- ***content*** This is the rendered markdown.
2018-08-02 21:34:26 -05:00
- ***path_to_root*** This is a path containing exclusively `../` 's that points
to the root of the book from the current file. Since the original directory
structure is maintained, it is useful to prepend relative links with this
`path_to_root` .
2015-08-05 18:28:59 +02:00
- ***chapters*** Is an array of dictionaries of the form
```json
{"section": "1.2.1", "name": "name of this chapter", "path": "dir/markdown.md"}
```
2018-08-02 21:34:26 -05:00
containing all the chapters of the book. It is used for example to construct
the table of contents (sidebar).
2015-08-05 18:28:59 +02:00
2015-08-05 20:36:21 +02:00
## Handlebars Helpers
2015-08-05 18:28:59 +02:00
2018-08-02 21:34:26 -05:00
In addition to the properties you can access, there are some handlebars helpers
at your disposal.
2015-08-05 18:28:59 +02:00
2018-08-02 16:52:54 -05:00
### 1. toc
2015-08-05 18:28:59 +02:00
2019-05-18 15:05:57 -07:00
The toc helper is used like this
```handlebars
{{#toc }}{{/toc}}
```
and outputs something that looks like this, depending on the structure of your
book
```html
< ul class = "chapter" >
< li > < a href = "link/to/file.html" > Some chapter< / a > < / li >
< li >
< ul class = "section" >
< li > < a href = "link/to/other_file.html" > Some other Chapter< / a > < / li >
< / ul >
< / li >
< / ul >
```
If you would like to make a toc with another structure, you have access to the
chapters property containing all the data. The only limitation at the moment
is that you would have to do it with JavaScript instead of with a handlebars
helper.
```html
< script >
var chapters = {{chapters}};
// Processing here
< / script >
```
2015-08-05 18:28:59 +02:00
2018-08-02 16:52:54 -05:00
### 2. previous / next
2015-08-05 18:28:59 +02:00
2024-02-20 15:29:30 -05:00
The previous and next helpers expose a `link` and `title` property to the
2019-05-18 15:05:57 -07:00
previous and next chapters.
2015-08-05 18:28:59 +02:00
2019-05-18 15:05:57 -07:00
They are used like this
2015-08-05 18:28:59 +02:00
2019-05-18 15:05:57 -07:00
```handlebars
{{#previous }}
< a href = "{{link}}" class = "nav-chapters previous" >
2024-02-20 15:29:30 -05:00
< i class = "fa fa-angle-left" > < / i > {{title}}
2019-05-18 15:05:57 -07:00
< / a >
{{/previous}}
```
2015-08-05 18:28:59 +02:00
2019-05-18 15:05:57 -07:00
The inner html will only be rendered if the previous / next chapter exists.
Of course the inner html can be changed to your liking.
2015-08-05 18:28:59 +02:00
------
2018-08-02 21:34:26 -05:00
*If you would like other properties or helpers exposed, please [create a new
2019-10-29 08:04:16 -05:00
issue](https://github.com/rust-lang/mdBook/issues)*
2025-02-13 10:04:21 -07:00
### 3. resource
The path to a static file.
It implicitly includes `path_to_root` ,
and accounts for files that are renamed with a hash in their filename.
```handlebars
< link rel = "stylesheet" href = "{{ resource " css / chrome . css " } } " >
```
