Skip to main content

Custom Styles

The easiest way to customize the appearance of your web book is by adding styles to index.css.

Using template.extend_render to overwrite index.css​

Create a template called yourmodid.css.jinja:

doc/src/hexdoc_yourmodid/_templates/yourmodid.css.jinja
{% include "index.css.jinja" %}

body {
  background-color: red;
}

The include tag (Jinja docs) inserts the contents of the template index.css.jinja from the plugin hexdoc. This is important if you want to keep the default hexdoc CSS styles.

tip

Any filename can be used here, but we recommend using your modid to help avoid conflicts with other plugins.

Then, add the following to your hexdoc.toml file:

doc/hexdoc.toml
[template.extend_render]
"index.css" = "yourmodid:yourmodid.css.jinja"

This tells hexdoc to create a file called index.css using the template yourmodid.css.jinja from the plugin yourmodid.

note

This section of the hexdoc.toml file is not exported, so it won't affect any other plugins that depend on your book.

Directly extending index.css.jinja​

Create a template called index.css.jinja:

doc/src/hexdoc_yourmodid/_templates/index.css.jinja
{% include "hexdoc:index.css.jinja" %}

body {
  background-color: red;
}
Hex Addons

If you're creating a book for a Hex Casting addon, use hexcasting:index.css.jinja instead of hexdoc:index.css.jinja.

warning

There are two problems with this approach:

  • You must specify a namespace (the hexdoc: part) to prevent the template from recursively rendering itself. This can be error-prone if you pick the wrong namespace.
    • For example, hexdoc-hexcasting adds styles to index.css, which is why the above note is necessary.
  • Your custom styles might interfere with other hexdoc plugins if they add your modid to template.include.

Both of these problems can be avoided by using the template.extend_render approach.