Material for Sphinx¶
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.
Getting Started¶
Prerequisites
Building the theme from source requires node.js v14 or newer installed. Please be aware that readthedocs.org uses a docker image that might have an outdated verson of node.js installed. Installing node.js from a Unix package manager may not provide version 14 or newer.
Installing from a distributed wheel (such as from pypi.org) does not require node.js installed.
Install from git source
pip install git+https://github.com/jbms/sphinx-immaterial.git
Update your conf.py with the required changes:
extension = ["sphinx_immaterial"]
# ...
html_theme = "sphinx_immaterial"
There are a lot more ways to customize this theme. See Customization
or theme.conf for more details.
Settings used in this documentation
extensions.append("sphinx_immaterial")
html_theme = "sphinx_immaterial"
# material theme options (see theme.conf for more information)
html_theme_options = {
"icon": {
"repo": "fontawesome/brands/github",
},
"site_url": "https://jbms.github.io/sphinx-immaterial/",
"repo_url": "https://github.com/jbms/sphinx-immaterial/",
"repo_name": "Sphinx-Immaterial",
"repo_type": "github",
"edit_uri": "blob/main/docs",
# "google_analytics": ["UA-XXXXX", "auto"],
"globaltoc_collapse": True,
"features": [
# "navigation.expand",
# "navigation.tabs",
# "toc.integrate",
"navigation.sections",
# "navigation.instant",
# "header.autohide",
"navigation.top",
# "navigation.tracking",
# "search.highlight",
"search.share",
],
"palette": [
{
"media": "(prefers-color-scheme: light)",
"scheme": "default",
"primary": "light-green",
"accent": "light-blue",
"toggle": {
"icon": "material/lightbulb-outline",
"name": "Switch to dark mode",
},
},
{
"media": "(prefers-color-scheme: dark)",
"scheme": "slate",
"primary": "deep-orange",
"accent": "lime",
"toggle": {
"icon": "material/lightbulb",
"name": "Switch to light mode",
},
},
],
# BEGIN: version_dropdown
"version_dropdown": True,
"version_info": [
{
"version": "https://sphinx-immaterial.rtfd.io",
"title": "ReadTheDocs",
"aliases": [],
},
{
"version": "https://jbms.github.io/sphinx-immaterial",
"title": "Github Pages",
"aliases": [],
},
],
# END: version_dropdown
"toc_title_is_page_title": True,
}