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"]

See also

templates_path

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.

See also

Templating

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 %}

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>

See also

Add custom templates

Add custom page layouts

You can create custom layouts and choose different page layouts for different pages.

To create a custom layout, create a new file _templates/custom-layout.html:

File: _templates/custom-layout.html
<html>
   <body>{{ body }}</body>
</html>

Then, select the layout in your document with the layout option.

---
layout: "custom-layout"
---

:layout: custom-layout

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. The page template extends the layout with-sidebar or without-sidebar depending on the context.

without-sidebar.html

Template for a page without navigation sidebar. This template is used when the option show_nav is set to False, or when you set layout: "without-sidebar" in the frontmatter of your Markdown document. This template extends the main template layout.

with-sidebar.html

Template with navigation sidebar on the left. This is the default template for all documentation pages. It extends from the main template layout.

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.