Configuration options to personalize your site.


There are two methods to alter the theme. The first, and simplest, uses the options exposed through html_theme_options in This site’s options are:

 90html_theme = "openff_sphinx_theme"
 92# Add any paths that contain custom static files (such as style sheets) here,
 93# relative to this directory. They are copied after the builtin static files,
 94# so a file named 'default.css' will overwrite the builtin 'default.css'.
 95html_static_path = ["_static"]
 97# If HTML theme settings isn't lines 90-160, remember to change customization.rst
 99# -- HTML theme settings ------------------------------------------------
100html_show_sourcelink = True
101html_sidebars = {
102    "**": ["globaltoc.html", "localtoc.html", "searchbox.html"],
103    "customization": ["globaltoc.html", "searchbox.html"],
104    "subpage/second-subsubpage": ["globaltoc.html", "searchbox.html"],
107# material theme options (see theme.conf for more information)
108html_theme_options = {
109    "base_url": "",
110    "repo_url": "",
111    "repo_name": "openff-sphinx-theme",
112    "html_minify": False,
113    "css_minify": False,
114    "globaltoc_depth": 3,
115    "globaltoc_include_local": True,
116    "color_accent": "openff-toolkit-blue",
117    "html_hyphenate_and_justify": True,
118    "nav_links": [
119        {
120            "href": "",
121            "internal": False,
122            "title": "Material for MkDocs",
123        },
124        {
125            "href": "",
126            "internal": False,
127            "title": "Material for Sphinx",
128        },
129        {
130            "href": "",
131            "internal": False,
132            "title": "The OpenFF Initiative",
133        },
134        {
135            "href": "",
136            "internal": False,
137            "title": "openff-sphinx-theme on GitHub",
138        },
139    ],
140    "heroes": {
141        "index": "A responsive Material Design theme for Sphinx sites.",
142        "customization": "Configuration options to personalize your site.",
143    },
144    "socials": [
145        {
146            "href": "",
147            "title": "OpenFF on Zenodo",
148            "icon_classes": "ai ai-zenodo",
149        },
150        {
151            "href": "",
152            "title": "OpenFF on YouTube",
153            "icon_classes": "fab fa-youtube",
154        },
155        {
156            "href": "",
157            "title": "OpenFF on GitHub",
158            "icon_classes": "fab fa-github",
159        },
160        {

Many of these settings are provided in this site as examples; for a minimalistic example, see OpenFF Sphinx theme Quickstart.

Configuration Options


Set to enable google analytics.


Set the repo url for the link to appear.


The name of the repo. It must be set if repo_url is set.


Must be one of github, gitlab or bitbucket.


The maximum depth of the global TOC; set it to -1 to allow unlimited depth.


If true, TOC entries that are not ancestors of the current page are collapsed.


If true, the global TOC tree will also contain hidden entries.


If true, the global TOC tree will include the current page’s localtoc entries if the localtoc is not rendered on the page


Accent color. Options are openff-blue, openff-toolkit-blue, openff-yellow, openff-orange, aquamarine, lilac, amaranth, grape, violet, pink, pale-green, green, crimson, eggplant, turquoise, or any valid CSS color.


If true, hyphenate and justify prose content. Doesn’t affect API docs. Quality of hyphenation will vary from browser to browser.


Minify pages after creation using htmlmin.


Prettify pages. Just for debugging, this will change how the page is rendered.


Minify css files found in the output directory.


Include the master document at the top of the page in the breadcrumb bar.


A list of dictionaries where each has three keys:

  • href: The URL or pagename (str)

  • title: The title to appear (str)

  • internal: Flag indicating to use pathto to find the page. Set to False for external content. (bool)


A dict[str,str] where the key is a pagename and the value is the text to display in the page’s hero location.


list[dict[str, str]] of social media links. Dicts have three keys: "href", "icon_classes", and optionally "title". Icon classes should be from Academicons or Font Awesome 5. If not specified, defaults to a set of links appropriate for an OpenFF Initiative project.

Customizing the layout

You can customize the theme by overriding Jinja template blocks. For example, ‘layout.html’ contains several blocks that can be overridden or extended.

Place a ‘layout.html’ file in your project’s ‘/_templates’ directory.

mkdir source/_templates
touch source/_templates/layout.html

Then, configure your ‘’:

templates_path = ['_templates']

Finally, edit your override file source/_templates/layout.html:

{# Import the theme's layout. #}
{% extends '!layout.html' %}

{%- block extrahead %}
{# Add custom things to the head HTML tag #}
{# Call the parent block #}
{{ super() }}
{%- endblock %}

New Blocks

The theme has a small number of new blocks to simplify some types of customization:


Previous and next in the footer.


Block that contains the icon font. You should probably call {{ super() }} at the end of the block to include the default icon fonts as well. (Font Awesome and Academicons)