Customization¶
Metadata for a single page¶
Each page can support a set of page-specific options. These are configured using metadata roles.
Each metadata is evaluated as a :key: value
pair.
See also
Review the File-wide metadata section in the sphinx docs.
- hero¶
Unlike, newer versions of mkdocs-material theme, this theme also supports the use of a textual “hero” section.
To set the hero’s text for an individual page, use the
:hero:
metadata field for the desired page. If not specified, then the page will not have a hero section.:hero: Configuration options to personalize your site.
If specified, hides the global navigation sidebar shown on the left side of the page. By default, the navigation menu is shown if the browser viewport is sufficiently wide.
:hide-navigation:
- hide-toc¶
If specified, hides the local table of contents shown on the right side of the page. By default the local table of contents is shown if the page contains sub-sections and the browser viewport is sufficiently wide. If the
toc.integrate
feature
is enabled, then this option has no effect.:hide-toc:
Instead of using
:hide-toc:
, this theme can also use the:tocdepth:
metadata to hide the page’s Table of Contents.:tocdepth: 0
Configuration Options¶
-
html_logo : str =
None
¶ The logo in the navigation side menu and header (when browser viewport is wide enough) is changed by specifying the
html_logo
option.See also
This option is documented with more detail in the Sphinx documentation. However, the size constraints for
html_logo
andhtml_favicon
are not as strict for this theme.
-
html_theme_options =
{}
¶ This theme is configured using a
html_theme_options
dict
in the conf.py file. The following subsections can be used can be used as keys whose values configure the theme in different ways.- site_url¶
Specify a site_url used to generate sitemap.xml links. If not specified, then no sitemap will be built.
- repo_url¶
Set the repo url for the link to appear.
- repo_name¶
The name of the repo. If must be set if repo_url is set.
- repo_type¶
Must be one of github, gitlab or bitbucket.
- icon["repo"]¶
The icon that represents the source code repository can be changed using the
repo
field of theicon
dict
(within thehtml_theme_options
dict
). Although this icon can be any of the icons bundled with this theme, popular choices are:fontawesome/brands/git
fontawesome/brands/git-alt
fontawesome/brands/git-square
fontawesome/brands/github
fontawesome/brands/github-alt
fontawesome/brands/github-square
fontawesome/brands/gitlab
fontawesome/brands/gitkraken
fontawesome/brands/bitbucket
Important
This option has no effect if the
repo_url
option is not specified."icon": { "repo": "fontawesome/brands/github", },
- edit_uri¶
This is the url segment that is concatenated with
repo_url
to point readers to the document’s source file. This is typically in the form of"blob/<branch name>/<docs source folder>"
. Defaults to a blank string (which disables the edit icon). This is disabled for builds on ReadTheDocs as they implement their own mechanism based on the repository’s branch or tagged commit.
- features¶
Some features that have been ported from the mkdocs-material theme and can be enabled by specifying the features name in a list of strings. The following features are supported:
navigation.tabs (only shows for browsers with large viewports)
Note
Due to a difference in general document structure between mkdocs and sphinx, any
toctree
entry should start with a page entity (that contains a section header). Sphinx does allowtoctree
entries to be a list of only hyperlinks, but a navigation tab created from such an entry will only lead to the first hyperlink in thetoctree
.See issue #33 for a problematic demonstration.
Hint
Sphinx automatically implements the navigation.indexes feature.
- palette¶
The theme’s color pallette must be a single
dict
or alist
ofdict
s. Eachdict
can optionally specify ascheme
,primary
,accent
, andmedia
fields.- scheme¶
To use light and dark modes, this theme supports 2 schemes which are specified by a
scheme
field.The
default
scheme for light modehtml_theme_options = { "palette": { "scheme": "default" } }
The
slate
scheme for dark mode.html_theme_options = { "palette": { "scheme": "slate" } }
- primary¶
Primary color options are
red, pink, purple, deep-purple, indigo, blue, light-blue, cyan, teal, green, light-green, lime, yellow, amber, orange, deep-orange, brown, grey, blue-grey, black, and white.
- accent¶
Accent color options are
red, pink, purple, deep-purple, indigo, blue, light-blue, cyan, teal, green, light-green, lime, yellow, amber, orange, deep-orange.
- toggle¶
If using a
list
of schemes, then each scheme can have atoggle
dict
in whichThe
name
field specifies the text in the tooltip.The
icon
field specifies an icon to use that visually indicates which scheme is currently used. Options must be any of the icons bundled with this theme. Popular combinations arematerial/toggle-switch-off-outline
material/toggle-switch
material/weather-sunny
material/weather-night
material/eye-outline
material/eye
material/lightbulb-outline
material/lightbulb
- media (palette preference)¶
In order to automatically set the color palette based on the user’s system preference, a media query can be specified with the
media
field.html_theme_options = { "palette": [ { "media": "(prefers-color-scheme: light)", "scheme": "default", "toggle": { "icon": "material/toggle-switch-off-outline", "name": "Switch to dark mode", } }, { "media": "(prefers-color-scheme: dark)", "scheme": "slate", "toggle": { "icon": "material/toggle-switch", "name": "Switch to light mode", } }, ] }
- direction¶
Specifies the text direction. Set to
ltr
(default) for left-to-right, orrtl
for right-to-left.
- font¶
Use this dictionary to change the fonts used in the theme. For example:
html_theme_options = { "font": { "text": "Roboto", # used for all the pages' text "code": "Roboto Mono" # used for literal code blocks }, }
You can specify any of the available Google Fonts.
- analytics¶
Set to enable site analytics.
html_theme_options = { "analytics": { "provider": "google", "property": "G-XXXXXXXXXX" # Or "UA-XXXXXXXX-X" } }
- globaltoc_collapse¶
If true (the default value), TOC entries that are not ancestors of the current page are collapsed.
Warning
Setting this option to
False
may lead to large generated page sizes since the entire table of contents tree will be duplicated on every page.
- toc_title¶
A string that specifies the title text that appears above the table of contents in the side bar. If neither this configuration option nor
toc_title_is_page_title
is specified, a default language-dependent translation of “Table of Contents” is used. This configuration option takes precedence overtoc_title_is_page_title
.
- toc_title_is_page_title¶
If set to
True
andtoc_title
is unspecified, the table of contents is labeled in the side bar by the title of the page itself.
- version_dropdown¶
A
bool
flag indicating whether the version drop-down selector should be used. See Version Dropdown below about using this feature.
- version_json¶
The name of the JSON file that contains the version information to be used for the Version Dropdown selector. The default assumes there is a file named versions.json located in the root directory of the site hosted by a webserver.
- version_info¶
A list of dictionaries used to populate the Version Dropdown selector.
Version Dropdown¶
A version dropdown selector is available that lets you store multiple versions in a single site. The standard structure of the site (relative to the base domain) is usually
/
/1.0
/2.0
Whereas Sphinx must be executed separately for each version of the documentation you are building.
git fetch --all --tags
git checkout 1.0
sphinx-build docs _build/1.0
git checkout 2.0
sphinx-build docs _build/2.0
This means you need to implement a custom mechanism that allows keeping the built documentation when checking out different branches or tagged commits.
Important
To use the version dropdown selector, you must set version_dropdown
to True
in
the html_theme_options
dict.
html_theme_options = {
"version_dropdown": True,
}
Supported Approaches¶
There are two approaches:
The version information is stored in a
version_info
list
in the conf.py file.Note
Notice this is an ordered list. Meaning, approach 1 will take precedence over approach 2.
The version information is stored in a JSON file.
The default name of the JSON file is
versions.json
, but the JSON file’s name could be changed by settingversion_json
in the conf.py file’shtml_theme_options
.html_theme_options = { "version_json": "doc_versions.json", }
Warning
The JSON approach only works if your documentation is served from a webserver; it does not work if you use
file://
url). When serving the docs from a webserver theversion_json
file is resolved relative to the parent directory that contains the sphinx builder’s HTML output. For example, if the builder’s output is2.0
, you should have directory structure like so:/versions.json /1.0/index.html /2.0/index.html
Version Information Structure¶
Both approaches use a data structure similar to what is used by the
mkdocs mike plugin. Contrary to what the mike plugin’s
README says, the aliases
field is not optional, but it can be set to an empty list if not using
aliases. Other required fields include version
and title
.
The
version
field can be set to a relative/absolute path or a URL.The
title
field is a string used to describe the version in the selector’s dropdown menu.The
aliases
field is meant for giving a specific version a surname like “latest” or “stable”. This way, a URL to the webserver “<webserver-domain>/stable” will be redirected to the correspondingversion
’s path.Let’s say you have a version of the documentation built on a pre-release in a directory called “3.0-rc1”.
/ /1.0 /2.0 /3.0-rc1
You can give this pre-released version an alias called “beta” or “latest”.
[ {"version": "1.0", "title": "1.0", "aliases": []} {"version": "2.0", "title": "2.0", "aliases": ["stable"]} {"version": "3.0-rc1", "title": "Release Candidate 1", "aliases": ["beta", "latest"]} ]
"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": [],
},
],
Note
aliases
do not apply when using an external URL (as in not relative to the same webserver)
in the verion
field.
html_theme_options = {
"version_dropdown": True,
"version_info": [
{"version": "2.0", "title": "2.0", "aliases": ["latest"]},
{"version": "1.0", "title": "1.0", "aliases": []},
],
}
Hint
Remember to set "version_dropdown": True
in the conf.py file’s html_theme_options
dict
.
[
{"version": "2.0", "title": "2.0", "aliases": ["latest"]},
{"version": "1.0", "title": "1.0", "aliases": []},
]
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 (typically located in the “docs” 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 %}
Partial Layout¶
To override partial html templates in the theme, the documentation project’s _template folder should imitate the structure of HTML partial templates in this theme’s src directory.
For example, this theme (unlike the mkdocs-material theme) still supports a user defined
extracopyright
block. To make use of this, create a file titled footer.html
in the
project’s _templates/partials
folder. So the project’s documentation sources are in a
folder named docs
.
┌ docs/
└┬ _templates/
└┬ partials/
└─ footer.html
In the footer.html
file, add the necessary code by extending the theme’s original
HTML template of the same name.
{% extends "!partials/footer.html" %}
{# the '!' in "!partials/footer.html" is important #}
{% block extracopyright %}
<p>EXTRA COPYRIGHT</p>
{% endblock %}
Lastly, make sure the project’s documentation conf.py
has the following line:
templates_path = ["_templates"]
New Blocks¶
This theme has a new block inherited from the mkdocs-material theme:
footerrel
Previous and next in the footer.