How do I override a template on readthedocs?

Question

I recently added sphinx documentation for blowdrycss to readthedocs.

I want to override the layout.html template on readthedocs. My current template override works fine on localhost, but not on readthedocs. The project uses the Alabaster theme which extends the basic theme.

Project directory structure can be seen here

The relevant parts are:

blowdrycss/
    docs/
        _templates/
            layout.html

        conf.py

Template setting in conf.py:

templates_path = ['_templates']

Contents of layout.html:

{% extends '!layout.html' %}


{% block sidebarsearch %}
    {{ super() }}
    <a href="https://flattr.com/submit/auto?user_id=nueverest&url=https%3A%2F%2Fgithub.com%2Fnueverest%2Fblowdrycss" target="_blank"><img src="http://button.flattr.com/flattr-badge-large.png" alt="Flattr this" title="Flattr this" border="0"></a>
{% endblock %}


{% block footer %}
    <div class="footer" style="text-align: center;">
        <a href="https://flattr.com/submit/auto?user_id=nueverest&url=https%3A%2F%2Fgithub.com%2Fnueverest%2Fblowdrycss" target="_blank"><img src="http://button.flattr.com/flattr-badge-large.png" alt="Flattr this" title="Flattr this" border="0"></a>
    </div>
    {{ super() }}
{% endblock %}

How do I override the layout.html template on readthedocs?

Update I've also tried:

The relevant parts are:

blowdrycss/
    docs/
        custom_templates/
            layout.html

        conf.py

Template setting in conf.py:

templates_path = ['custom_templates']

*_templates* is the default one, can you try with another one? — Ciro Pedrini, Dec 01 '15 at 15:19
i created a new directory `custom_templates` and place `layout.html` inside readthedocs still does not recognize it. — nu everest, Dec 02 '15 at 12:20
It's actually documented on read-the-docs http://read-the-docs.readthedocs.org/en/latest/theme.html — Wolph, Dec 11 '15 at 13:31
@nueverest: I was referring to this bit: "By default, Read the Docs will use its own custom sphinx theme unless you set one yourself in your `conf.py` file." — Wolph, Dec 11 '15 at 13:42

score 3 · Accepted Answer · answered Dec 11 '15 at 13:35

3

While readthedocs doesn't support the templates_path straight away, you can use a custom theme with templates inside of it. http://sphinx-doc.org/theming.html

Simply create a new theme directory and add this to your conf.py:

html_theme = 'your_theme'
html_theme_path = ['.']

You can see an example in one of my projects:

answered Dec 11 '15 at 13:35

Wolph

78,177
11
137
148

I used `html_theme_path = ['custom_themes', ]` copied and pasted the alabaster theme into it renamed it to `custom_alabaster` and edited the template files. Thanks for pointing me in the right direction. – nu everest Dec 11 '15 at 13:53

score 1 · Answer 2 · answered Mar 29 '19 at 23:00

1

Looks like now ReadTheDocs should support templates_path: https://docs.readthedocs.io/en/stable/guides/remove-edit-buttons.html?highlight=templates_path#remove-links-from-top-right-corner

answered Mar 29 '19 at 23:00

MarSoft

3,555
1
33
38

How do I override a template on readthedocs?

2 Answers2