Adaptation of mkdocs-material theme for the Sphinx documentation system
Project description
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-immaterial
or 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.html
Then, 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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sphinx_immaterial-0.11.12.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 168a47f7bc61f02d2e90663b07e32ee8c47e3938fbf2e826791423e9b3bd5b2d |
|
MD5 | 0e9af3114f47a94b7933b963e4c1b631 |
|
BLAKE2b-256 | b32cfdfc394e6149a58187d001d80ce91df817cfb2a07434f35110649af6ac36 |
Hashes for sphinx_immaterial-0.11.12-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5c3a3d52e1617f491c8187bcd17d8af0c74cf988aff4d5b2dc5566f0db764350 |
|
MD5 | 7c9d1815f4e6318d0d9b8b09f75f3aa9 |
|
BLAKE2b-256 | afc001122421a4bb40e8d4fa95d1ebde361bcfaf6e082fe42c7d77e71e8ba821 |