> Fetch the complete documentation index at: https://sphinxawesome.xyz/llms.txt
> Use this file to discover available pages before exploring further.

<a id="sec-add-custom-templates"></a>

# Add custom templates

Add, extend, or overrde Jinja2 templates.

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

```python
templates_path = ["_templates"]
```

#### SEE ALSO
[`templates_path`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-templates_path)

<!-- This file is meant to be included in `add-custom-templates`. The heading must be an `h3` to match the structure. -->

<a id="sec-extend-templates"></a>

## Extend templates

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

```html+jinja
{% 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](https://www.sphinx-doc.org/en/master/development/html_themes/templating.html)

## Extend template blocks

To add code, you can [extend the page template](#sec-extend-templates) 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.

```html+jinja
{% extends "!page.html" %}

{{ super() }}

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

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

<a id="sec-hide-right-sidebar"></a>

## 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.

1. [Add a templates folder to your docs](#sec-add-custom-templates).
2. Create a new file `_templates/layout.html` with the following content:
   ```html+django
   {%- 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.
3. Create a new file `_templates/page.html` with the following content:
   ```html+django
   {%- 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.
4. Include the `:notoc:` option in your documents.
   ```reStructuredText
   :notoc: true

   ...
   ```

For an example, see [Page without right sidebar](../../../demo/notoc/index.html.md).

<a id="sec-left-sidebar-depth"></a>

## Example: Adjust the navigation depth in the left sidebar

By default, the left sidebar facilitates navigation between pages. The right sidebar supports navigation between sections on the same page.

If that’s not what you want, you can increase the *depth* of the left sidebar. To do this, override the template for the left sidebar.

1. [Add a templates folder to your docs](#sec-add-custom-templates).
2. Create a new file `_templates/sidebar_toc.html` with the following content:
   ```html+django
   <nav class="table w-full min-w-full my-6 lg:my-8">
     {{ toctree(collapse=false) }}
   </nav>
   ```

   The default template uses the `titles_only` option, which makes the sidebar only include page titles. If you omit this option, more headings are included.

   #### SEE ALSO
   [toctree (templating)](https://www.sphinx-doc.org/en/master/development/html_themes/templating.html#toctree)

## 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:

```html+jinja
{# 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](#sec-add-custom-templates)

## 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.
  <br/>
  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](https://github.com/kai687/sphinxawesome-theme/tree/main/src/sphinxawesome_theme).
