Customize the theme

Customize the Awesome Theme by adding custom CSS, using custom layouts, or modify existing templates.

For the methods listed on this page, it’s better to use traditional classes 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 Tailwind CSS.

Add or override styles

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

For example, place custom 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)

Override CSS custom properties

You can override these custom properties (variables):

--color-brand

The color for hover, focus, and highlight styles

--color-links

The color for links in the main text.

To override custom properties, add a custom CSS file with new values. For example, change the link color to green:

CSS
:root {
  --color-links: green;
}

Add 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 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 per-page layout.

    • If you don’t write your Sphinx documentation in Markdown, you can Override page layouts globally.

      For example, you can override the page template and use the extra-layout template:

      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. See Add page layouts for more information.

To override an existing template, you need to name it the same as the original. For example, to use a custom header on all pages, 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 can override 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 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 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/.

Override per-page layout

Caution

You can only select per-page layouts if you write your documentation in Markdown using the myst-parser.

The Awesome 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

...