Using custom Sphinx templates on Read the Docs#

I wanted to make a small customization to one of my documentation templates on Read the Docs.

It turns out you can over-ride the default templates by creating a _templates directory in your documentation folder and dropping new files into it - no additional configuration changes required.

I wanted to customize a small part of the layout.html template. The original template is here: https://github.com/simonw/sphinx_rtd_theme/blob/master/sphinx_rtd_theme/layout.html

It has named blocks in it, which means I can over-ride just the specific named block I’m interested in. I created my own {% block sidebartitle %} block, then saved it in a file in _templates/layout.html.

To inherit from the default layout template, I used {% extends "!layout.html" %} - note the ! there which causes it to use the default template (without that character the build script throws an infinite recursion error).

Here’s the layout.html template I used:

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

3
{% block sidebartitle %}
4

5
<a href="https://datasette.io/">
6
  <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="{{ _('Logo') }}"/>
7
</a>
8

9
{% if theme_display_version %}
10
  {%- set nav_version = version %}
11
  {% if READTHEDOCS and current_version %}
12
    {%- set nav_version = current_version %}
13
  {% endif %}
14
  {% if nav_version %}
15
    <div class="version">
16
      {{ nav_version }}
17
    </div>
18
  {% endif %}
19
{% endif %}
20

21
{% include "searchbox.html" %}
22

23
{% endblock %}

See https://github.com/simonw/datasette/tree/main/docs for the full documentation layout - the only thing I had to change to get this custom template was adding the new _templates folder and the layout.html file.