Customization

Metadata for a single page

Each page can support a set of page-specific options. These are configured using metadata roles. Each metadata is evaluated as a :key: value pair.

See also

Review the File-wide metadata section in the sphinx docs.

hero

Unlike, newer versions of mkdocs-material theme, this theme also supports the use of a textual “hero” section.

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.

This is how the hero for this page is declared.
:hero: Configuration options to personalize your site.
hide-navigation

If specified, hides the global navigation sidebar shown on the left side of the page. By default, the navigation menu is shown if the browser viewport is sufficiently wide.

Hide the navigation menu like so:
:hide-navigation:
hide-toc

If specified, hides the local table of contents shown on the right side of the page. By default the local table of contents is shown if the page contains sub-sections and the browser viewport is sufficiently wide. If the toc.integrate feature is enabled, then this option has no effect.

Hide the Table of Contents like so:
:hide-toc:

Instead of using :hide-toc:, this theme can also use the :tocdepth: metadata to hide the page’s Table of Contents.

Set the depth for the Table of Contents to 0:
:tocdepth: 0

If specified, hides the “Edit this page” link at the top of the page. By default, an edit link is shown if edit_uri is specified. This option overrides that for a given page.

Hide the “Edit this page” link:
:hide-edit-link:

A common use case for this option is to specify it on automatically-generated pages, as for those pages there is no source document to edit.

Configuration Options

The logo in the navigation side menu and header (when browser viewport is wide enough) is changed by specifying the html_logo option.

See also

This option is documented with more detail in the Sphinx documentation. However, the size constraints for html_logo and html_favicon are not as strict for this theme.

html_theme_options = {}

This theme is configured using a html_theme_options dict in the conf.py file. The following subsections can be used can be used as keys whose values configure the theme in different ways.

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.

icon["repo"]

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:

  • fa-git fontawesome/brands/git

  • fa-git-alt fontawesome/brands/git-alt

  • fa-git-square fontawesome/brands/git-square

  • fa-github fontawesome/brands/github

  • fa-github-alt fontawesome/brands/github-alt

  • fa-github-square fontawesome/brands/github-square

  • fa-gitlab fontawesome/brands/gitlab

  • fa-gitkraken fontawesome/brands/gitkraken

  • fa-bitbucket fontawesome/brands/bitbucket

Important

This option has no effect if the repo_url option is not specified.

This is the setting currently used by this documentation.
    "icon": {
        "repo": "fontawesome/brands/github",
    },
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 from the mkdocs-material theme and can be enabled by specifying the features name in a list of strings. The following features are supported:

  • content.code.annotate

  • header.autohide

  • navigation.expand

  • navigation.instant

  • navigation.sections

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

    Note

    Due to a difference in general document structure between mkdocs and sphinx, any toctree entry should start with a page entity (that contains a section header). Sphinx does allow toctree entries to be a list of only hyperlinks, but a navigation tab created from such an entry will only lead to the first hyperlink in the toctree.

    See issue #33 for a problematic demonstration.

  • navigation.tabs.sticky

  • navigation.top

  • navigation.tracking

  • search.highlight

  • search.share

  • toc.integrate

  • toc.follow

    This is similar to the toc.follow feature supported by the mkdocs-material theme, but differs in that both the left and right sidebar are scrolled automatically.

    • The local table-of-contents scrolls automatically to keep the currently-displayed document section in view. Note that this applies to all three possible locations for the local table-of-contents:

      • in the right sidebar, which is the default location if the browser viewport is sufficiently wide;

      • in the left sidebar, if the toc.integrate feature is enabled;

      • in the “layered” navigation menu, if the browser viewport is sufficiently narrow.

    • If the toc.integrate feature is disabled, the left sidebar additionally scrolls automatically to keep within view either:

      • the navigation entry for the current document, or

      • if the current document contains sections with child documents, the navigation entry for the currently-displayed document section.

      Note that if the toc.integrate feature is enabled, the left sidebar is instead scrolled for the local table-of-contents as described above.

  • toc.sticky

    Makes headings in the left and right sidebars “sticky”, such that the full path to each heading remains visible even as the sidebars are scrolled.

Hint

Sphinx automatically implements the navigation.indexes feature.

palette

The theme’s color pallette must be a single dict or a list of dicts. Each dict can optionally specify a scheme, primary, accent, and media fields.

scheme

To use light and dark modes, this theme supports 2 schemes which are specified by a scheme field.

  1. The default scheme for light mode

    html_theme_options = {
         "palette": { "scheme": "default" }
    }
    
  2. The slate scheme for dark mode.

    html_theme_options = {
         "palette": { "scheme": "slate" }
    }
    
primary

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

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

If using a list of schemes, then each scheme can have a toggle dict in which

  • The name field specifies the text in the tooltip.

  • The icon field specifies an icon to use that visually indicates which scheme is currently used. Options must be any of the icons bundled with this theme. Popular combinations are

    toggle-off material/toggle-switch-off-outline

    toggle-on material/toggle-switch

    sunny material/weather-sunny

    night material/weather-night

    eye-outline material/eye-outline

    eye material/eye

    lightbulb-outline material/lightbulb-outline

    lightbulb material/lightbulb

media (palette preference)

In order to automatically set the color palette based on the user’s system preference, a media query can be specified with the media field.

html_theme_options = {
    "palette": [
        {
            "media": "(prefers-color-scheme: light)",
            "scheme": "default",
            "toggle": {
                "icon": "material/toggle-switch-off-outline",
                "name": "Switch to dark mode",
            }
        },
        {
            "media": "(prefers-color-scheme: dark)",
            "scheme": "slate",
            "toggle": {
                "icon": "material/toggle-switch",
                "name": "Switch to light mode",
            }
        },
    ]
}
direction

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

font

Use this dictionary to change the fonts used in the theme. For example:

html_theme_options = {
    "font": {
        "text": "Roboto",  # used for all the pages' text
        "code": "Roboto Mono"  # used for literal code blocks
    },
}

You can specify any of the available Google Fonts.

The specified fonts will be downloaded automatically (using the cache specified by sphinx_immaterial_external_resource_cache_dir) and included in the built documentation.

analytics

Set to enable site analytics.

html_theme_options = {
    "analytics": {
        "provider": "google",
        "property": "G-XXXXXXXXXX"  # Or "UA-XXXXXXXX-X"
    }
}
globaltoc_collapse

If true (the default value), TOC entries that are not ancestors of the current page are collapsed.

Warning

Setting this option to False may lead to large generated page sizes since the entire table of contents tree will be duplicated on every page.

toc_title

A string that specifies the title text that appears above the table of contents in the side bar. If neither this configuration option nor toc_title_is_page_title is specified, a default language-dependent translation of “Table of Contents” is used. This configuration option takes precedence over toc_title_is_page_title.

html_theme_options = {
    "toc_title": "Contents",
}
toc_title_is_page_title

If set to True and toc_title is unspecified, the table of contents is labeled in the side bar by the title of the page itself.

html_theme_options = {
    "toc_title_is_page_title": True,
}
social

A list of dicts that define iconic links in the site’s footer. Each dict shall have a "icon" and a "link" field.

This theme uses the following configuration:
    "social": [
        {
            "icon": "fontawesome/brands/github",
            "link": "https://github.com/jbms/sphinx-immaterial",
        },
        {
            "icon": "fontawesome/brands/python",
            "link": "https://pypi.org/project/sphinx-immaterial/",
        },
    ],
version_dropdown

A bool flag indicating whether the version drop-down selector should be used. See Version Dropdown below about using this feature.

version_json

The name of the JSON file that contains the version information to be used for the Version Dropdown selector. The default assumes there is a file named versions.json located in the root directory of the site hosted by a webserver.

version_info

A list of dictionaries used to populate the Version Dropdown selector.

sphinx_immaterial_external_resource_cache_dir : str

Specifies the local directory used to cache external resources, such as Google Fonts. If this config option is not specified, defaults to:

SPHINX_IMMATERIAL_EXTERNAL_RESOURCE_CACHE_DIR

Environment variable that specifies a default value for the sphinx_immaterial_external_resource_cache_dir configuration option.

Version Dropdown

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

/
/1.0
/2.0

Whereas Sphinx must be executed separately for each version of the documentation you are building.

git fetch --all --tags
git checkout 1.0
sphinx-build docs _build/1.0
git checkout 2.0
sphinx-build docs _build/2.0

This means you need to implement a custom mechanism that allows keeping the built documentation when checking out different branches or tagged commits.

Important

To use the version dropdown selector, you must set version_dropdown to True in the html_theme_options dict.

html_theme_options = {
    "version_dropdown": True,
}

Supported Approaches

There are two approaches:

  1. The version information is stored in a version_info list in the conf.py file.

    Note

    Notice this is an ordered list. Meaning, approach 1 will take precedence over approach 2.

  2. The version information is stored in a JSON file.

    The default name of the JSON file is versions.json, but the JSON file’s name could be changed by setting version_json in the conf.py file’s html_theme_options.

    html_theme_options = {
        "version_json": "doc_versions.json",
    }
    

    Warning

    The JSON approach only works if your documentation is served from a webserver; it does not work if you use file:// url). When serving the docs from a webserver the version_json file is resolved relative to the parent directory that contains the sphinx builder’s HTML output. For example, if the builder’s output is 2.0, you should have directory structure like so:

    /versions.json
    /1.0/index.html
    /2.0/index.html
    

Version Information Structure

Both approaches use a data structure similar to what is used by the mkdocs mike plugin. Contrary to what the mike plugin’s README says, the aliases field is not optional, but it can be set to an empty list if not using aliases. Other required fields include version and title.

  • The version field can be set to a relative/absolute path or a URL.

  • The title field is a string used to describe the version in the selector’s dropdown menu.

  • The aliases field is meant for giving a specific version a surname like “latest” or “stable”. This way, a URL to the webserver “<webserver-domain>/stable” will be redirected to the corresponding version’s path.

    Let’s say you have a version of the documentation built on a pre-release in a directory called “3.0-rc1”.

    /
    /1.0
    /2.0
    /3.0-rc1
    

    You can give this pre-released version an alias called “beta” or “latest”.

    [
      {"version": "1.0", "title": "1.0", "aliases": []}
      {"version": "2.0", "title": "2.0", "aliases": ["stable"]}
      {"version": "3.0-rc1", "title": "Release Candidate 1", "aliases": ["beta", "latest"]}
    ]
    
This is the version dropdown selector settings used by this theme:
    "version_dropdown": True,
    "version_info": [
        {
            "version": "https://sphinx-immaterial.rtfd.io",
            "title": "ReadTheDocs",
            "aliases": [],
        },
        {
            "version": "https://jbms.github.io/sphinx-immaterial",
            "title": "Github Pages",
            "aliases": [],
        },
    ],

Note

aliases do not apply when using an external URL (as in not relative to the same webserver) in the verion field.

html_theme_options = {
    "version_dropdown": True,
    "version_info": [
        {"version": "2.0", "title": "2.0", "aliases": ["latest"]},
        {"version": "1.0", "title": "1.0", "aliases": []},
    ],
}

Hint

Remember to set "version_dropdown": True in the conf.py file’s html_theme_options dict.

[
  {"version": "2.0", "title": "2.0", "aliases": ["latest"]},
  {"version": "1.0", "title": "1.0", "aliases": []},
]

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 %}

Partial Layout

To override partial html templates in the theme, the documentation project’s _template folder should imitate the structure of HTML partial templates in this theme’s src directory.

For example, this theme (unlike the mkdocs-material theme) still supports a user defined extracopyright block. To make use of this, create a file titled footer.html in the project’s _templates/partials folder. So the project’s documentation sources are in a folder named docs.

┌ docs/
└┬ _templates/
 └┬ partials/
  └─ footer.html

In the footer.html file, add the necessary code by extending the theme’s original HTML template of the same name.

{% extends "!partials/footer.html" %}
{# the '!' in "!partials/footer.html" is important #}
{% block extracopyright %}
  <p>EXTRA COPYRIGHT</p>
{% endblock %}

Lastly, make sure the project’s documentation conf.py has the following line:

templates_path = ["_templates"]

New Blocks

This theme has a new block inherited from the mkdocs-material theme:

footerrel

Previous and next in the footer.


Last update: Sep 30, 2022