Material for MkDocs Admonitions 完全指南：从基本语法到自定义扩展

Material for MkDocs Admonitions 完全指南：从基本语法到自定义扩展

【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material

Admonitions（又称 call-outs、提示框）是 Material for MkDocs 中最常用的文档排版工具，用于在不打断正文阅读流的前提下插入补充信息。本文以 docs/reference/admonitions.md 为核心，完整覆盖配置启用、12 种内置类型、可折叠与行内块等全部用法，并结合仓库内 SCSS 源码（src/templates/assets/stylesheets/main/extensions/markdown/_admonition.scss）与 Details 样式 讲解其实现原理，最后给出经典外观还原与自定义 admonition 类型的完整 CSS 方案。

什么是 Admonitions

Admonitions 是嵌入在文档正文中的醒目提示块，适合承载"注意事项""补充说明""示例代码"等侧边内容，而不会显著打断文档的阅读节奏。Material for MkDocs 提供了多种不同类型的 admonitions，并允许在块内包含和嵌套任意内容——段落、代码块、表格、列表，乃至其他 admonitions。

本仓库自己的文档就大量使用这一特性，例如 docs/reference/admonitions.md 中所有类型示例、docs/setup/extensions/python-markdown.md 中的配置说明，都是通过 admonitions 渲染出来的。

启用与配置

Admonitions 的基础能力由 Python-Markdown 的admonition扩展提供，配合 PyMdown Extensions 的details与superfences扩展，还可以让提示块支持折叠，并嵌套任意 Markdown 内容（尤其是代码块与标签页）。

在项目的mkdocs.yml中添加以下配置：

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

三个扩展的分工如下：

在本仓库的 mkdocs.yml 中，admonition扩展已在markdown_extensions一节启用。

为每种类型配置专属图标

从主题版本 8.3.0 起，每一种受支持的 admonition 类型都有独立的图标。默认图标定义在主题 SCSS 的$admonitions映射表中（见 src/templates/assets/stylesheets/main/extensions/markdown/_admonition.scss），例如note对应pencil-circle图标，warning对应alert图标。

你也可以将任意类型替换为主题自带的图标，甚至是自定义图标。在mkdocs.yml中配置：

theme: icon: admonition: <type>: <icon>

其中<type>替换为下文 支持的类型 中的类型名，<icon>替换为图标短代码。要找到心仪的图标，可以借助图标搜索功能：输入几个关键词，点击搜索结果的短代码即可复制到剪贴板。

下面是两套备选的完整图标方案。

=== "Octicons"

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

=== "FontAwesome"

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

图标（.svg文件）需要存在于主题的图标目录中才能被引用。自定义图标可以放入自己的.icons目录，具体方法参见自定义图标。

基本用法

Admonitions 的语法非常简洁：块以!!!开头，紧跟一个关键字作为类型限定符，块内容从下一行开始，缩进四个空格：

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

从底层实现看，主题将admonition扩展生成的<div class="admonition">元素样式化为提示框：带 1.5px 边框、圆角、轻微阴影，并设置了page-break-inside: avoid避免打印时跨页（见 _admonition.scss）。

修改标题

默认情况下，提示框的标题就是类型限定符的首字母大写形式（如note→Note）。如果想自定义标题，可以在类型限定符后添加一个包含合法 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.

嵌套提示块

在提示块内部继续使用!!!并逐级增加缩进，即可实现嵌套：

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

从样式上，主题对嵌套的.admonition额外设置了margin-top: 1em; margin-bottom: 1em;，以保证多级嵌套时垂直间距依然协调（见 _admonition.scss）。

移除标题

与修改标题类似，在类型限定符后紧跟空字符串""，即可同时隐藏标题和图标：

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

注意：移除标题的写法对可折叠块不生效——折叠块必须有标题才能显示展开/收起控件。

可折叠块

启用pymdownx.details后，把起始标记从!!!换成???，提示块就会渲染为带右侧小箭头的可展开/收起区域：

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

在???后追加一个+（即???+），则初始状态为展开：

???+ 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.

实现原理：pymdownx.details会把折叠提示块渲染为 HTML 的<details>/<summary>元素。主题 SCSS 中details直接@extend .admonition继承提示框样式，summary则@extend .admonition-title继承标题样式，并在summary::after上用mask-image绘制一个旋转的箭头图标——块展开时（details[open]）箭头旋转 90 度（见 _details.scss）。同时主题隐藏了浏览器原生的::marker与::-webkit-details-marker标记，保证外观统一。

行内块

Admonitions 还可以渲染为行内块（例如用作侧边栏）。使用inline end修饰符让提示框浮动到右侧（RTL 语言下为左侧），只使用inline修饰符则浮动到左侧（RTL 语言下为右侧）：

=== ":octicons-arrow-right-16: inline end"

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

=== ":octicons-arrow-left-16: inline"

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

使用行内修饰符时有两点必须注意：

1. 声明顺序：使用inline修饰符的提示块必须声明在其旁边正文内容的前面；
2. 空间不足时回退：如果视口没有足够空间把提示块排到正文旁边（例如在移动端），提示块会自动拉伸到视口的完整宽度。

支持的类型

Material for MkDocs 内置了 12 种类型限定符。默认类型是note，当遇到未知类型限定符时也会回退到note的样式。下表列出了全部类型、对应图标与边框色（取自 _admonition.scss 的$admonitions映射）：

以下为每种类型的完整渲染效果：

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

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

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

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

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

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

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

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

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

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

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

关于旧版类型限定符的弃用说明：旧版本中部分类型曾支持多个限定符，例如用summary或tldr渲染abstract。由于这会导致主题 CSS 体积增大，这些额外限定符现已全部弃用，并将在下一个大版本中移除，升级时请留意升级指南。

自定义

恢复经典外观

在 8.5.6 之前，admonitions 的外观略有不同——边框只有左侧的 4px 竖线，而非如今的全边框样式。如果你想恢复这一经典外观，可以在额外样式表中添加以下 CSS：

=== "docs/stylesheets/extra.css"

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

=== "mkdocs.yml"

``` yaml extra_css: - stylesheets/extra.css ```

经典外观参考（!!! classic）：

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

添加自定义类型

添加一种全新的 admonition 类型只需要两样东西：一个颜色和一个*.svg图标。

1. 从主题的图标目录中复制你选中的图标 SVG 代码；
2. 在额外样式表中定义该类型的图标 CSS 变量、边框颜色与标题背景色；
3. 通过mkdocs.yml的extra_css引入样式表。

以下示例注册了一个名为pied-piper的自定义类型，强调色为绿色（rgb(43, 155, 70)）：

=== "docs/stylesheets/extra.css"

``` css :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); } ```

=== "mkdocs.yml"

``` yaml extra_css: - stylesheets/extra.css ```

应用后即可直接使用该自定义类型：

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

渲染效果：

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

原理说明：主题正是用--md-admonition-icon--<type>这样的 CSS 变量来驱动每种类型的图标——默认类型的图标变量由 SCSS 在:root中通过svg-load()批量注入（见 _admonition.scss），标题前的图标则通过.admonition-title::before的mask-image属性绘制（见 _admonition.scss）。因此自定义类型时，只要在:root中定义同名变量，并配套给出边框色、标题背景色和图标遮罩规则即可，无需修改任何主题文件。

进阶技巧与注意事项

• 嵌套代码块：结合pymdownx.superfences，可以在提示块内放入带语言高亮的代码块、标签页（如本页配置示例）甚至表格，嵌套内容的缩进要逐级递增；
• 打印友好：主题为提示块设置了page-break-inside: avoid并在打印时去除阴影（见 _admonition.scss），因此在文档导出为 PDF 时提示块不会跨页断裂、也不会残留阴影；
• 键盘可达性：折叠块（details/summary）对键盘设备显示焦点轮廓、对指针设备隐藏轮廓，并且隐藏了原生 marker，保证可访问性（见 _details.scss）；
• 行内块的声明顺序：inline/inline end提示块必须写在相邻正文之前，且移动端等窄视口下会自动占满整行宽度。

总结

Admonitions 是 Material for MkDocs 排版能力中性价比最高的一环：一行mkdocs.yml配置即可启用，!!!/???/???+三种起始标记分别对应静态、折叠与默认展开三种形态，12 种内置类型覆盖了注释、摘要、提示、警告、示例等绝大多数文档场景，而图标替换与自定义类型又让它在视觉上完全贴合你的文档风格。掌握本文从语法到源码的原理，你就可以在自己的文档中自如地组织信息层次，让说明类内容既醒目又不打断阅读流。

【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material