Skip to content

工具提示

¥Tooltips

技术文档中经常会用到许多缩写词，这些缩写词可能需要额外的解释，尤其是对于项目的新用户。针对这些问题，Material for MkDocs 结合使用 Markdown 扩展来提供全站通用的词汇表。

¥Technical documentation often incurs the usage of many acronyms, which may need additional explanation, especially for new user of your project. For these matters, Material for MkDocs uses a combination of Markdown extensions to enable site-wide glossaries.

配置

¥Configuration

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

¥This configuration enables abbreviations and allows to build a simple project-wide glossary, sourcing definitions from a central location. Add the following line to mkdocs.yml:

markdown_extensions:
  - abbr
  - attr_list
  - pymdownx.snippets

查看其他配置选项：

¥See additional configuration options:

改进的工具提示

¥Improved tooltips

9.5.0

¥9.5.0

启用改进的工具提示后，Material for MkDocs 会将浏览器的title属性渲染逻辑替换为精美的小工具提示。将以下几行添加到mkdocs.yml中：

¥When improved tooltips are enabled, Material for MkDocs replaces the browser's rendering logic for title attribute with beautiful little tooltips. Add the following lines to mkdocs.yml:

theme:
  features:
    - content.tooltips

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

¥Now, tooltips will be rendered for the following elements:

  • 内容– 带有title 、永久链接和代码复制按钮的元素

    ¥Content – elements with a title, permalinks and code copy button

  • 标题– 主页按钮、标题标题、调色板开关和存储库链接

    ¥Header – home button, header title, color palette switch and repository link

  • 导航– 用省略号缩短的链接，即...

    ¥Navigation – links that are shortened with ellipsis, i.e. ...

用法

¥Usage

添加工具提示

¥Adding tooltips

Markdown 语法允许为每个链接指定title ，当启用改进的工具提示时，标题将呈现为美观的工具提示。使用以下几行代码为链接添加工具提示：

¥The Markdown syntax allows to specify a title for each link, which will render as a beautiful tooltip when improved tooltips are enabled. Add a tooltip to a link with the following lines:

Link with tooltip, inline syntax
[Hover me](https://example.com "I'm a tooltip!")

将鼠标悬停在我身上

¥Hover me

还可以将工具提示添加到链接引用：

¥Tooltips can also be added to link references:

Link with tooltip, reference syntax
[Hover me][example]

  [example]: https://example.com "I'm a tooltip!"

将鼠标悬停在我身上

¥Hover me

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

¥For all other elements, a title can be added by using the Attribute Lists extension:

Icon with tooltip
:material-information-outline:{ title="Important information" }

添加缩写

¥Adding abbreviations

可以使用类似于 URL 和脚注的特殊语法来定义缩写，以*开头，紧接着在方括号中附加要关联的术语或首字母缩略词：

¥Abbreviations can be defined by using a special syntax similar to URLs and footnotes, starting with a * and immediately followed by the term or acronym to be associated in square brackets:

Text with abbreviations
The HTML specification is maintained by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

HTML 规范由 W3C 维护。

¥The HTML specification is maintained by the W3C.

添加词汇表

¥Adding a glossary

Snippets扩展可用于实现简单的词汇表，通过将所有缩写移动到专用文件1中，并使用以下配置将该文件自动附加到所有页面：

¥The Snippets extension can be used to implement a simple glossary by moving all abbreviations in a dedicated file1, and auto-append this file to all pages with the following configuration:

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

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

提示

¥Tip

当使用docs文件夹外的专用文件时，将父目录添加到watch文件夹列表中，以便当词汇表文件更新时，运行mkdocs serve时会自动重新加载项目。

¥When using a dedicated file outside of the docs folder, add the parent directory to the list of watch folders so that when the glossary file is updated, the project is automatically reloaded when running mkdocs serve.

watch:
  - includes

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