Sphinx-Immaterial Theme
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.
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.
See this theme’s own documentation for a demonstration.
WARNING: This theme is still in beta. While it is already very usable, breaking changes will still be made prior to the 1.0 release.
Installation
Install via pip:
$ pip install sphinx-immaterialor if you have the code checked out locally:
$ pip install -e .Configuration
In your conf.py add sphinx_immaterial as an extension:
extensions = [
...,
"sphinx_immaterial"
]and add the following:
html_theme = 'sphinx_immaterial'to set the theme.
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.
mkdir source/_templates
touch source/_templates/layout.htmlThen, 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 %}
Differences from mkdocs-material
This theme closely follows the upstream mkdocs-material repository, but there are a few differences, primarily due to differences between Sphinx and MkDocs:
This theme adds styles for Sphinx object descriptions, commonly used for API documentation (e.g. class and function documentation). This is a core element of Sphinx for which there is no corresponding feature in MkDocs.
mkdocs-material uses lunr.js for searching, and has custom UI components for displaying search results in a drop-down menu as you type the search query. This theme uses a separate search implementation based on the custom index format used by Sphinx, which fully integrates with the search UI provided by mkdocs-material.
1 maintainer
Metadata
1 maintainer
Release files for sphinx-immaterial 0.13.9
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| sphinx_immaterial-0.13.9-py3-none-any.whl | Python 3 | none | any | Details |
Release files / sphinx_immaterial-0.13.9-py3-none-any.whl
| Download URL | sphinx_immaterial-0.13.9-py3-none-any.whl |
|---|---|
| Size | 13.7 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5ea92d2ddc6befcd0fedbd3e6766ea4746e94d9a8a5cc0ab092a946e1fde4254
|
|
BLAKE2b-256 checksum How to use checksums |
3d426e958fc5d80ccd18c87d1b7d7c0e17fed04c0ed8a72933dd41c8643622d4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
