Skip to content
Return to: MkDocs-MaterialX Start Page

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, MaterialX for MkDocs uses a combination of Markdown extensions to enable site-wide glossaries.

Configuration⚓︎

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
    View Abbreviations

    The Extension adds the ability to add a small tooltip to an element.

  • Attribute Lists
    View Attribute Lists

    Allows HTML attributes & CSS classes to almost every MD inline & block-level element.

  • Snippets
    View Snippets

    The extension adds the ability to embed content from arbitrary files into a document.

Improved Tooltips⚓︎

Improved Tooltips

When improved tooltips are enabled, MaterialX 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⚓︎

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:

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

Afridyne Systems

Tooltips can also be added to link references:

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

Afridyne Systems (PTY) Ltd

Other Elements

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⚓︎

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

The HTML specification is maintained by the W3C.

Adding a Glossary⚓︎

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

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