Tooltips

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

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:

• Abbreviations
• Attribute Lists
• Snippets

Improved tooltips

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:

• 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

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:

[Hover me](https://example.com "I'm a tooltip!")

Tooltips can also be added to link references:

[Hover me][example]

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

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

:material-information-outline:{ title="Important information" }

Adding abbreviations

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:

The HTML specification is maintained by the W3C.

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

Adding a glossary

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

[^1]: It's highly recommended to put the Markdown file containing the abbreviations outside of the docs folder (here, a folder with the name includes is used), as MkDocs might otherwise complain about an unreferenced file.

=== ":octicons-file-code-16: includes/abbreviations.md"

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

=== ":octicons-file-code-16: mkdocs.yml"

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

!!! tip

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

```` yaml
watch:
  - includes
````