Material for Sphinx

This theme is an adaptation of the popular mkdocs-material theme for the Sphinx documentation tool.

This theme is regularly maintained to stay up to date with the upstream mkdocs-material repository. The HTML templates, JavaScript, and styles from the mkdocs-material theme are incoroprated directly with mostly minor modifications.

Independent of the upstream mkdocs-material theme, this theme integrates with and significantly extends Sphinx’s API documentation functionality.

This theme is a fork of the sphinx-material theme, which proved the concept of a Sphinx theme based on an earlier version of the mkdocs-material theme, but has now significantly diverged from the upstream mkdocs-material repository.

Getting Started


Building the theme from source requires node.js v14 or newer installed. Please be aware that uses a docker image that might have an outdated verson of node.js installed. Installing node.js from a Unix package manager may not provide version 14 or newer.

Installing from a distributed wheel (such as from does not require node.js installed.

Install from git source

pip install git+

Update your with the required changes:

extension = ["sphinx_immaterial"]
# ...
html_theme = "sphinx_immaterial"

There are a lot more ways to customize this theme. See Customization or theme.conf for more details.

Settings used in this documentation

html_theme = "sphinx_immaterial"

# material theme options (see theme.conf for more information)
html_theme_options = {
    "icon": {
        "repo": "fontawesome/brands/github",
    "site_url": "",
    "repo_url": "",
    "repo_name": "Sphinx-Immaterial",
    "repo_type": "github",
    "edit_uri": "blob/main/docs",
    # "google_analytics": ["UA-XXXXX", "auto"],
    "globaltoc_collapse": True,
    "features": [
        # "navigation.tabs",
        # "toc.integrate",
        # "navigation.instant",
        # "header.autohide",
        # "navigation.tracking",
        # "search.highlight",
    "palette": [
            "media": "(prefers-color-scheme: light)",
            "scheme": "default",
            "primary": "light-green",
            "accent": "light-blue",
            "toggle": {
                "icon": "material/lightbulb-outline",
                "name": "Switch to dark mode",
            "media": "(prefers-color-scheme: dark)",
            "scheme": "slate",
            "primary": "deep-orange",
            "accent": "lime",
            "toggle": {
                "icon": "material/lightbulb",
                "name": "Switch to light mode",
    # BEGIN: version_dropdown
    "version_dropdown": True,
    "version_info": [
            "version": "",
            "title": "ReadTheDocs",
            "aliases": [],
            "version": "",
            "title": "Github Pages",
            "aliases": [],
    # END: version_dropdown
    "toc_title_is_page_title": True,
    # BEGIN: social icons
    "social": [
            "icon": "fontawesome/brands/github",
            "link": "",
            "icon": "fontawesome/brands/python",
            "link": "",
    # END: social icons

Last update: Sep 30, 2022