Customization

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

html_theme = "openff_sphinx_theme"

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named 'default.css' will overwrite the builtin 'default.css'.
html_static_path = ["_static"]

# If HTML theme settings isn't lines 90-160, remember to change customization.rst

# -- HTML theme settings ------------------------------------------------
html_show_sourcelink = True
html_sidebars = {
    "**": ["globaltoc.html", "localtoc.html", "searchbox.html"],
    "customization": ["globaltoc.html", "searchbox.html"],
    "subpage/second-subsubpage": ["globaltoc.html", "searchbox.html"],
}

# material theme options (see theme.conf for more information)
html_theme_options = {
    "base_url": "http://openforcefield.github.io/openff-sphinx-theme/",
    "repo_url": "https://github.com/openforcefield/openff-sphinx-theme/",
    "repo_name": "openff-sphinx-theme",
    "html_minify": False,
    "css_minify": False,
    "globaltoc_depth": 3,
    "globaltoc_include_local": True,
    "color_accent": "openff-toolkit-blue",
    "html_hyphenate_and_justify": True,
    "nav_links": [
        {
            "href": "https://squidfunk.github.io/mkdocs-material/",
            "internal": False,
            "title": "Material for MkDocs",
        },
        {
            "href": "https://bashtage.github.io/sphinx-material/",
            "internal": False,
            "title": "Material for Sphinx",
        },
        {
            "href": "https://openforcefield.org",
            "internal": False,
            "title": "The OpenFF Initiative",
        },
        {
            "href": "https://github.com/openforcefield/openff-sphinx-theme/",
            "internal": False,
            "title": "openff-sphinx-theme on GitHub",
        },
    ],
    "heroes": {
        "index": "A responsive Material Design theme for Sphinx sites.",
        "customization": "Configuration options to personalize your site.",
    },
    "socials": [
        {
            "href": "https://zenodo.org/communities/openforcefield/",
            "title": "OpenFF on Zenodo",
            "icon_classes": "ai ai-zenodo",
        },
        {
            "href": "https://www.youtube.com/channel/UCh0aJSUm_sYr7nuTzhW806g",
            "title": "OpenFF on YouTube",
            "icon_classes": "fab fa-youtube",
        },
        {
            "href": "https://github.com/openforcefield",
            "title": "OpenFF on GitHub",
            "icon_classes": "fab fa-github",
        },
        {

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

Configuration Options

google_analytics_account

Set to enable google analytics.

repo_url

Set the repo url for the link to appear.

repo_name

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

repo_type

Must be one of github, gitlab or bitbucket.

globaltoc_depth

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

globaltoc_collapse

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

globaltoc_includehidden

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

globaltoc_include_local

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

color_accent

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.

html_hyphenate_and_justify

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

html_minify

Minify pages after creation using htmlmin.

html_prettify

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

css_minify

Minify css files found in the output directory.

master_doc

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

nav_links

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)

heroes

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

socials

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.

Sidebars

You must set html_sidebars in order for the side bar to appear. There are four in the complete set.

html_sidebars = {
    "**": ["globaltoc.html", "localtoc.html", "searchbox.html"]
}

You can exclude any to hide a specific sidebar. For example, if this is changed to

html_sidebars = {
    "**": ["globaltoc.html"]
}

then only the global ToC would appear on all pages (** is a glob pattern).

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 ‘conf.py’:

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:

footerrel: Previous and next in the footer.
fonticon: 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)