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
# -- HTML theme settings ------------------------------------------------
extensions.append("sphinx_immaterial")
html_title = "Sphinx-Immaterial"
html_theme = "sphinx_immaterial"
html_favicon = "_static/images/favicon.ico" # colored version of material/bookshelf.svg
html_logo = "_static/images/Ybin.gif" # from https://gifer.com/en/Ybin
# material theme options (see theme.conf for more information)
html_theme_options = {
"icon": {
"logo": "material/library",
"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,
"globaltoc_depth": -1,
"features": [
# "navigation.expand",
# "navigation.tabs",
# "toc.integrate",
"navigation.sections",
# "navigation.instant",
# "header.autohide",
"navigation.top",
],
"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",
},
},
],
}
html_last_updated_fmt = ""
html_use_index = True
html_domain_indices = True