Configuration options to personalize your site.

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:

 90html_theme = "openff_sphinx_theme"
 91
 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"]
 96
 97# If HTML theme settings isn't lines 90-160, remember to change customization.rst
 98
 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"],
105}
106
107# material theme options (see theme.conf for more information)
108html_theme_options = {
109    "base_url": "http://openforcefield.github.io/openff-sphinx-theme/",
110    "repo_url": "https://github.com/openforcefield/openff-sphinx-theme/",
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": "https://squidfunk.github.io/mkdocs-material/",
121            "internal": False,
122            "title": "Material for MkDocs",
123        },
124        {
125            "href": "https://bashtage.github.io/sphinx-material/",
126            "internal": False,
127            "title": "Material for Sphinx",
128        },
129        {
130            "href": "https://openforcefield.org",
131            "internal": False,
132            "title": "The OpenFF Initiative",
133        },
134        {
135            "href": "https://github.com/openforcefield/openff-sphinx-theme/",
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": "https://zenodo.org/communities/openforcefield/",
147            "title": "OpenFF on Zenodo",
148            "icon_classes": "ai ai-zenodo",
149        },
150        {
151            "href": "https://www.youtube.com/channel/UCh0aJSUm_sYr7nuTzhW806g",
152            "title": "OpenFF on YouTube",
153            "icon_classes": "fab fa-youtube",
154        },
155        {
156            "href": "https://github.com/openforcefield",
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

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.

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)