# Admonitions

Admonitions, also known as *call-outs*, are an excellent choice for including side content without significantly interrupting the document flow. Zensical provides several different types of admonitions and allows for the inclusion and nesting of arbitrary content.

## Configuration

This configuration enables admonitions, allows to make them collapsible and to nest arbitrary content inside admonitions. Add the following lines to your configuration:

```toml
[project.markdown_extensions]
admonition = {}
pymdownx.details = {}
pymdownx.superfences = {}
```

```yaml
markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences
```

See additional configuration options:

- [Admonition](<https://zensical.org/docs/compatibility/markdown/python-markdown/#admonition>)
- [Details](<https://zensical.org/docs/compatibility/markdown/python-markdown-extensions/#details>)
- [SuperFences](<https://zensical.org/docs/compatibility/markdown/python-markdown-extensions/#superfences>)

### Admonition icons

Each of the supported admonition types has a distinct icon, which can be changed to any icon bundled with the theme, or even a [custom icon](<https://zensical.org/docs/setup/logo-and-icons/#additional-icons>). Add the following lines to your configuration:

```toml
[project.theme.icon.admonition]
<type> = "<icon>"
```

> [!NOTE]
>
> **Expand to show alternate icon sets**
>
> ```toml
> [project.theme.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"
> ```
>
> ```toml
> [project.theme.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"
> ```

```yaml
theme:
  icon:
    admonition:
      <type>: <icon>
```

> [!NOTE]
>
> **Expand to show alternate icon sets**
>
> ```yaml
> theme:
>   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
> ```
>
> ```yaml
> theme:
>   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
> ```

## Usage

Admonitions follow a simple syntax: a block starts with `!!!`, followed by a single keyword used as a [type qualifier](<#supported-types>). The content of the block follows on the next line, indented by four spaces:

Admonition

```markdown
!!! note

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.
```

> [!NOTE]
>
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

### Change the title

By default, the title will equal the type qualifier in titlecase. However, it can be changed by adding a quoted string containing valid Markdown (including links, formatting, ...) after the type qualifier:

Admonition with custom title

```markdown
!!! note "Phasellus posuere in sem ut cursus"

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.
```

> [!NOTE]
>
> **Phasellus posuere in sem ut cursus**
>
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

### Nested admonitions

You can also include nested admonitions in your documentation. To do this, you can use your existing admonitions and indent the desired ones:

Nested Admonition

```markdown
!!! note "Outer Note"

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

    !!! note "Inner Note"

        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
        nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
        massa, nec semper lorem quam in massa.
```

> [!NOTE]
>
> **Outer Note**
>
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.
>
> > **Inner Note**
> >
> > Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

### Remove the title

Similar to [changing the title](<#change-the-title>), the icon and title can be omitted entirely by adding an empty string directly after the type qualifier. Note that this will not work for [collapsible blocks](<#collapsible-blocks>):

Admonition without title

```markdown
!!! note ""

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.
```

> [!NOTE]
>
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

### Collapsible blocks

When [Details](<https://zensical.org/docs/compatibility/markdown/python-markdown-extensions/#details>) is enabled and an admonition block is started with `???` instead of `!!!`, the admonition is rendered as an expandable block with a small toggle on the right side:

Admonition, collapsible

```markdown
??? note

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.
```

> [!NOTE]
>
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Adding a `+` after the `???` token renders the block expanded:

Admonition, collapsible and initially expanded

```markdown
???+ note

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.
```

> [!NOTE]
>
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

### Inline blocks

Admonitions can also be rendered as inline blocks (e.g., for sidebars), placing them to the right using the `inline` + `end` modifiers, or to the left using only the `inline` modifier:

> [!NOTE]
>
> **Lorem ipsum**
>
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

```markdown
!!! info inline end "Lorem ipsum"

    Lorem ipsum dolor sit amet, consectetur
    adipiscing elit. Nulla et euismod nulla.
    Curabitur feugiat, tortor non consequat
    finibus, justo purus auctor massa, nec
    semper lorem quam in massa.
```

Use `inline end` to align to the right (left for rtl languages).

> [!NOTE]
>
> **Lorem ipsum**
>
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

```markdown
!!! info inline "Lorem ipsum"

    Lorem ipsum dolor sit amet, consectetur
    adipiscing elit. Nulla et euismod nulla.
    Curabitur feugiat, tortor non consequat
    finibus, justo purus auctor massa, nec
    semper lorem quam in massa.
```

Use `inline` to align to the left (right for rtl languages).

**Important**: admonitions that use the `inline` modifiers *must* be declared prior to the content block you want to place them beside. If there's insufficient space to render the admonition next to the block, the admonition will stretch to the full width of the viewport, e.g., on mobile viewports.

### Supported types

The following admonition types are available in Zensical. The default is `note`.

**`note`**

> [!NOTE]
>
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

**`abstract`**

> [!NOTE]
>
> **Abstract**
>
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

**`info`**

> [!NOTE]
>
> **Info**
>
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

**`tip`**

> [!TIP]
>
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

**`success`**

> [!TIP]
>
> **Success**
>
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

**`question`**

> [!NOTE]
>
> **Question**
>
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

**`warning`**

> [!WARNING]
>
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

**`failure`**

> [!CAUTION]
>
> **Failure**
>
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

**`danger`**

> [!CAUTION]
>
> **Danger**
>
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

**`bug`**

> [!CAUTION]
>
> **Bug**
>
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

**`example`**

> [!NOTE]
>
> **Example**
>
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

**`quote`**

> [!NOTE]
>
> **Quote**
>
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

## Custom admonitions

For custom admonition types, see [Material for MkDocs' custom admonitions guide](<https://squidfunk.github.io/mkdocs-material/reference/admonitions/#custom-admonitions>). Its CSS examples target the classic Material appearance and may need adaptation for Zensical's `modern` variant; see [theme variants](<https://zensical.org/docs/compatibility/mkdocs/migration/#theme-variant>) for details.

## GitHub callouts

In addition to the [admonition syntax](<#usage>), [GitHub callouts](<https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts>), also known as *alerts*, can be used. They are defined as blockquotes with a special marker. This syntax is portable to GitHub, GitLab, and other tools that recognize it.

### Configuration

GitHub callouts are enabled with the [Quotes](<https://facelessuser.github.io/pymdown-extensions/extensions/quotes/>) extension, which is bundled with [Python Markdown Extensions](<https://zensical.org/docs/compatibility/markdown/python-markdown-extensions/index.md>). The `callouts` option must be turned on in the configuration:

```toml
[project.markdown_extensions.pymdownx.quotes]
callouts = true
```

```yaml
markdown_extensions:
  - pymdownx.quotes:
      callouts: true
```

### Usage

A callout is started with a blockquote marker `>` followed by `[!<type>]`. The content of the callout follows on subsequent lines, each prefixed with `>`:

GitHub callout

```markdown
> [!NOTE]
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
> nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
> massa, nec semper lorem quam in massa.
```

> [!NOTE]
>
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

The callout marker must be all uppercase. Lowercase markers, e.g. `[!note]`, are not recognized by GitHub, so they are not rendered as callouts there.

### Supported callout types

Five callout types are supported by GitHub. A direct mapping exists to the admonition types listed in the [supported types](<#supported-types>) section for three of them:

**`[!NOTE]`**

`note`

**`[!TIP]`**

`tip`

**`[!WARNING]`**

`warning`

**`[!IMPORTANT]`**

`important` – not a built-in admonition type, so the default admonition styling is used unless a [custom style](<https://zensical.org/docs/customization/#additional-css>) is added.

**`[!CAUTION]`**

`caution` – not a built-in admonition type, so the default admonition styling is used unless a [custom style](<https://zensical.org/docs/customization/#additional-css>) is added.

With the [Quotes](<https://facelessuser.github.io/pymdown-extensions/extensions/quotes/>) extension, any admonition type supported by Zensical can be used, not only these five.

Callouts are not part of the [GitHub Flavored Markdown specification](<https://github.github.com/gfm/>), so they are not supported by all GitHub Flavored Markdown parsers.