Use custom HTML templates

If the default template in the Sphinx Stack doesn’t fully meet your needs – whether you want a unique layout, a custom header or footer, or a specialized sidebar for certain pages – you can create and use a custom template for your project.

This guide shows you how to extend or override the default templates in the Sphinx Stack to tailor the look and structure of your documentation.

Note

Base template customizations can be made to your documentation. However, they are not officially supported by the team maintaining the Spinx Stack. Use them at your own discretion.

Setup

First, create the docs/_templates directory; all your custom templates will need to be stored in this directory.

Then uncomment this line in docs/conf.py so your project will use local templates (where available):

conf.py
templates_path = ["_templates"]

In most cases, you will need to copy the default templates from the canonical-sphinx theme as a starting point and edit as needed.

See also

Sphinx uses the Jinja templating engine for its HTML templates; see the Jinja template syntax reference for more details.

Use custom template for all pages

Sphinx looks for a template called page.html as the entry point and main page template for documentation pages. To customize your project’s look and structure, check this file and determine which parts – such as the header, footer, or sidebars – need to be edited or overridden.

Here are some examples.

Remove on-page TOC

To remove the on-page TOC in the right sidebar, make a copy of page.html in the docs/_templates directory, and remove the applicable lines. This will apply to all pages.

page.html
{% block right_sidebar %}
<div class="toc-sticky toc-scroll">
   {% if not furo_hide_toc_orig %}
    <div class="toc-title-container">
      <span class="toc-title">
       {{ _("Contents") }}
      </span>
    </div>
    <div class="toc-tree-container">
      <div class="toc-tree">
        {{ toc }}
      </div>
    </div>
   {% endif %}
    {% if meta and ((meta.discourse and discourse_prefix) or meta.relatedlinks) %}
    <div class="relatedlinks-title-container">
      <span class="relatedlinks-title">

Use custom template for specific pages

If you want to use a custom template for specific pages in your project, you can do so by using conditional logic in page.html.

First, create the base template with your modifications (e.g. special-header.html, special-page.html) and place it in the docs/_templates directory.

Next, make a copy of page.html.

Partial template changes

To make partial changes (e.g. custom header) to specific pages, modify only the relevant parts of page.html where you want the custom layout or behavior to apply. For example, wrap the body block in a conditional statement so the custom header (e.g. special-header.html) applies only to the “how-to/custom-templates” and “how-to/build” page.

_templates/page.html
{% block body -%}
   {% if pagename in ["how-to/build", "how-to/custom-templates"] %}
       {% include "special-header.html" %}
   {% else %}
       {% include "header.html" %}
   {% endif %}
   {{ super() }}
{%- endblock body %}

Whole template changes

To make changes to the whole template (e.g. a custom layout for a landing page or marketing page), modify the extends statement in page.html to specify the pages that will use different templates. For example, the special-page.html template applies only to the “how-to/customise” and “how-to/diagrams-as-code” page.

_templates/page.html
{% if pagename in ["how-to/customise", "how-to/diagrams-as-code"] %}
    {% extends "special-page.html" %}
{% else %}
    {% extends "furo/page.html" %}
{% endif %}

Note

The pages “how-to/customise” and “how-to/diagrams-as-code” will use special-page.html as the base template, but all other blocks (e.g. footer, body, etc) will follow the default page.html.