Sphinx-Immaterial Theme =======================
|MIT License| |PyPI Package| |CI status| |codecov-badge|
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:
.. code-block:: bash
$ pip install sphinx-immaterial
or if you have the code checked out locally:
.. code-block:: bash
$ pip install -e .
Configuration -------------
In your conf.py add sphinx_immaterial as an extension:
.. code-block:: python
extensions = [ ..., "sphinx_immaterial" ]
and add the following:
.. code-block:: python
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.
.. code-block:: bash
mkdir source/_templates touch source/_templates/layout.html
Then, configure your 'conf.py':
.. code-block:: python
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
- mkdocs-material uses
lunr.js__ for searching, and has
.. |MIT License| image:: https://img.shields.io/badge/License-MIT-blue.svg :target: https://opensource.org/licenses/MIT-Clause
.. |PyPI Package| image:: https://img.shields.io/pypi/v/sphinx-immaterial :target: https://pypi.org/project/sphinx-immaterial
.. |CI status| image:: https://github.com/jbms/sphinx-immaterial/actions/workflows/build.yml/badge.svg :target: https://github.com/jbms/sphinx-immaterial/actions/workflows/build.yml
.. |codecov-badge| image:: https://codecov.io/gh/jbms/sphinx-immaterial/graph/badge.svg?token=IGK0B3WN42 :alt: codecov :target: https://codecov.io/gh/jbms/sphinx-immaterial