Skip to main content

Adaptation of mkdocs-material theme for the Sphinx documentation system

Project description

MIT License PyPI Package CI status

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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx_immaterial-0.11.10.tar.gz (8.3 MB view hashes)

Uploaded source

Built Distribution

sphinx_immaterial-0.11.10-py3-none-any.whl (10.9 MB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page