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.

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 and html_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 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¶

The link to the repository will be rendered next to the search bar on large screens and as part of the main navigation drawer on smaller screen sizes. Additionally, for public repositories hosted on GitHub or GitLab, the number of stars and forks is automatically requested and rendered.

GitHub repositories also include the tag of the latest release. Unfortunately, GitHub only provides an API endpoint to obtain the latest release - not the latest tag. Thus, make sure to create a release (not pre-release) for the latest tag you want to display next to the number of stars and forks.

repo_name¶: The name of the repository. If repo_url is set, then the repository’s name will be extracted from the given URL. Optionally, this can be set to customize the repository name.

Warning

If the repo_url does not use a github, gitlab, or bitbucket domain, then this option must be set explicitly.

icon¶

This is the setting currently used by this documentation.¶

    "icon": {
        "repo": "fontawesome/brands/github",
        "edit": "material/file-edit-outline",
    },

repo¶

The icon that represents the source code repository can be changed using the icon[repo] field in the html_theme_options settings. 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/github
fontawesome/brands/github-alt
fontawesome/brands/gitlab
fontawesome/brands/gitkraken
fontawesome/brands/bitbucket

Important

This option has no effect if the repo_url option is not specified.

admonition¶: The default icons for admonitions can be changed by setting this field to a dict in which the keys are CSS classes (see Admonitions) and the values are any of the icons bundled with this theme.

See also

Refer to the Changing the Admonition Icon section for more detail.

edit¶

The icon used for the generated “edit this page” button at the top of the document. This is only used if edit_uri is configured and when not explicitly hidden using hide-edit-link.

As usual, any of the icons bundled with this theme can be used here. While the default is material/pencil, this documentation uses material/file-edit-outline

logo¶

The icon that is used as a fallback when html_logo is not specified. The behavior of this option is inherited from the mkdocs-material theme, so any of the icons bundled with this theme can be used here.

html_theme_options = {
    "icon": {
        "logo": "material/library"
    },
}

alternate¶

The icon used for the language selector button. See languages to configure the options in the language selector drop-down menu.

html_theme_options = {
    "icon": {
        "logo": "material/translate"
    },
}

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).

features¶

Some features that have been ported from the mkdocs-material theme and can be enabled by specifying the feature’s name in a list of strings. The following features are supported:

content.code.annotate

See also

Refer to the Code Annotations document for more detail.
content.tabs.link

See also

Please refer to the Linked tabs section for more information.
header.autohide
navigation.expand
navigation.instant
navigation.sections
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 allow toctree 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 the toctree.

See issue #33 for a problematic demonstration.
navigation.tabs.sticky
navigation.top
navigation.tracking
search.highlight
search.share
toc.integrate
announce.dismiss

See also

Refer to the New blocks section below about how to add an announcement banner.
toc.follow

This is similar to the toc.follow feature supported by the mkdocs-material theme, but differs in that both the left and right sidebar are scrolled automatically.
- The local table-of-contents scrolls automatically to keep the currently-displayed document section in view. Note that this applies to all three possible locations for the local table-of-contents:
  - in the right sidebar, which is the default location if the browser viewport is sufficiently wide;
  - in the left sidebar, if the toc.integrate feature is enabled;
  - in the “layered” navigation menu, if the browser viewport is sufficiently narrow.
- If the toc.integrate feature is disabled, the left sidebar additionally scrolls automatically to keep within view either:
  - the navigation entry for the current document, or
  - if the current document contains sections with child documents, the navigation entry for the currently-displayed document section.
  Note that if the toc.integrate feature is enabled, the left sidebar is instead scrolled for the local table-of-contents as described above.
toc.sticky

Makes headings in the left and right sidebars “sticky”, such that the full path to each heading remains visible even as the sidebars are scrolled.

Hint

Sphinx automatically implements the navigation.indexes feature.

palette¶

The theme’s color pallette must be a single dict or a list of dicts. Each dict can optionally specify a scheme, primary, accent, and media fields.

scheme¶

To use light and dark modes, this theme supports 2 schemes which are specified by a scheme field.

html_theme_options = {
    "palette": { "scheme": "default" }
}

(scheme for light mode)
(scheme for dark mode)

Click one of the listed schemes to see how it looks.

primary¶

The primary color is used for the header, the sidebar, text links and several other components.

html_theme_options = {
    "palette": { "primary": "green" }
}

Primary color options are

Click one of the colors to see how it looks.

accent¶

The accent color is used to denote elements that can be interacted with, e.g. hovered links, buttons, and scrollbars.

html_theme_options = {
    "palette": { "accent": "green" }
}

Accent color options are

Click one of the colors to see how it looks.

toggle¶

If using a list of schemes, then each scheme can have a toggle dict in which

The 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 are

material/toggle-switch-off-outline

material/toggle-switch

material/weather-sunny

material/weather-night

material/eye-outline

material/eye

material/lightbulb-outline

material/lightbulb

`material/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, or rtl 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.

The specified fonts will be downloaded automatically (using the cache specified by sphinx_immaterial_external_resource_cache_dir) and included in the built documentation.

To use the user’s system font instead of (and similar to) the theme’s default fonts, set this field to False.

rely on fonts available in the user’s OS.¶

html_theme_options = {
    "font": False,
}

Using a self-hosted font:¶

Using a custom or self-hosted font requires extra CSS to define the font family and overridden CSS theme variables. The following steps were used to self-host Google’s “Comic Neue” and “Comic Mono” fonts as an example.

Copy the font files to your project’s _static folder. The font’s file format() will be specified in step 2. If the font has different weights, then each weight will have a separate file. By default, this theme mainly uses 300, 400, and 700 weights, although only one weight/variant is technically required (400 weight is recommended).

Define the font family in a CSS file and append the CSS file’s name to the project’s list of html_css_files in config.py.

Each weight must have a corresponding @font-face rule. The same mandate applies to italic variants (if any) and their weights.

docs/_static/custom_font_example.css¶

/* comic-neue-latin-400-normal */
@font-face {
  font-family: 'Comic Neue';
  font-style: normal;
  font-display: swap;
  font-weight: 400;
  src: url('./example-custom-font/comic-neue-latin-400-normal.woff2') format('woff2'), url('./example-custom-font/comic-neue-latin-400-normal.woff') format('woff');
}
/* comic-mono-latin-400-normal */
@font-face {
  font-family: 'Comic Mono';
  font-style: normal;
  font-display: swap;
  font-weight: 400;
  src: url('./example-custom-font/comic-mono-latin-400-normal.woff2') format('woff2'), url('./example-custom-font/comic-mono-latin-400-normal.woff') format('woff');
}

The path specified in the url() is relative to the file defining the font family. For example, the above snippet is located in this project’s _static folder where the font’s files are located in _static/example-custom-font/ folder.

Override the theme’s CSS variables.
```
:root {
  --md-text-font: "Comic Neue"; /* (1)! \*/
  --md-code-font: "Comic Mono"; /* (2)! \*/
}
```
1. Used for regular text.
2. Used for code snippets.
Warning

Always define fonts with the CSS variables shown above and not with font-family because font-family uses the theme’s CSS variables that define the system font fallback.

This text is just an **example**.
*Notice* the font family used is different (monospaced) in the code snippet.

This text is just an example. Notice the font family used is different (monospaced) in the code snippet.

analytics¶

To enable site analytics, a provider and property fields must be specified in this dict.

html_theme_options = {
    "analytics": {
        "provider": "google",
        "property": "G-XXXXXXXXXX"
    }
}

feedback¶

This theme also supports user feedback using site analytics. Along with the required provider and property fields, the feedback dict also requires the following fields:

title

The text used to invite user feedback (placed just above the feedback buttons).

ratings

This list of dict objects specifies the user’s options for feedback. Each dict will represent a button and requires the following fields:

icon: As usual, any of the icons bundled with this theme can be specified here.
name: The text shown in the tooltip when hovering over a feedback button.
data: The data transmitted to your analytics provider upon submission of user feedback.
note: The text displayed after the user feedback is submitted. You can use a HTML hyperlink element <a href="a_url">link text</a> to encourage further user interaction (see example snippet below).

using Google analytics to collect user feedback for each page¶

html_theme_options = {
    "analytics": {
        "provider": "google",
        "property": "G-XXXXXXXXXX",
        "feedback": {
            "title": "Was this page helpful?",
            "ratings": [
                {
                    "icon": "material/emoticon-happy-outline",
                    "name": "This page was helpful",
                    "data": 1,
                    "note": "Thanks for the feedback!",
                },
                {
                    "icon": "material/emoticon-sad-outline",
                    "name": "This page could be improved",
                    "data": 0,
                    "note": "Thanks for the feedback! Help us improve this page by "
                    '<a href="https://github.com/jbms/sphinx-immaterial/issues">opening an issue</a>.',
                },
            ],
        },
    },
}

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 setting version_json in the conf.py file’s html_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 the version_json file is resolved relative to the directory that contains the sphinx builder’s HTML output. For example, if the builder’s output is 2.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 corresponding version’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"]}
]
```

This is the version dropdown selector settings used by this theme:¶

    "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 version field.

Using version_info in conf.py Using a JSON file

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": []},
]

To redirect browsers to the latest version, add a index.html in the same directory as your project’s versions.json file to be served as the domain’s base URL. It should look something like the following:

<!DOCTYPE HTML>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <meta http-equiv="refresh" content="0; url=latest/" />
        <link rel="canonical" href="latest/" />
    </head>
    <body>
        <p>If this page does not refresh automatically, then please direct your browser to
            <a href="latest/">our latest docs</a>.
        </p>
    </body>
</html>

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"]

Adding a comment system¶

This theme supports using a third-party comment system of your choice at the bottom of any page. There are several services that can deliver an integrated comment system, but the following example demonstrates using Giscus which is Open Source and built on Github’s Discussions feature.

Ensure these requisites are completed:
- Install the Giscus Github App and grant access to the repository that should host comments as GitHub discussions. Note that this can be a repository different from your documentation.
- Visit Giscus and generate the snippet through their configuration tool to load the comment system. Copy the snippet for the next step. The resulting snippet should look similar to this:
```
<script
  src="https://giscus.app/client.js"
  data-repo="<username>/<repository>"
  data-repo-id="..."
  data-category="..."
  data-category-id="..."
  data-mapping="title"
  data-reactions-enabled="1"
  data-emit-metadata="1"
  data-theme="light"
  data-lang="en"
  crossorigin="anonymous"
  async>
</script>
```

Override the theme’s partials/comments.html template (blank by default) in your documentation source, and add the following code to you comments.html template override:

docs/_templates/partials/comments.html¶

{% if page.meta.comments %} <!-- (1)! -->
  <h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
  <!-- Insert generated snippet (2) here -->

  <!-- Synchronize Giscus theme with palette -->
  <script>
    var giscus = document.querySelector("script[src*=giscus]")

    /* Set palette on initial load */
    var palette = __md_get("__palette")
    if (palette && typeof palette.color === "object") {
      var theme = palette.color.scheme === "slate" ? "dark" : "light" // (3)!
      giscus.setAttribute("data-theme", theme)
    }

    /* Register event handlers after documented loaded */
    document.addEventListener("DOMContentLoaded", function() {
      var ref = document.querySelector("[data-md-component=palette]")
      ref.addEventListener("change", function() {
        var palette = __md_get("__palette")
        if (palette && typeof palette.color === "object") {
          var theme = palette.color.scheme === "slate" ? "dark" : "light" // (4)!

          /* Instruct Giscus to change theme */
          var frame = document.querySelector(".giscus-frame")
          frame.contentWindow.postMessage(
            { giscus: { setConfig: { theme } } },
            "https://giscus.app"
          )
        }
      })
    })
  </script>
{% endif %}

This template will only be used if the show-comments metadata is added to the document’s source.
This should be the snippet generated from step 1.
This code block ensures that Giscus renders with a dark theme when the palette[scheme] is set to slate. Note that multiple dark themes are available, so you can change it to your liking.
If changing the dark theme used by Giscus, then also change the dark theme name here as this takes affect when toggling between light and dark color schemes.
If changing the dark theme used by Giscus, then also change the dark theme name here as this takes affect when toggling between light and dark color schemes.

Enable comments for a certain page by adding the show-comments metadata to the document’s source.

If you’re using Version Dropdown, you might want to display a warning when the user visits any other version than the latest version. Using a partial template, you can override the outdated block with the a new jinja template located in the project’s documentation’s _templates/base.html.

docs/_templates/base.html¶

{% extends "!base.html" %}

{% block outdated %}
  You're not viewing the latest version.
  <a href="{{ '../' ~ base_url}}">
    <strong>Click here to go to latest.</strong>
  </a>
{% endblock %}

Changing the color of the banner in dark scheme

Depending on the project’s choices for palette colors, it might make the banner’s text more legible to change the background color of the banner.

docs/_static/extra_style.css¶

/* only override for dark/slate scheme */
[data-md-color-scheme="slate"] .md-banner--warning {
  background: var(--md-footer-bg-color);
}

New Blocks¶

This theme has a few new block inherited from the mkdocs-material theme:

footerrel

Previous and next in the footer.

announce

An announcement can be added to the top of the page by extending this theme’s base.html template. For example, this documentation uses the following custom template to add an announcement (scroll to top to see it in action).

docs/_templates/base.html¶

{% extends "!base.html" %}
{% block announce %}
  <p>
    Now includes
    <a href="https://squidfunk.github.io/mkdocs-material/changelog/">changes from mkdocs-material theme</a>
    v8.5.6
  </p>
{% endblock %}

Optionally, add the "announce.dismiss" in the features list to let readers dismiss the announcement banner.

Last update: Nov 16, 2024

Customization¶

Metadata for a single page¶

Configuration Options¶

Version Dropdown¶

Supported Approaches¶

Version Information Structure¶

Customizing the layout¶

Partial Layout¶

Adding a comment system¶

Version Banner¶

New Blocks¶