Customize the theme

You can customize the theme by adding custom CSS, using custom layouts, or modify existing templates.

On this page

For the methods listed on this page, it’s better to use traditional methods to style your templates. Extra files, aren’t processed by webpack, so you can’t use Tailwind’s @apply directive. See Modify the theme, if you want to modify the existing templates and use (almost) the full power of Tailwind.

Add or override styles

To add extra CSS files, use the html_css_files configuration value. To add extra JavaScript files, use the html_js_files configuration value.

For example, place additional styles in a file _static/custom.css and add the following options to your Sphinx configuration in conf.py:

python conf.py
html_static_path = ["_static"]
html_css_files = ["custom.css"]

If you want to override existing styles, you might have to add !important.

See also

CSS Specificity (MDN Web Docs)

Add additional page layouts

Sometimes, you want to add a custom page to your documentation, for example, a custom homepage for the documentation project. These pages often have a different layout than the documentation pages themselves. An example is the homepage of the Sphinx documentation.

To add additional page layouts to your Sphinx documentation:

  1. Create a directory in your Sphinx project, for example, _templates/ and add it to your Sphinx configuration:

    python File: conf.py
    templates_path = ["_templates"]

    See also

    templates_path

  2. Create a new layout file, for example, extra-layout.html:

    html+jinja File: extra-layout.html
    {% extends "layout.html" %}

{% block body %}
{% endblock %}

    This creates a rudimentary layout where the main text is inserted directly below the page header.

  3. To use this custom layout, you have two options:

    • If you write your Sphinx documentation in Markdown, see Override page layout per page.

    • If you Override page layouts globally, you can extend your custom layout. For example, you can override the page template and use the extra-layout template defined previously:

      html+jinja File: page.html
      {% extends "extra-layout.html" %}

{% block body %}
{{ body }}
{% endblock %}

      Now all pages in your documentation use your custom layout.

Override page layouts globally

If you want to override a template for all pages of your documentation, place a template file in a custom _templates directory, as described in Add additional page layouts.

To override an existing template, you need to name it the same. For example, to use a custom header on all pages:

  1. Create a file header.html in the _templates directory:

    html+jinja File: header.html
    HEADER

    This shows the word HEADER on every page of your documentation.

The main templates you may want to override include:

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 without navigation sidebar. This template is used, when the theme option show_nav is set to False, or when you set layout: "without-sidebar" in the front matter 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 overall 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/ on GitHub.

Override page layout per page

Caution

This section only applies if you use the myst-parser for writing Sphinx documentation in Markdown.

The theme has two page layouts. The default layout shows a sidebar with all navigation links on the left side.

If you want to override the layout on one page, you can use the layout option in the YAML front matter.

For example, the About page uses a layout without a sidebar:

markdown
---
layout: "without-sidebar"
---

# About

...