跳转至

Admonitions 警示块

警示框，又称提示框，是一种非常适合在不中断文档流的情况下包含附加内容的工具。Material for MkDocs 提供了多种类型的警示框，并允许在其中嵌套任意内容。

使用方法

警示框使用简单的语法：块以 !!! 开始，后跟一个作为类型限定符的关键字。块内容紧接在下一行，并缩进四个空格。

!!! note

    这是没有设置标题的 note 类型警示块。

Note

这是没有设置标题的 note 类型警示块。

修改标题

在默认情况下，标题会显示为警示框的类型。但你可以通过在类型限定符后添加带引号的字符串来修改标题(支持有效的 Markdown 语法，包括链接、格式化等)。

!!! note "这里是[标题](#)"

    这是设置了标题的 note 类型警示块，
    你可以在标题里任意发挥，例如加一个超链接等。

这里是标题

这是设置了标题的 note 类型警示块， 你可以在标题里任意发挥，例如加一个超链接等。

删除标题

与修改标题类似，你还可以完全省略警示块的标题和图标。只需要在类型限定符后添加一个空字符串即可。请注意，这种方法不适用于后面提到的可折叠警示块。

!!! note ""

    与修改标题类似，可以通过在类型限定符后
    添加空字符串完全省略图标和标题。但请注意，这在折叠块中无效。

与修改标题类似，可以通过在类型限定符后 添加空字符串完全省略图标和标题。但请注意，这在折叠块中是无效的。

可折叠块

启用 Details 扩展后，若警示框块以 ??? 代替 !!!，则警示框会被渲染为一个可折叠的块，同时右侧带有一个小型切换按钮，用于切换折叠状态。

??? note

    启用 Details 扩展后，将警示块的起始标记从 !!! 更改为 ???，
    即可将其渲染为一个可折叠块，并在块的右侧显示一个小型折叠切换按钮。
Note

启用 Details 扩展后，将警示块的起始标记 从 !!! 更改为 ???，即可将其渲染为一个可折叠块， 并在块的右侧显示一个小型折叠切换按钮。

自动展开

在 ??? 后面加一个 + 即可将折叠块默认设置为展开状态。

???+ note

    在 ??? 后面加一个 + 即可将折叠块默认设置为展开状态。
Note

在 ??? 后面加一个 + 即可将折叠块默认设置为展开状态。

内联块

警示框也可以渲染为行内块(你可以将其用于侧边栏等场合)。通过使用 inline 和 end 修饰符，可以将警示框分别渲染在其他元素的左侧或右侧。 重要提示: 使用 inline 修饰符的警示框必须在想要放置其旁边的内容块之前声明。如果空间不足，比如在移动端查看网页，警示框将被强制拉伸至视窗的完整宽度。

右侧内联块

这是一个通过 inline end 修饰的内联块， 因此该块会被渲染到文字右侧，这可以用于在侧边栏显示信息。

!!! info inline end "右侧内联块"

    这是一个通过 inline end 修饰的内联块，
    因此该块会被渲染到文字右侧，
    这可以用于在侧边栏显示信息。

左侧内联块

这是一个只通过 inline 修饰的内联块， 因此该块会被渲染到文字左侧，这同样可以用于在侧边栏显示信息。

!!! info inline "左侧内联块"

    这是一个只通过 inline 修饰的内联块，
    因此该块会被渲染到文字左侧，
    这同样可以用于在侧边栏显示信息。

支持类型

以下是 Material for MkDocs 支持的类型限定符，默认类型设置为 note:

note

Note

这是一个 note 类型的警示块。
圣人无常师。孔子师郯子、苌弘、师襄、老聃。郯子之徒，其贤不及孔子。孔子曰：三人行，则必有我师。是故弟子不必不如师，师不必贤于弟子，闻道有先后，术业有专攻，如是而已。—— 韩愈《师说》

abstract

Abstract

这是一个 abstract 类型的警示块。
圣人无常师。孔子师郯子、苌弘、师襄、老聃。郯子之徒，其贤不及孔子。孔子曰：三人行，则必有我师。是故弟子不必不如师，师不必贤于弟子，闻道有先后，术业有专攻，如是而已。—— 韩愈《师说》

info

Info

这是一个 info 类型的警示块。
圣人无常师。孔子师郯子、苌弘、师襄、老聃。郯子之徒，其贤不及孔子。孔子曰：三人行，则必有我师。是故弟子不必不如师，师不必贤于弟子，闻道有先后，术业有专攻，如是而已。—— 韩愈《师说》

tip

Tip

这是一个 tip 类型的警示块。
圣人无常师。孔子师郯子、苌弘、师襄、老聃。郯子之徒，其贤不及孔子。孔子曰：三人行，则必有我师。是故弟子不必不如师，师不必贤于弟子，闻道有先后，术业有专攻，如是而已。—— 韩愈《师说》

success

Success

这是一个 success 类型的警示块。
圣人无常师。孔子师郯子、苌弘、师襄、老聃。郯子之徒，其贤不及孔子。孔子曰：三人行，则必有我师。是故弟子不必不如师，师不必贤于弟子，闻道有先后，术业有专攻，如是而已。—— 韩愈《师说》

question

Question

这是一个 question 类型的警示块。
圣人无常师。孔子师郯子、苌弘、师襄、老聃。郯子之徒，其贤不及孔子。孔子曰：三人行，则必有我师。是故弟子不必不如师，师不必贤于弟子，闻道有先后，术业有专攻，如是而已。—— 韩愈《师说》

warning

Warning

这是一个 warning 类型的警示块。
圣人无常师。孔子师郯子、苌弘、师襄、老聃。郯子之徒，其贤不及孔子。孔子曰：三人行，则必有我师。是故弟子不必不如师，师不必贤于弟子，闻道有先后，术业有专攻，如是而已。—— 韩愈《师说》

failure

Failure

这是一个 failure 类型的警示块。
圣人无常师。孔子师郯子、苌弘、师襄、老聃。郯子之徒，其贤不及孔子。孔子曰：三人行，则必有我师。是故弟子不必不如师，师不必贤于弟子，闻道有先后，术业有专攻，如是而已。—— 韩愈《师说》

danger

Danger

这是一个 danger 类型的警示块。
圣人无常师。孔子师郯子、苌弘、师襄、老聃。郯子之徒，其贤不及孔子。孔子曰：三人行，则必有我师。是故弟子不必不如师，师不必贤于弟子，闻道有先后，术业有专攻，如是而已。—— 韩愈《师说》

bug

Bug

这是一个 bug 类型的警示块。
圣人无常师。孔子师郯子、苌弘、师襄、老聃。郯子之徒，其贤不及孔子。孔子曰：三人行，则必有我师。是故弟子不必不如师，师不必贤于弟子，闻道有先后，术业有专攻，如是而已。—— 韩愈《师说》

example

Example

这是一个 example 类型的警示块。
圣人无常师。孔子师郯子、苌弘、师襄、老聃。郯子之徒，其贤不及孔子。孔子曰：三人行，则必有我师。是故弟子不必不如师，师不必贤于弟子，闻道有先后，术业有专攻，如是而已。—— 韩愈《师说》

quote

Quote

这是一个 quote 类型的警示块。
圣人无常师。孔子师郯子、苌弘、师襄、老聃。郯子之徒，其贤不及孔子。孔子曰：三人行，则必有我师。是故弟子不必不如师，师不必贤于弟子，闻道有先后，术业有专攻，如是而已。—— 韩愈《师说》

自定义设置

恢复到旧版本

在 8.5.6 版本之前，警示块的外观与现在的外观略有区别。具体对比可以看下图。

如果你想恢复到旧版的外观，可以将以下的 CSS 添加到一个额外的样式表中，并在 mkdocs.yml 中引用它即可。

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

extra_css:
  - stylesheets/extra.css

自定义样式

参见 Custom admonitions.