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

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

.. important::
   It is :dutree:`important` to correctly use admonitions.

.. warning::
   This is a :dutree:`warning`.

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

Version Directives¶

The versionadded, versionchanged, deprecated, and versionremoved directives defined by Sphinx are also rendered by the sphinx-immaterial theme as admonitions. The directives are optionally overridden to support additional admonition options :collapsible:, :name:, and :class:.

sphinx_immaterial_override_version_directives : bool = True¶

This theme can be configured to disallow these overrides if the new features cause a conflict with other Sphinx extensions.

Disallow overriding builtin version directives in conf.py¶

sphinx_immaterial_override_version_directives = False

These admonition styles can be customized (regardless of the sphinx_immaterial_override_version_directives setting) using the Custom Admonitions feature provided the name matches the directive name, but only the icon, color, and classes options will apply; all other options are ignored.

sphinx_immaterial_custom_admonitions = [
    {
        "name": "versionchanged",
        "color": (27, 138, 236),
        "icon": "material/alert-rhombus",
    }
]

.. versionadded:: 1.0 Description in title.
    :collapsible:

    Some additional context.
.. versionchanged:: 2.0
    Description in title.
.. deprecated:: 3.0

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

Specific directive Generic directive

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

Specific directive Generic directive

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

Specific directive Generic directive

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

Specific directive Generic directive

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

Specific directive Generic directive

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

Specific directive Generic directive

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

Specific directive Generic directive

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

Specific directive Generic directive

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

• a SVG file placed in the documentation project’s sphinx_immaterial_icon_path (this takes precedence).

• the .icons folder that has all of the icons bundled with this theme.

color: Color | None¶

The base color to be used for the admonition’s styling. If specified, this must be defined via:

• name (e.g. "Black", "azure")

• hexadecimal value (e.g. "0x000", "#FFFFFF", "7fffd4")

• RGB/RGBA tuples (e.g. (255, 255, 255), (255, 255, 255, 0.5))

• RGB/RGBA strings (e.g. "rgb(255, 255, 255)", "rgba(255, 255, 255, 0.5)")

• HSL strings (e.g. "hsl(270, 60%, 70%)", "hsl(270, 60%, 70%, .5)")

Note

Any specified transparency (alpha value) is ignored.

classes: list[str]¶

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¶

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.

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

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

: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);
}

html_static_path = ["_static"]
html_css_files = ["extra_css.css"]

Equivalent approach with Custom Admonitions feature¶

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.

html_theme_options = {
    "icon": {
        "admonition": {
            "note": "material/file-document-outline", # (1)!
        },
    },
}

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¶

sphinx_immaterial_custom_admonitions = [
    {
        "name": "note",
        "icon": "material/file-document-outline",
        "override": True,
    },
]