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
:
If you want to override existing styles, you might have to add !important
.
See also
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:
: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:
Create a directory in your Sphinx project, for example,
_templates/
and add it to your Sphinx configuration:See also
Create a new layout file, for example,
extra-layout.html
:This creates a rudimentary layout where the main text is inserted directly below the page header.
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 theextra-layout
template:{% 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:
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. Thepage
template extends the layoutwith-sidebar
orwithout-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 toFalse
, or when you setlayout: "without-sidebar"
in the front matter of your Markdown document. This template extends the main templatelayout
.
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:
---
layout: "without-sidebar"
---
# About
...