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_options = {
    'site_url': 'http://bashtage.github.io/sphinx-material/',
    'repo_url': 'https://github.com/bashtage/sphinx-material/',
    'repo_name': 'Material for Sphinx',
    'google_analytics': ['UA-XXXXX','auto'],
    'html_minify': True,
    'globaltoc_depth': 2
}

hero¶

To set the hero’s text for an individual page, use the :hero: metadata field for the desired page. If not specified, then the page will not have a hero section.

Configuration Options¶

html_logo¶

The logo in the navigation side menu and header (when browser viewport is wide enough) is changed by specifying the html_logo option. This must specify an image in the project’s path (typically in the docs/images folder).

html_theme_options¶

site_url¶

Specify a site_url used to generate sitemap.xml links. If not specified, then no sitemap will be built.

repo_url¶

Set the repo url for the link to appear.

repo_name¶

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

repo_type¶

Must be one of github, gitlab or bitbucket.

edit_uri¶

This is the url segment that is concatenated with repo_url to point readers to the document’s source file. This is typically in the form of 'blob/<branch name>/<docs source folder>'. Defaults to a blank string (which disables the edit icon). This is disabled for builds on ReadTheDocs as they implement their own mechanism based on the repository’s branch or tagged commit.

features¶

Some features that have been ported and can be enabled by specifying the features name in a list of strings. The following features are supported:

• navigation.expand

• navigation.tabs (only shows for browsers with large viewports)

• toc.integrate

• navigation.sections

• navigation.instant

• header.autohide

• navigation.top

• search.highlight

• search.share

icon for the repository¶

The icon that represents the source code repository can be changed using the repo field of the icon dict (within the html_theme_options dict). Although this icon can be any of the icons bundled with this theme, popular choices are:

• fontawesome/brands/git

• fontawesome/brands/git-alt

• fontawesome/brands/git-square

• fontawesome/brands/github

• fontawesome/brands/github-alt

• fontawesome/brands/github-square

• fontawesome/brands/gitlab

• fontawesome/brands/gitkraken

• fontawesome/brands/bitbucket

palette¶

The theme’s color pallet. This theme requires at least 2 schemes specified (ie 1 scheme for light & 1 scheme for dark). Each scheme needs a specified primary and accent colors. Additionally, each scheme must have a toggle dict in which the name field specifies the text in the tooltip and the icon field specifies an icon to use to visually indicate which scheme is currently used.

primary color¶

Options are

red, pink, purple, deep-purple, indigo, blue, light-blue, cyan, teal, green, light-green, lime, yellow, amber, orange, deep-orange, brown, grey, blue-grey, black, and white.

accent color¶

Options are

red, pink, purple, deep-purple, indigo, blue, light-blue, cyan, teal, green, light-green, lime, yellow, amber, orange, deep-orange.

Toggle icon¶

Options must be any of the icons bundled with this theme. Popular combinations are

material/toggle-switch-off-outline	material/toggle-switch
material/weather-sunny	material/weather-night
material/eye-outline	material/eye
material/lightbulb-outline	material/lightbulb

direction¶

Specifies the text direction. Set to ltr (default) for left-to-right, or rtl for right-to-left.

google_analytics_account¶

Set to enable google analytics.

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.

version_dropdown¶

A flag indicating whether the version drop down should be included. You must supply a JSON file to use this feature.

version_dropdown_text¶

The text in the version dropdown button

version_json¶

The location of the JSON file that contains the version information. The default assumes there is a file versions.json located in the root of the site.

version_info¶

A dictionary used to populate the version dropdown. If this variable is provided, the static dropdown is used and any JavaScript information is ignored.

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 (typically located in the “docs” 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.

font

The default font inline CSS and the class to the google API. Use this block when changing the font.

fonticon

Block that contains the icon font. Use this to add additional icon fonts (e.g., FontAwesome). You should probably call {{ super() }} at the end of the block to include the default icon font as well.

Version Dropdown¶

A version dropdown is available that lets you store multiple versions in a single site. The standard structure of the site, relative to the base is usually:

/
/devel
/v1.0.0
/v1.1.0
/v1.1.1
/v1.2.0

To use the version dropdown, you must set version_dropdown to True in the sites configuration.

There are two approaches, one which stores the version information in a JavaScript file and one which uses a dictionary in the configuration.

Using a Javascript File¶

The data used is read via javascript from a file. The basic structure of the file is a dictionary of the form [label, path].

This dictionary tells the dropdown that the release version is in the root of the site, the other versions are archived under their version number, and the development version is located in /devel.

Using conf.py¶

The alternative uses a dictionary where the key is the title and the value is the target. The dictionary is part of the size configuration’s html_theme_options.

The dictionary structure is nearly identical. Here you can use relative paths like in the JavaScript version. You can also use absolute paths.