Custom Theme

@gitbook-ng/gitbook can be easily themed. Books use the theme-default theme by default.

Caution: Custom theme can block some plugins from working correctly.

Structure of a theme

A theme is a plugin containing templates and assets. Overriding any individual template is optional, since themes always extend the default theme.

Extend/Customize theme in a book

Authors can extend the templates of a theme directly from their book's source (without creating an external theme). Templates will be resolved in the _layouts folder of the book first, then in the installed plugins/themes.

.
├── SUMMARY.md
├── _layouts
│   └── website
│       └── page.html
├── book.json
...

Extend instead of Forking

When you want to make your theme changes available to multiple books, instead of forking the default theme, you can extend it using the templating syntax:

{% extends template.self %}

{% block head %}
    {{ super() }}
    <script>
      // Your script here...
    </script>
{% endblock %}

{% block body %}
    ... This will be added to the beginning of "body" block

    {{ super() }}

    ... This will be added to the end of "body" block
{% endblock %}

Take a look at the API theme for a more complete example.

Publish a theme

Themes are published as plugins (see related docs) with a theme- prefix. For example the theme awesome will be loaded from the theme-awesome plugin, and then from the gitbook-plugin-theme-awesome NPM package.