Sphinx Immaterial Theme

0.13.9 · active · verified Thu Apr 16

Sphinx-Immaterial is an adaptation of the popular mkdocs-material theme for the Sphinx documentation system. It is actively maintained to stay up to date with the upstream mkdocs-material repository, incorporating HTML templates, JavaScript, and styles with mostly minor modifications. The current version is 0.13.9, with frequent minor releases as seen in the GitHub changelog, often driven by upstream `mkdocs-material` updates or Sphinx compatibility fixes.

Common errors

```
KeyError: 'font'
```
cause This error occurs when the `sphinx_immaterial.google_fonts` extension attempts to access 'font' options in `html_theme_options` but it's not defined or incorrectly configured, especially with Sphinx 9.1.0.

fix Define the 'font' key within `html_theme_options` in your `conf.py`, even if empty or basic. Refer to the `sphinx-immaterial` documentation for correct font configuration.
```
Extension error: Could not import extension sphinx_immaterial.apidoc.python.default (exception: cannot import name 'PyTypedField' from 'sphinx.domains.python')
```
cause This error is typically seen with Sphinx versions >= 7.3.0, which introduced breaking changes to internal APIs that `sphinx-immaterial`'s API documentation extensions relied upon.

fix Upgrade `sphinx-immaterial` to a version compatible with Sphinx 7.3.0+ (e.g., `0.12.x` or later, check release notes), or temporarily pin your Sphinx version to a compatible earlier release (e.g., `sphinx~=7.2.0`).
```
sphinx.errors.ThemeError: The theme 'sphinx_immaterial' was not found or is not a valid theme. Check your html_theme setting.
```
cause This usually happens when `html_theme = 'sphinx_immaterial'` is set in `conf.py` but the `sphinx_immaterial` package is not installed, or `sphinx_immaterial` is not added to the `extensions` list.

fix Ensure `pip install sphinx-immaterial` has been run, and both `extensions = [...'sphinx_immaterial']` and `html_theme = 'sphinx_immaterial'` are correctly set in your `conf.py`.
```
WARNING: Unknown target name: "some_target"
```
cause This warning, often accompanied by issues in docstring parsing, can occur when using `numpydoc` with `sphinx-immaterial` if there are conflicts in how cross-references or sections are interpreted, or due to incorrect reStructuredText syntax.

fix Carefully review your reStructuredText and `numpydoc` style. Ensure `numpydoc` is configured correctly, and consider simplifying complex docstring structures or explicit cross-referencing. `numpydoc` itself has a style guide.

Warnings

breaking The theme is still in beta, and breaking changes may be introduced in minor versions before reaching a stable 1.0 release.
Fix: Always review the release notes and changelogs before upgrading, especially for minor versions, and test your documentation build.
breaking Older Sphinx versions are no longer supported. For example, support for Sphinx < 6 was dropped in `sphinx-immaterial` v0.13.2.
Fix: Ensure your Sphinx installation meets the minimum version requirement specified in the `sphinx-immaterial` release notes. Upgrade Sphinx to a compatible version.
gotcha Incompatibility with newer Sphinx versions due to internal API changes is a recurring issue, notably with Sphinx >= 7.3.0 and Sphinx 9.x. This can lead to `ExtensionError` or `KeyError` during the build process.
Fix: Check GitHub issues or release notes for specific compatibility fixes. If encountering issues, try pinning your Sphinx version to the latest known compatible version with `sphinx-immaterial` until a fix is released for the theme.
gotcha Using the `numpydoc` Sphinx extension in conjunction with `sphinx-immaterial` might lead to warnings or unexpected formatting, as the theme explicitly warns if `numpydoc` is used.
Fix: Review `numpydoc` configuration and theme documentation for any specific guidelines. Consider adjusting `numpydoc` settings or carefully inspecting rendered output to ensure correct interpretation of docstrings.

Install

pip install sphinx-immaterial Install latest version

Imports

sphinx_immaterial
```
extensions = [
    # ... other extensions
    'sphinx_immaterial'
]
```
The theme itself must be enabled as a Sphinx extension in `conf.py`.
html_theme
wrong:
```
html_theme = 'material' # or 'mkdocs-material'
```
correct:
```
html_theme = 'sphinx_immaterial'
```
The theme name for Sphinx is 'sphinx_immaterial', not 'material' or 'mkdocs-material'.

Quickstart

To quickly set up `sphinx-immaterial`, first initialize a Sphinx project using `sphinx-quickstart`. Then, modify the `conf.py` file to include `sphinx_immaterial` in your `extensions` list and set `html_theme = 'sphinx_immaterial'`. You can further customize the theme using `html_theme_options` in `conf.py`.

import os
import sys

# Minimal conf.py
project = 'My Project'
copyright = '2026, Your Name'
author = 'Your Name'
release = '0.1'

extensions = [
    'sphinx_immaterial',
    'sphinx.ext.autodoc', # Example standard extension
]

html_theme = 'sphinx_immaterial'
html_theme_options = {
    'icon': {
        'repo': 'fontawesome/brands/github'
    },
    'site_url': 'https://example.com/docs/'
}

# Example index.rst (or index.md if markdown is enabled)
# You would typically generate this with sphinx-quickstart first.
# Replace with content of docs/index.rst or equivalent.
# This part is illustrative, not executed Python code.
# Example: docs/index.rst
# My Project
# ===========
#
# Welcome to my project's documentation!
#
# .. toctree::
#    :maxdepth: 2
#    :caption: Contents:
#
#    module1
#    module2

view raw JSON →