工具提示

技术文档通常使用许多缩写词，这些缩写词可能需要额外的解释，特别是对于您项目的新用户。为了解决这些问题，Material for MkDocs 使用 Markdown 扩展的组合来启用全站词汇表。

配置

此配置启用缩写词，并允许构建一个简单的项目范围词汇表，从一个中央位置获取定义。在mkdocs.yml中添加以下行：

markdown_extensions:
  - abbr
  - attr_list
  - pymdownx.snippets

查看附加的配置选项：

当启用改进的工具提示时，Material for MkDocs 将浏览器的title属性的渲染逻辑替换为漂亮的小工具提示。在mkdocs.yml中添加以下行：

theme:
  features:
    - content.tooltips

现在，工具提示将呈现在以下元素中：

[Markdown 语法]允许为每个链接指定title，当启用改进的工具提示时，它将呈现为漂亮的工具提示。使用以下行将工具提示添加到链接中：

带工具提示的链接，行内语法

[悬停在我上面](https://example.com "我是一个工具提示！")

工具提示也可以添加到链接引用中：

带工具提示的链接，引用语法

[悬停在我上面][example]

[example]: https://example.com "我是一个工具提示！"

对于其他所有元素，可以使用[属性列表]扩展添加title：

带工具提示的图标

:material-information-outline:{ title="重要信息" }

可以使用类似 URL 和脚注的特殊语法来定义缩写词，以*开头，紧接着用方括号括起来的术语或缩写词：

带缩写词的文本

HTML 规范由 W3C 维护。

_[HTML]: 超文本标记语言
_[W3C]: 万维网联盟

HTML 规范由 W3C 维护。

[HTML]: 超文本标记语言 [W3C]: 万维网联盟

可以使用代码片段扩展来实现一个简单的词汇表，将所有缩写词放在一个专用文件中¹，并将此文件自动附加到所有页面上，使用以下配置：

includes/abbreviations.md mkdocs.yml

*[HTML]: 超文本标记语言
*[W3C]: 万维网联盟

markdown_extensions:
  - pymdownx.snippets:
      auto_append:
        - includes/abbreviations.md

强烈建议将包含缩写词的 Markdown 文件放在docs文件夹之外（在这里，使用名为includes的文件夹），因为否则 MkDocs 可能会抱怨未引用的文件。 ↩