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 = "mdanalysis_sphinx_theme"

extra_nav_links = {}
extra_nav_links["MDAnalysis"] = "http://mdanalysis.org"
extra_nav_links["MDAnalysis docs"] = "http://docs.mdanalysis.org"
extra_nav_links["@mdanalysis"] = "https://twitter.com/mdanalysis"


# material theme options (see theme.conf for more information)
html_theme_options = {
    # whether to apply official MDAnalysis styling
    # e.g. using the official MDAnalysis logo and favicon
    # and using the MDAnalysis privacy policy
    "mda_official": True,
    # Extra navigation links to show on the sidebar, before the table of contents
    "extra_nav_links": extra_nav_links,
    # The background colour of the logo area in the navigation bar
    "sidebar_logo_background": "#ffffff",
    # The background colour of the top navigation bar on mobile
    "mobile_navbar_background": "dark-gray",

    # other options inherited from sphinx_rtd_theme
    # Only display logo and not the project name on sidebar
    "logo_only": True,
    # Display the version number on the sidebar
    "display_version": True,
    # Where to display "next" and "previous" buttons
    "prev_next_buttons_location": "bottom",
    # Add an icon next to external links
    "style_external_links": False,
    # If enabled, navigation entries are not expandable
    "collapse_navigation": True,
    # If enabled, the navigation bar scrolls with the main page
    "sticky_navigation": True,
    # Maximum depth of the contents tree -- set to -1 for unlimited
    "navigation_depth": 4,
    # Whether to include hidden toctrees in the navigation bar
    "includehidden": True,
    # Whether to hide page subheadings from navigation
    "titles_only": False,
}

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

Configuration Options

mda_official: Whether to use official MDAnalysis styling. If True, this adds a footer with the MDAnalysis privacy policy and other common features. For example, if a logo and a favicon are not specified, the MDAnalysis logo and favicon are used.
sidebar_logo_background: The colour of the background of the logo in the sidebar. This can be a hex string (e.g. '#ffffff') or any of the named colours (mdanalysis-orange, mdanalysis-code-orange, white, dark-gray)
mobile_navbar_background: The colour of the top navigation header in mobile format. This can be a hex string (e.g. '#ffffff') or any of the named colours (mdanalysis-orange, mdanalysis-code-orange, white, dark-gray)
extra_nav_options: This is a dictionary of additional navigation links. They appear before the rest of the tables of contents in the sidebar. The keys are the labels of the links, and the values are the URLs.

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)