Callouts#

A callout draws attention to information that should not be missed. Sumi uses the syntax GitHub introduced for alerts, so callouts render on GitHub, in your editor's preview and in Sumi alike.

> [!NOTE]
> Sumi reads the same syntax GitHub does.

注意

Sumi reads the same syntax GitHub does.

The five types#

注意

Useful information that users should know, even when skimming.

提示

Helpful advice for doing things better or more easily.

重要

Key information users need to achieve their goal.

警告

Urgent information that needs immediate attention to avoid problems.

小心

Advises about risks or negative outcomes of certain actions.

> [!NOTE]
> [!TIP]
> [!IMPORTANT]
> [!WARNING]
> [!CAUTION]

Sumi also accepts the type names used by Material for MkDocs — info, success, question, failure, danger, bug, example, quote, abstract and todo — each mapped to the closest colour.

Custom titles#

Text after the marker replaces the default title:

> [!WARNING] Back up first
> `mkdocs gh-deploy --force` replaces the whole `gh-pages` branch.

Back up first

mkdocs gh-deploy --force replaces the whole gh-pages branch.

Collapsible callouts#

Add - after the marker for a callout that starts closed, or + for one that starts open but can be closed.

> [!TIP]- Why is it called Sumi?
> *Sumi* (墨) is the ink of East Asian calligraphy: one colour, many shades.

Why is it called Sumi?

Sumi (墨) is the ink of East Asian calligraphy: one colour, many shades.

Collapsed callouts are printed open.

Rich content#

A callout can hold anything a blockquote can — lists, code, tables, even other callouts.

Before you upgrade

1. Read the release notes. 2. Pin the version in requirements.txt:

```text
mkdocs-sumi==0.1.0
```

Admonitions#

If your pages already use the admonition extension, they keep working and look the same:

!!! warning "Deprecated"
    Use `theme.palette` instead.

Deprecated

Use theme.palette instead.

??? note and ???+ note from pymdownx.details are styled as collapsible callouts.