Add custom templates

Add, extend, or overrde Jinja2 templates.

Create a directory in your Sphinx project and add it to your Sphinx configuration:

File: conf.py

templates_path = ["_templates"]

Extend templates

To extend existing templates, create a new file with the same name and add the following code:

{% extends "!TEMPLATE" %}

{{ super() }}

Replace TEMPLATE with the name of the template you want to extend. The exclamation mark lets Sphinx load the parent template from the HTML theme. Call super() to render the original content of the parent template.

Extend template blocks

To add code, you can extend the page template and override the template blocks:

extrahead: Adds your template code before the closing </head> tag. This is useful to add custom styles or JavaScript code.
body_before: Adds content to the top of the page.
body_after: Adds content to the bottom of the page.

File: page.html

{% extends "!page.html" %}

{{ super() }}

{% block extrahead %}
{# Included before the closing </head> tag #}
{% endblock %}

{% block extrabody %}
{# Included after the main content, before the <footer> #}
{% endblock %}

Example: hide the right sidebar

Extending the base templates is a powerful technique to achieve custom layouts that integrate well with the existing theme.

For example, you can change the layout to conditionally show or hide the on-page table of contents in the right sidebar. To achieve this, you need to update 2 templates:

layout.html. You need to update this template to extend the body to the full width.
page.html. You need to update this template to conditionally include the table of contents.

Add a templates folder to your docs.

Create a new file _templates/layout.html with the following content:

File: layout.html

{%- extends "!layout.html" %}

{{ super() }}

{%- block main %}
{%- if meta is defined and meta is not none and 'notoc' in meta %}
  <main class="relative py-6">
{%- else %}
  <main class="relative py-6 lg:gap-10 lg:py-8 xl:grid xl:grid-cols-[1fr_300px]">
{%- endif %}
{%- block body %}{%- endblock %}
</main>
{%- endblock main %}

This change leads to different styles being applied to the main element, depending on whether the document has a :notoc: field or not.

Create a new file _templates/page.html with the following content:

File: page.html

{%- extends "!page.html" -%}

{{ super() }}

{%- block on_page_toc %}
{%- if (meta is not defined or meta is none or "notoc" not in meta) and display_toc %}
{%- include "toc.html" %}
{%- endif %}
{% endblock %}

This change hides the sidebar if the document has a :notoc: option.

Include the :notoc: option in your documents.
```
:notoc: true

...
```

For an example, see Page without right sidebar.

Add custom templates

You can define completely custom layouts and templates for your pages.

For example, to create your own custom footer template, create a file _templates/footer.html with the following content:

File: _tempates/footer.html

{# A custom footer template that doesn't inherit from the parent. #}

<div style="background-color: red;">
   Your custom footer.
</div>

Available templates

The main templates you can extend are:

header.html

Template for the header.

footer.html

Template for the footer.

page.html

Template for the body of the page.

This page must contain the {{ body }} expression to render the contents of your documentation. This template extends the template layout.html.

layout.html

Main template defining the structure of the page, including the HTML <head> with all imported CSS and JavaScript files.

For more information, see the available templates in the directory src/sphinxawesome_theme.