Admonitions¶

Use admonitions for callouts with custom titles and Markdown content. For predefined titles and type-specific colors, use Alerts.

Enable¶

Enable Python-Markdown's admonition extension in mkdocs.yml:

markdown_extensions:
  - admonition

Write an admonition¶

Before you start

Keep the configuration in one place and merge new settings into it.

!!! note "Before you start"

    Keep the configuration in one place and merge new settings into it.

Indent the body four spaces. The type follows !!!; the quoted custom title is optional. For example, !!! note without a quoted title displays Note. Admonition types currently share the same theme styling.

For expandable notes using ??? or ???+, see Collapsible content.

Customization¶

These theme settings customize all admonitions. Admonitions don't use the type-specific alert_* colors:

theme:
  name: pixel-lab
  highlight_color: "#f5c842"
  surface_color: "#fffdf2"
  border_color: "#101410"
  shadow_color: "#101410"

Parameter	Default	Effect
`highlight_color`	Golden yellow · `#f5c842`	Admonition title background
`surface_color`	Ivory · `#fffdf2`	Admonition body background
`text_color`	Dark green-gray · `#182018`	Admonition body text
`border_color`	Near-black · `#101410`	Admonition outline and title divider
`shadow_color`	Near-black · `#101410`	Admonition pixel shadow

See Common attributes.

Component-wide overrides¶

To change every admonition's title fill, add this to your custom stylesheet:

.admonition > .admonition-title {
  background: #f5c842; /* Golden yellow */
}

Scoped overrides¶

Wrap each selected admonition, following Scope selected instances:

<div class="instance-admonition" markdown="1">

!!! note "Before you start"

    Keep the configuration in one place.

</div>

Add the scoped rule to your stylesheet:

.instance-admonition > .admonition > .admonition-title {
  background: #f5c842; /* Golden yellow */
}