Admonitions

This theme uses the Admonition Directive for Sphinx admonitions.

rST and Sphinx

Most of the admonitions that the mkdocs-material theme supports were “borrowed” from admonitions defined in the reStructuredText specifications. You may recognize them from usage in other sphinx-based themes.

sphinx_immaterial_override_builtin_admonitions : bool = True

All builtin admonitions defined by sphinx and docutils are overridden by this theme to extend new functionality like custom titles and collapsible/dropdown appearance. This theme can be configured to disallow these overrides if the new features cause a conflict with other Sphinx extensions.

Disallow overriding builtin admonitions in conf.py
sphinx_immaterial_override_builtin_admonitions = False
note, seealso, todo
.. seealso::
   This admonition is specific to Sphinx directives and not defined in the reStructuredText
   specifications as you can `seealso`. The `todo` admonition is also defined as an extension
   that is distributed with Sphinx.

   The :dutree:`note` admonition *is* defined by the reStructuredText specifications.

See also

This admonition is specific to Sphinx directives and not defined in the reStructuredText specifications as you can seealso. The todo admonition is also defined as an extension that is distributed with Sphinx.

The note admonition is defined by the reStructuredText specifications.

tip, hint, important
.. important::
   It is :dutree:`important` to correctly use admonitions.

Important

It is important to correctly use admonitions.

attention, caution, warning
.. warning::
   This is a :dutree:`warning`.

Warning

This is a warning.

danger, error
.. error::
   You have made a grave :dutree:`error`.

Error

You have made a grave error.

Admonitions from mkdocs-material

Some additional admonitions are supported via the CSS styles inherited from the mkdocs-material theme. These admonition styles can be used in 2 ways:

  • The generic admonition directive’s :class: option.

  • The specific admonition directives generated by this theme for convenience. If the automatically generated directives cause conflicts with other existing directives’ names, then this theme can be configured to skip generating the specific directives.

    sphinx_immaterial_generate_extra_admonitions : bool = True

    The inherited admonition styles are conveniently exposed as directives in the sphinx-immaterial theme using the Custom Admonitions feature. Set this config option to False to disallow the generation of these convenience directives.

    Disallow generating extra admonition directives in conf.py
    sphinx_immaterial_generate_extra_admonitions = False
    

    If this option is disabled, the generic admonition directive can still be used to invoke these inherited admonition styles.

info
.. info::

   Some admonished content using the `info admonition style`_.

Info

Some admonished content using the info admonition style.

.. admonition:: Info
   :class: info

   Some admonished content using the `info admonition style`_.

Info

Some admonished content using the info admonition style.

abstract
.. abstract::

   Some admonished content using the `abstract admonition style`_.

Abstract

Some admonished content using the abstract admonition style.

.. admonition:: Abstract
   :class: abstract

   Some admonished content using the `abstract admonition style`_.

Abstract

Some admonished content using the abstract admonition style.

success
.. success::

   Some admonished content using the `success admonition style`_.

Success

Some admonished content using the success admonition style.

.. admonition:: Success
   :class: success

   Some admonished content using the `success admonition style`_.

Success

Some admonished content using the success admonition style.

question
.. question::

   Some admonished content using the `question admonition style`_.

Question

Some admonished content using the question admonition style.

.. admonition:: Question
   :class: question

   Some admonished content using the `question admonition style`_.

Question

Some admonished content using the question admonition style.

failure
.. failure::

   Some admonished content using the `failure admonition style`_.

Failure

Some admonished content using the failure admonition style.

.. admonition:: Failure
   :class: failure

   Some admonished content using the `failure admonition style`_.

Failure

Some admonished content using the failure admonition style.

bug
.. bug::

   Some admonished content using the `bug admonition style`_.

Bug

Some admonished content using the bug admonition style.

.. admonition:: Bug
   :class: bug

   Some admonished content using the `bug admonition style`_.

Bug

Some admonished content using the bug admonition style.

example
.. example::

   Some admonished content using the `example admonition style`_.

Example

Some admonished content using the example admonition style.

.. admonition:: Example
   :class: example

   Some admonished content using the `example admonition style`_.

Example

Some admonished content using the example admonition style.

quote
.. quote::

   Some admonished content using the `quote admonition style`_.

Quote

Some admonished content using the quote admonition style.

.. admonition:: Quote
   :class: quote

   Some admonished content using the `quote admonition style`_.

Quote

Some admonished content using the quote admonition style.

Admonition Directive

All admonitions listed above are created or overridden by this theme’s Custom Admonitions feature.

sphinx_immaterial_override_generic_admonitions : bool = True

The generic admonition directive defined by docutils is overridden by this theme to extend new functionality like custom titles and collapsible/dropdown appearance. This theme can be configured to disallow overriding the generic admonition directive if the new features cause a conflict with other Sphinx extensions.

Disallow overriding generic admonition in conf.py
sphinx_immaterial_override_generic_admonitions = False

By default, the following options are available to all admonitions.

.. admonition::

This directive was overridden from the docutils definition. The only difference (aside from the added options listed below) is that the inherently required argument used for a title has been made optional.

:title:

This option provides an alternative for custom titles in admonitions defined in rST and Sphinx because they don’t accept any directive arguments. When used with the generic admonition and the inherited Admonitions from mkdocs-material, the value for this option is concatenated with a title given as a directive argument.

The :no-title: option will supersede any given title.

Equivalent ways to customize the admonition’s title.
.. tip::
   :title: A custom title specified in the directive's :rst:`:title:` option.

   The :dutree:`tip` directive accepts no arguments.

.. admonition:: A custom title specified in the directive's *argument*.

   Notice the blank line between the directive's beginning block and this content block.

.. legacy:: A custom title specified in both the
   :title: directive's *argument* and :rst:`:title:` option.
      It can even span multiple lines.

   This admonition's directive was created just for this documentation using the
   sphinx-immaterial theme's `Custom Admonitions`_ feature.

A custom title specified in the directive’s :title: option.

The tip directive accepts no arguments.

A custom title specified in the directive’s argument.

Notice the blank line between the directive’s beginning block and this content block.

A custom title specified in both the directive’s argument and :title: option. It can even span multiple lines.

This admonition’s directive was created just for this documentation using the sphinx-immaterial theme’s Custom Admonitions feature.

:no-title:

This flag will skip rendering the admonition’s title. Coincidentally, this option will invoke the same behavior of a generic admonition without an argument provided.

The :collapsible: option will cause the :no-title: to be ignored.

Equivalent ways to exclude rendering the title
.. admonition::

   This *generic* admonition uses the styling of the `note admonition style <note-admonition-style>`.

.. success::
   :no-title:

   This *specific* admonition uses the styling of the `success admonition style`_

This generic admonition uses the styling of the note admonition style.

This specific admonition uses the styling of the success admonition style

:collapsible:

This option can be used to convert the rendered admonition into a collapsible HTML <details> element. A value of open will make the admonition expanded by default. Any other value is ignored and will make the admonition collapsed by default.

.. example:: Opened by default
   :collapsible: open

   Hide me.

.. question:: Closed by default.
   :collapsible:

   Found me.
Opened by default

Hide me.

Closed by default.

Found me.

:name:

Set this option with a qualified ID to reference the admonition from other parts of the documentation using the ref role.

.. quote:: Referencing an Admonition
   :name: my-admonition

   A reference to :ref:`this admonition <my-admonition>`

Referencing an Admonition

A reference to this admonition

:class:

If further CSS styling is needed, then use this option to append a CSS class name to the rendered HTML elements.

.. admonition::
   :class: animated-admonition-border

   .. literalinclude:: _static/extra_css.css
      :language: css
      :caption: docs/_static/extra_css.css
      :start-after: /* ************************* animated-admonition-border style
      :end-before: /* ************************* my-special-key style
docs/_static/extra_css.css
@keyframes flash_border {
  0% {
    border-color: blueviolet;
  }
  50% {
    border-color: aqua;
  }
  100% {
    border-color: blueviolet;
  }
}

.md-typeset .admonition.animated-admonition-border {
  animation: flash_border 1.5s infinite;
}

Custom Admonitions

This theme offers a robust solution that allows user-defined custom admonitions from the documentation’s conf.py.

sphinx_immaterial_custom_admonitions : list[sphinx_immaterial.custom_admonitions.CustomAdmonitionConfig] = []

A list of dicts that will be used to create custom admonition directives. Each dict is validated using the data class CustomAdmonitionConfig.

class sphinx_immaterial.custom_admonitions.CustomAdmonitionConfig[source]

This data class validates the user’s configuration value(s) in sphinx_immaterial_custom_admonitions. Each validated object corresponds to a generated custom admonition directive tailored with theme specific options.

name : str

The required name of the directive. This will be also used as a CSS class name. This value shall have characters that match the regular expression pattern [a-zA-Z0-9_-].

title : str | None

The default title to use when rendering the custom admonition. If this is not specified, then the name value is converted and used.

icon : str | None

The relative path to an icon that will be used in the admonition’s title. If specified, this path shall be relative to

color : tuple[int, int, int] | None

The base color to be used for the admonition’s styling. If specified, this must be specified as a RGB color space. Each color component shall be confined to the range [0, 255]. It is also possible to use the colorsys module if converting from a different color space (like HSL) to RGB.

classes : list[str] | None

If specified, this list of qualified names will be added to every rendered admonition (specific to the generated directive) element’s class attribute.

To adopt the styling of pre-existing admonition, include the desired admonition directive’s name in this list.

Adopting the style of an hint admonition:
sphinx_immaterial_custom_admonitions = [
    {
        "name": "my-admonition",
        "classes": ["hint"],
    },
]
override : bool

Can be used to override an existing directive (default is False). Only set this to True if the directive being overridden is an existing admonition defined by rST and Sphinx or an admonition inherited from the mkdocs-material theme.

Custom Admonition Example

As a demonstration, we will be using the following configuration:

sphinx_immaterial_custom_admonitions = [
    {
        "name": "legacy",
        "color": (236, 64, 11),
        "icon": "fontawesome/solid/recycle",
    },
]

Note that the name of the created directive (legacy) is directly related to the value of the name option.

The above configuration will create a directive that could be documented like so:

.. legacy::

A custom admonition created from the example's configuration. See the admonition directive for all available options and examples.

.. legacy::

   This is simple a example.

Legacy

This is simple a example.

Legacy approaches

Less efficient

These approaches were inherited from the mkdocs-material theme. While they still work in this theme, they are discouraged because:

  1. Changing Admonition Style requires boilerplate CSS code which is prone to errors (like typos or copy-and-paste problems).

  2. Changing the Admonition Icon is implemented in HTML only which will result in bloated HTML files.

The sphinx-immaterial theme offers custom admonitions as a more efficient alternative.

Changing Admonition Style

See our legacy notice and explanation.

If you want to add a custom admonition type, all you need is a color and an *.svg icon. Copy the icon’s code from the .icons folder and add the new CSS to an additional style sheet.

Pied Piper Example
.. admonition:: Pied Piper
   :class: pied-piper

   Don't tell him you use spaces instead of tabs...

Pied Piper

Don’t tell him you use spaces instead of tabs…

docs/_static/extra_css.css
:root {
  --md-admonition-icon--pied-piper: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M244 246c-3.2-2-6.3-2.9-10.1-2.9-6.6 0-12.6 3.2-19.3 3.7l1.7 4.9zm135.9 197.9c-19 0-64.1 9.5-79.9 19.8l6.9 45.1c35.7 6.1 70.1 3.6 106-9.8-4.8-10-23.5-55.1-33-55.1zM340.8 177c6.6 2.8 11.5 9.2 22.7 22.1 2-1.4 7.5-5.2 7.5-8.6 0-4.9-11.8-13.2-13.2-23 11.2-5.7 25.2-6 37.6-8.9 68.1-16.4 116.3-52.9 146.8-116.7C548.3 29.3 554 16.1 554.6 2l-2 2.6c-28.4 50-33 63.2-81.3 100-31.9 24.4-69.2 40.2-106.6 54.6l-6.3-.3v-21.8c-19.6 1.6-19.7-14.6-31.6-23-18.7 20.6-31.6 40.8-58.9 51.1-12.7 4.8-19.6 10-25.9 21.8 34.9-16.4 91.2-13.5 98.8-10zM555.5 0l-.6 1.1-.3.9.6-.6zm-59.2 382.1c-33.9-56.9-75.3-118.4-150-115.5l-.3-6c-1.1-13.5 32.8 3.2 35.1-31l-14.4 7.2c-19.8-45.7-8.6-54.3-65.5-54.3-14.7 0-26.7 1.7-41.4 4.6 2.9 18.6 2.2 36.7-10.9 50.3l19.5 5.5c-1.7 3.2-2.9 6.3-2.9 9.8 0 21 42.8 2.9 42.8 33.6 0 18.4-36.8 60.1-54.9 60.1-8 0-53.7-50-53.4-60.1l.3-4.6 52.3-11.5c13-2.6 12.3-22.7-2.9-22.7-3.7 0-43.1 9.2-49.4 10.6-2-5.2-7.5-14.1-13.8-14.1-3.2 0-6.3 3.2-9.5 4-9.2 2.6-31 2.9-21.5 20.1L15.9 298.5c-5.5 1.1-8.9 6.3-8.9 11.8 0 6 5.5 10.9 11.5 10.9 8 0 131.3-28.4 147.4-32.2 2.6 3.2 4.6 6.3 7.8 8.6 20.1 14.4 59.8 85.9 76.4 85.9 24.1 0 58-22.4 71.3-41.9 3.2-4.3 6.9-7.5 12.4-6.9.6 13.8-31.6 34.2-33 43.7-1.4 10.2-1 35.2-.3 41.1 26.7 8.1 52-3.6 77.9-2.9 4.3-21 10.6-41.9 9.8-63.5l-.3-9.5c-1.4-34.2-10.9-38.5-34.8-58.6-1.1-1.1-2.6-2.6-3.7-4 2.2-1.4 1.1-1 4.6-1.7 88.5 0 56.3 183.6 111.5 229.9 33.1-15 72.5-27.9 103.5-47.2-29-25.6-52.6-45.7-72.7-79.9zm-196.2 46.1v27.2l11.8-3.4-2.9-23.8zm-68.7-150.4l24.1 61.2 21-13.8-31.3-50.9zm84.4 154.9l2 12.4c9-1.5 58.4-6.6 58.4-14.1 0-1.4-.6-3.2-.9-4.6-26.8 0-36.9 3.8-59.5 6.3z"/></svg>')
}

.md-typeset .admonition.pied-piper {
  border-color: rgb(43, 155, 70);
}

.md-typeset .pied-piper>.admonition-title {
  background-color: rgba(43, 155, 70, 0.1);
  border-color: rgb(43, 155, 70);
}

.md-typeset .pied-piper>.admonition-title::before {
  background-color: rgb(43, 155, 70);
  -webkit-mask-image: var(--md-admonition-icon--pied-piper);
  mask-image: var(--md-admonition-icon--pied-piper);
}
docs/conf.py
html_static_path = ["_static"]
html_css_files = ["extra_css.css"]
Equivalent approach with Custom Admonitions feature
docs/conf.py
sphinx_immaterial_custom_admonitions = [
    {
        "name": "pied-piper",
        "color": (43, 155, 70),
        "icon": "fontawesome/brands/pied-piper-alt",
    },
]

Changing the Admonition Icon

See our legacy notice and explanation.

Any of the above builtin admonitions’ icons can be changed using the icon[admonition] field in html_theme_options settings. This will only work with any of the icons bundled with this theme.

Changing the note icon in conf.py
html_theme_options = {
    "icon": {
        "admonition": {
            "note": "material/file-document-outline", # (1)!
        },
    },
}
  1. Uses the icon

Alternate icon sets

Here’s some recipes for use in conf.py

html_theme_options = {
    "icon": {
        "admonition": {
            "note": "octicons/tag-16",
            "abstract": "octicons/checklist-16",
            "info": "octicons/info-16",
            "tip": "octicons/squirrel-16",
            "success": "octicons/check-16",
            "question": "octicons/question-16",
            "warning": "octicons/alert-16",
            "failure": "octicons/x-circle-16",
            "danger": "octicons/zap-16",
            "bug": "octicons/bug-16",
            "example": "octicons/beaker-16",
            "quote": "octicons/quote-16",
        },
    },
}
html_theme_options = {
    "icon": {
        "admonition": {
            "note": "fontawesome/solid/note-sticky",
            "abstract": "fontawesome/solid/book",
            "info": "fontawesome/solid/circle-info",
            "tip": "fontawesome/solid/bullhorn",
            "success": "fontawesome/solid/check",
            "question": "fontawesome/solid/circle-question",
            "warning": "fontawesome/solid/triangle-exclamation",
            "failure": "fontawesome/solid/bomb",
            "danger": "fontawesome/solid/skull",
            "bug": "fontawesome/solid/robot",
            "example": "fontawesome/solid/flask",
            "quote": "fontawesome/solid/quote-left",
        },
    },
}
Equivalent approach with Custom Admonitions feature
docs/conf.py
sphinx_immaterial_custom_admonitions = [
    {
        "name": "note",
        "icon": "material/file-document-outline",
        "override": True,
    },
]

Last update: Nov 15, 2022