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.
This configuration enables abbreviations and allows to build a simple project-wide glossary, sourcing definitions from a central location. Add the following line to
See additional configuration options:
Sponsors only · insiders-4.15.0 · Experimental
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
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.
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:
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:
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
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:
It's highly recommended to put the Markdown file containing the abbreviations outside of the
docsfolder (here, a folder with the name
includesis used), as MkDocs might otherwise complain about an unreferenced file. ↩