注释¶

Material for MkDocs 的一大旗舰功能是能够注入注释——这些小标记可以几乎在文档的任何地方添加，并在点击或键盘聚焦时展开包含任意 Markdown 的工具提示。

配置¶

此配置允许将注释添加到所有行内和块级元素，以及代码块，并且可以将注释嵌套在一起。将以下行添加到 mkdocs.yml：

markdown_extensions:
  - attr_list
  - md_in_html
  - pymdownx.superfences

查看其他配置选项：

• 属性列表
• HTML 中的 Markdown
• SuperFences

注释图标¶

9.2.0

注释图标可以更改为主题中捆绑的任何图标，甚至是 自定义图标，例如 material/arrow-right-circle:。只需将以下行添加到 mkdocs.yml：

theme:
  icon:
    annotation: material/arrow-right-circle # (1)!

1. 输入几个关键词以使用我们的 图标搜索 找到完美的图标，并点击短代码将其复制到剪贴板：

一些流行的选择：

• - material/plus-circle
• - material/circle-medium
• - material/record-circle
• - material/arrow-right-circle
• - material/arrow-right-circle-outline
• - material/chevron-right-circle
• - material/star-four-points-circle
• - material/plus-circle-outline

使用¶

使用注释¶

9.2.0

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

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

1.  :man_raising_hand: 我是一个注释！我可以包含 `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: 我也是一个注释！

在警告中¶

警告 的标题和正文也可以通过在类型限定符后添加 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: 我也是一个注释！

在内容标签中¶

内容标签可以通过将 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: 我也是一个注释！

在其他所有地方¶

属性列表 扩展是将注释添加到大多数元素的关键成分，但它有一些 限制。不过，始终可以利用 HTML 中的 Markdown 扩展，用 div 和 annotate 类包装任意元素：

<div class="annotate" markdown>

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

</div>

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

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