警告¶

¥Admonitions¶

警告，也称为标注，是包含侧边内容的绝佳选择，不会显著中断文档流程。Material for MkDocs 提供了几种不同类型的警告，并允许包含和嵌套任意内容。

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

配置¶

¥Configuration¶

此配置启用警告，允许其可折叠，并允许在警告中嵌套任意内容。将以下几行添加到mkdocs.yml中：

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

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

查看其他配置选项：

¥See additional configuration options:

警告图标¶

¥Admonition icons¶

8.3.0

¥8.3.0

每种受支持的警告类型都有一个独特的图标，可以将其更改为主题附带的任何图标，甚至可以更改为自定义图标。将以下几行添加到mkdocs.yml中：

¥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. Add the following lines to mkdocs.yml:

theme:
  icon:
    admonition:
      <type>: <icon> # (1)!

输入几个关键字，使用我们的图标搜索找到完美的图标，然后单击短代码将其复制到剪贴板：

Expand to show alternate icon sets

Octicons FontAwesome

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

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¶

警告遵循简单的语法：一个块以!!!开头，后跟一个用作类型限定符的关键字。块的内容在下一行，缩进四个空格：

¥Enter a few keywords to find the perfect icon using our icon search and click on the shortcode to copy it to your clipboard:

Admonition

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

笔记

Lorem ipsum dolor sat amet，consectetur adipiscing elit。 Nulla et euismod nulla。 Curabitur feugiat、tortor non consequat finibus、justo purus auctor Massa、nec semper lorem quam in Massa。

更改标题¶

¥Changing the title¶

默认情况下，标题将等于类型限定符的首字母大写形式。但是，可以通过在类型限定符后添加包含有效 Markdown 代码（包括链接、格式等）的引号字符串来更改它：

¥Admonitions follow a simple syntax: a block starts with !!!, followed by a single keyword used as a type qualifier. The content of the block follows on the next line, indented by four spaces:

Admonition with custom title

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

Lorem ipsum dolor sat amet，consectetur adipiscing elit。 Nulla et euismod nulla。 Curabitur feugiat、tortor non consequat finibus、justo purus auctor Massa、nec semper lorem quam in Massa。

¥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¶

您还可以在文档中包含嵌套的警告。为此，您可以使用现有的警告，并缩进所需的警告：

¥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:

Nested Admonition

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

外注

¥Phasellus posuere in sem ut cursus

Lorem ipsum dolor sat amet，consectetur adipiscing elit。 Nulla et euismod nulla。 Curabitur feugiat、tortor non consequat finibus、justo purus auctor Massa、nec semper lorem quam in Massa。

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

内在笔记

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

Lorem ipsum dolor sat amet，consectetur adipiscing elit。 Nulla et euismod nulla。 Curabitur feugiat、tortor non consequat finibus、justo purus auctor Massa、nec semper lorem quam in Massa。

¥Outer Note

删除标题¶

¥Removing the title¶

与更改标题类似，可以通过在类型限定符后直接添加空字符串来完全省略图标和标题。请注意，这不适用于可折叠块：

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

Admonition without title

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

Lorem ipsum dolor sat 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

可折叠积木¶

¥Collapsible blocks¶

当启用“详细信息”并且警告块以???而不是!!!开头时，警告将呈现为可扩展块，右侧带有一个小切换按钮：

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

Admonition, collapsible

??? 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 sat amet，consectetur adipiscing elit。 Nulla et euismod nulla。 Curabitur feugiat、tortor non consequat finibus、justo purus auctor Massa、nec semper lorem quam in Massa。

¥Similar to changing 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:

在???标记后添加+可使块展开：

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

Admonition, collapsible and initially expanded

???+ 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 sat amet，consectetur adipiscing elit。 Nulla et euismod nulla。 Curabitur feugiat、tortor non consequat finibus、justo purus auctor Massa、nec semper lorem quam in Massa。

¥When 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:

内联块¶

¥Inline blocks¶

警告也可以呈现为内联块（例如，用于侧边栏），使用inline + end修饰符将它们放置在右侧，或仅使用inline修饰符将它们放置在左侧：

¥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 end inline

乱码

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

Lorem ipsum dolor sat amet，consectetur adipiscing elit。 Nulla et euismod nulla。 Curabitur feugiat、tortor non consequat finibus、justo purus auctor Massa、nec semper lorem quam in Massa。

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

使用inline end向右对齐（对于 rtl 语言则向左对齐）。

¥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:

乱码

¥Lorem ipsum

Lorem ipsum dolor sat amet，consectetur adipiscing elit。 Nulla et euismod nulla。 Curabitur feugiat、tortor non consequat finibus、justo purus auctor Massa、nec semper lorem quam in Massa。

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

使用inline左对齐（对于 rtl 语言则为右对齐）。

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

重要提示：使用inline修饰符的警告必须在要放置它们的内容块之前声明。如果内容块旁边没有足够的空间来渲染警告，则警告将拉伸至视口的整个宽度，例如在移动设备视口上。

¥Lorem ipsum

支持的类型¶

¥Supported types¶

以下是 Material for MkDocs 提供的类型限定符列表，而默认类型（以及未知类型限定符的后备）是note 1 ：

¥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: 笔记
¥Use inline to align to the left (right for rtl languages).

Lorem ipsum dolor sat amet，consectetur adipiscing elit。 Nulla et euismod nulla。 Curabitur feugiat、tortor non consequat finibus、justo purus auctor Massa、nec semper lorem quam in Massa。
¥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.
abstract: 抽象的
¥Following is a list of type qualifiers provided by Material for MkDocs, whereas the default type, and thus fallback for unknown type qualifiers, is note¹:

Lorem ipsum dolor sat 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
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.

Lorem ipsum dolor sat 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
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.

Lorem ipsum dolor sat 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
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.

Lorem ipsum dolor sat 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
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.

Lorem ipsum dolor sat 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
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.

Lorem ipsum dolor sat 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
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.

Lorem ipsum dolor sat 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
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.

Lorem ipsum dolor sat 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
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.

Lorem ipsum dolor sat 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
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.

Lorem ipsum dolor sat 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
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.

Lorem ipsum dolor sat 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

定制¶

¥Customization¶

经典警句¶

¥Classic admonitions¶

在8.5.6版本之前，警告的外观略有不同：

¥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

Lorem ipsum dolor sat amet，consectetur adipiscing elit。 Nulla et euismod nulla。 Curabitur feugiat、tortor non consequat finibus、justo purus auctor Massa、nec semper lorem quam in Massa。

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

如果要恢复此外观，请将以下 CSS 添加到附加样式表：

¥Prior to version 8.5.6, admonitions had a slightly different appearance:

docs/stylesheets/extra.css mkdocs.yml

.md-typeset .admonition,
.md-typeset details {
  border-width: 0;
  border-left-width: 4px;
}

extra_css:
  - stylesheets/extra.css

自定义警告¶

¥Custom admonitions¶

如果您想添加自定义警告类型，只需一种颜色和一个*.svg图标即可。从.icons文件夹复制图标代码，并将以下 CSS 添加到附加样式表：

¥Note

docs/stylesheets/extra.css mkdocs.yml

: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,
.md-typeset details.pied-piper {
  border-color: rgb(43, 155, 70);
}
.md-typeset .pied-piper > .admonition-title,
.md-typeset .pied-piper > summary {
  background-color: rgba(43, 155, 70, 0.1);
}
.md-typeset .pied-piper > .admonition-title::before,
.md-typeset .pied-piper > summary::before {
  background-color: rgb(43, 155, 70);
  -webkit-mask-image: var(--md-admonition-icon--pied-piper);
          mask-image: var(--md-admonition-icon--pied-piper);
}

extra_css:
  - stylesheets/extra.css

应用自定义后，您可以使用自定义警告类型：

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

Admonition with custom type

!!! pied-piper "Pied Piper"

    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.

花衣魔笛手

¥If you want to restore this appearance, add the following CSS to an additional style sheet:

Lorem ipsum dolor sat amet，consectetur adipiscing elit。 Nulla et euismod nulla。 Curabitur feugiat、tortor non consequat finibus、justo purus auctor Massa、nec semper lorem quam in Massa。

¥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 following CSS to an additional style sheet:

以前，一些受支持的类型定义了多个限定符。例如，作者可以使用summary或tldr作为替代限定符来呈现抽象警告。由于这增加了 Material for MkDocs 附带的 CSS 的大小，因此额外的类型限定符现在已全部弃用，并将在下一个主要版本中移除。升级指南中也会提到这一点。↩