Skip to content

注解

Material for MkDocs的主要特点之一是能够插入注解-小标记，几乎可以添加在文档的任何地方，并在单击或键盘焦点时展开包含任意Markdown内容的工具提示。

配置

此配置允许将注解添加到所有内联和块级元素以及代码块中，并且可以嵌套注解。将以下行添加到mkdocs.yml文件中：

markdown_extensions:
  - attr_list
  - md_in_html
  - pymdownx.superfences

查看额外的配置选项：

使用方法

使用注解

9.2.0b0 · 实验性

注解由两部分组成：标记，可以放置在标记为annotate类的块中的任何位置，以及位于包含标记的块下方的列表中的内容：

带注解的文本
Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
{ .annotate }

1.  :man_raising_hand: 我是一个注解！我可以包含`code`、__格式化文本__、图像等等，基本上可以用Markdown表达的任何内容。

Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.

  1. 🙋‍♂️ 我是一个注解！我可以包含code、格式化文本、图像等等，基本上可以用Markdown表达的任何内容。

注意，annotate类只能添加到最外层的块中。所有嵌套元素可以使用相同的列表来定义注解，除非注解本身是嵌套的。

在注解中嵌套

当启用SuperFences时，可以通过将annotate类添加到承载注解内容的列表项中来将注解嵌套在注解中，重复此过程：

带有嵌套注解的文本
Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
{ .annotate }

1.  :man_raising_hand: 我是一个注解！ (1)
    { .annotate }

    1.  :woman_raising_hand: 我也是一个注解！

Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.

  1. 🙋‍♂️ 我是一个注解！ (1)

    1. 🙋‍♀️ 我也是一个注解！

在警示中

警示的标题和内容也可以通过在类型限定符之后添加annotate修饰符来承载注解，类似于内联块的工作方式：

带有注解的警示
!!! note annotate "Phasellus posuere in sem ut cursus (1)"

    Lorem ipsum dolor sit amet, (2) consectetur adipiscing elit. Nulla et
    euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
    purus auctor massa, nec semper lorem quam in massa.

1.  :man_raising_hand: 我是一个注解！
2.  :woman_raising_hand: 我也是一个注解！

Phasellus posuere in sem ut cursus (1)

Lorem ipsum dolor sit amet, (2) consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

  1. 🙋‍♂️ 我是一个注解！
  2. 🙋‍♀️ 我也是一个注解！

在内容选项卡中

通过将annotate类添加到专用内容选项卡的块（而不是容器）中，内容选项卡可以承载注解（不支持添加到容器）：

带有注解的内容选项卡
=== "选项卡1"

    Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
    { .annotate }

    1.  :man_raising_hand: 我是一个注解！

=== "选项卡2"

    Phasellus posuere in sem ut cursus (1)
    { .annotate }

    1.  :woman_raising_hand: 我也是一个注解！

Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.

  1. 🙋‍♂️ 我是一个注解！

Phasellus posuere in sem ut cursus (1)

  1. 🙋‍♀️ 我也是一个注解！

在其他所有地方

属性列表扩展是将注解添加到大多数元素的关键要素，但它有一些限制。然而，始终可以利用HTML中的Markdown扩展将任意元素用具有annotate类的div包装起来：

带注解的HTML
<div class="annotate" markdown>

> Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.

</div>

1.  :man_raising_hand: 我是一个注解！

Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.

  1. 🙋‍♂️ 我是一个注解！

借助这个技巧，还可以将注解添加到块引用、列表和许多不受属性列表扩展支持的其他元素中。此外，请注意，代码块遵循不同的语义。

已知限制

请注意，当前注解在数据表格中不起作用，详细信息请参见#3453，因为数据表格是可滚动元素，定位非常棘手。这可能会在未来修复。