{"id":9319,"library":"sphinx-immaterial","title":"Sphinx Immaterial Theme","description":"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.","status":"active","version":"0.13.9","language":"en","source_language":"en","source_url":"https://github.com/jbms/sphinx-immaterial","tags":["sphinx","documentation","theme","mkdocs-material","material design"],"install":[{"cmd":"pip install sphinx-immaterial","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for building documentation; compatibility with Sphinx versions is actively managed and has led to breaking changes.","package":"sphinx","optional":false},{"reason":"Runtime environment requirement.","package":"python","optional":false},{"reason":"Required for the optional 'keys' extension (e.g., sphinx_immaterial.kbd_keys) to process keyboard key directives.","package":"pymdown-extensions","optional":true}],"imports":[{"note":"The theme itself must be enabled as a Sphinx extension in `conf.py`.","symbol":"sphinx_immaterial","correct":"extensions = [\n    # ... other extensions\n    'sphinx_immaterial'\n]"},{"note":"The theme name for Sphinx is 'sphinx_immaterial', not 'material' or 'mkdocs-material'.","wrong":"html_theme = 'material' # or 'mkdocs-material'","symbol":"html_theme","correct":"html_theme = 'sphinx_immaterial'"}],"quickstart":{"code":"import os\nimport sys\n\n# Minimal conf.py\nproject = 'My Project'\ncopyright = '2026, Your Name'\nauthor = 'Your Name'\nrelease = '0.1'\n\nextensions = [\n    'sphinx_immaterial',\n    'sphinx.ext.autodoc', # Example standard extension\n]\n\nhtml_theme = 'sphinx_immaterial'\nhtml_theme_options = {\n    'icon': {\n        'repo': 'fontawesome/brands/github'\n    },\n    'site_url': 'https://example.com/docs/'\n}\n\n# Example index.rst (or index.md if markdown is enabled)\n# You would typically generate this with sphinx-quickstart first.\n# Replace with content of docs/index.rst or equivalent.\n# This part is illustrative, not executed Python code.\n# Example: docs/index.rst\n# My Project\n# ===========\n#\n# Welcome to my project's documentation!\n#\n# .. toctree::\n#    :maxdepth: 2\n#    :caption: Contents:\n#\n#    module1\n#    module2","lang":"python","description":"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`."},"warnings":[{"fix":"Always review the release notes and changelogs before upgrading, especially for minor versions, and test your documentation build.","message":"The theme is still in beta, and breaking changes may be introduced in minor versions before reaching a stable 1.0 release.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Ensure your Sphinx installation meets the minimum version requirement specified in the `sphinx-immaterial` release notes. Upgrade Sphinx to a compatible version.","message":"Older Sphinx versions are no longer supported. For example, support for Sphinx < 6 was dropped in `sphinx-immaterial` v0.13.2.","severity":"breaking","affected_versions":"<0.13.2 (for Sphinx < 6)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"0.11.x with Sphinx >=7.3.0, 0.13.x with Sphinx 9.x"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"KeyError: 'font'"},{"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`).","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.","error":"Extension error: Could not import extension sphinx_immaterial.apidoc.python.default (exception: cannot import name 'PyTypedField' from 'sphinx.domains.python')"},{"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`.","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.","error":"sphinx.errors.ThemeError: The theme 'sphinx_immaterial' was not found or is not a valid theme. Check your html_theme setting."},{"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.","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.","error":"WARNING: Unknown target name: \"some_target\""}]}