Inline icons

This theme has a builtin role to use icons within lines of text.


Using icons in the table of contents or navigation menu is not supported.


Set the content of this role to a relative path of an SVG image (excluding the .svg file extension). This path shall be relative to

  • the documentation source’s path(s) configured with sphinx_immaterial_icon_path (this takes precedence).

  • the .icons directory bundled with this theme

Optionally, a CSS class can be specified after the icon’s path, but the path and CSS class must be separated by semi-colon (;). Do not use spaces. If specifying multiple CSS classes, then separate them with a comma (,).

sphinx_immaterial_icon_path : list[str] = []

This list of paths will contain custom SVG icons that can be used in the documentation via si-icon or sphinx_immaterial_custom_admonitions. These paths must be relative to the documentation project’s file. The icons stored here will be (if used) rendered as CSS variables in the documentation’s HTML output. This is designed to allow for less duplicated code in generated output.

The icons in these paths will not be copied to the HTML output (like they would be for html_static_path).

Using inline icons

The following sets of icons are bundled with this theme:

Using a builtin icon
- :si-icon:`material/material-design` `Material Design <>`_
- :si-icon:`fontawesome/regular/font-awesome` `Font Awesome <>`_
- :si-icon:`octicons/mark-github-16` `Octicons <>`_
- :si-icon:`simple/simpleicons` `Simple Icons <>`_

You can also browse these icons locally from the sphinx-immaterial theme’s install path under path/to/sphinx-immaterial/sphinx_immaterial/.icons/.

Using custom CSS

It is possible to add specific styles to certain inline icons. Simply append a comma (,) separated list of CSS classes, and don’t forget to separate the icon’s path and CSS classes with a semi-colon (;).

Using an icon with custom CSS
This is a paragraph with :si-icon:`fontawesome/solid/heart;pulsing-heart` an animated icon
using the following CSS rules:

.. literalinclude:: _static/extra_css.css
    :language: css
    :start-after: /* *********************** inline icon pulsing-heart style

This is a paragraph with an animated icon using the following CSS rules:

@keyframes heart {
  0%, 40%, 80%, 100% {
    transform: scale(1);
  20%, 60% {
    transform: scale(1.15);

.pulsing-heart::before {
  background-color: red;
  animation: heart 1s infinite;
  height: 1.5em;
  width: 1.5em;
  vertical-align: middle;

Custom inline icons

Custom icons can be added to the documentation’s source files and referenced using the relative path. For example, this documentation has added the Sphinx application’s logo to its _static folder (which is specified using sphinx_immaterial_icon_path).




The custom icon must be a SVG file!

Ideally, the custom icon should have no embedded color or style information and use a transparent background. Conventionally, a SVG file is optimized using SVGO for which there are various ways to use.

A dimension of 24 pixels (width and/or height) is preferred. Be mindful of the SVG’s viewbox attribute as it must coincide with the path(s) maximum needed dimensions.

This icon :si-icon:`sphinx_logo` is located in

This icon is located in docs/_static/sphinx_logo.svg

Last update: Feb 17, 2024