Admonitions

Admonitions#

Admonitions (also known as callouts) highlight a particular block of text, that exists slightly apart from the narrative of your page, such as a note or a warning.

Admonitions are a special case of directive extensions. It is advised to use admonitions with the colon_fence extension, which signify that the content of the block is also MyST Markdown.

:::{tip}
Let's give readers a helpful hint!
:::

小技巧

Let’s give readers a helpful hint!

1.  Admonition types#

The following core admonition types are available:

注意

This is a attention

小心

This is a caution

危险

This is a danger

错误

This is a error

提示

This is a hint

重要

This is a important

备注

This is a note

参见

This is a seealso

小技巧

This is a tip

警告

This is a warning

These admonitions take no argument, but may be specified with options:

class:

A space-separated list of CSS classes to add to the admonition, conforming to the identifier normalization rules.

name:

A reference target for the admonition (see cross-referencing).

:::{tip}
:class: myclass1 myclass2
:name: a-tip-reference
Let's give readers a helpful hint!
:::

[Reference to my tip](#a-tip-reference)

小技巧

Let’s give readers a helpful hint!

Reference to my tip

Sphinx also adds a number of additional admonition types, for denoting changes to the documentation, or to the codebase:

:::{versionadded} 1.2.3
Explanation of the new feature.
:::

:::{versionchanged} 1.2.3
Explanation of the change.
:::

:::{deprecated} 1.2.3
Explanation of the deprecation.
:::

Added in version 1.2.3: Explanation of the new feature.

在 1.2.3 版本发生变更: Explanation of the change.

自 1.2.3 版本弃用: Explanation of the deprecation.

2.  Admonition titles#

To provide a custom title for an admonition, use the admonition directive. If you also want to style the admonition as one of the core admonition types, you can use the admonition directive with the class option.

:::{admonition} My custom title with *Markdown*!
:class: tip

This is a custom title for a tip admonition.
:::

My custom title with Markdown!

This is a custom title for a tip admonition.

3.  Collapsible admonitions#

The sphinx-togglebutton extension allows you to create collapsible admonitions, by adding a dropdown class to the admonition.

:::{note}
:class: dropdown

This admonition has been collapsed,
meaning you can add longer form content here,
without it taking up too much space on the page.
:::

备注

This admonition has been collapsed, meaning you can add longer form content here, without it taking up too much space on the page.

4.  Other Containers (grids, tabs, cards, etc.)#

Using the colon_fence extension, content block can be wrapped in containers with a custom CSS class.

:::bg-primary
This is a container with a custom CSS class.

- It can contain multiple blocks
:::

This is a container with a custom CSS class.

  • It can contain multiple blocks

Using the sphinx-design extension, it is also possible to create beautiful, screen-size responsive web-components.

:::{card} Card Title
Header
^^^
Card content
+++
Footer
:::

Header

Card Title

Card content

Footer

::::{tab-set}

:::{tab-item} Label1
Content 1
:::

:::{tab-item} Label2
Content 2
:::

::::

Content 1

Content 2