Abbreviations¶

Technical documentation often incurs the usage of a lot of 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¶

Abbreviations¶

Source · Extension

The Abbreviations extension, which is part of the standard Markdown library, allows to add additional content to parts of the text which are then shown on hover, e.g. for glossaries:

markdown_extensions:
  - abbr

Snippets¶

The Snippets extension, which is part of Python Markdown Extensions, allows to insert content from other files or other, regular content, and can be enabled via mkdocs.yml:

markdown_extensions:
  - pymdownx.snippets

Usage¶

Adding abbreviations¶

When the Abbreviations extension is enabled, abbreviations can be defined with a special syntax similar to URLs and footnotes at any point in the Markdown document.

Example:

The HTML specification is maintained by the W3C.

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

Result:

The HTML specification is maintained by the W3C.

Adding a glossary¶

When Snippets is enabled, content from other files can be embedded, which is especially useful to include abbreviations from a central file – a glossary – and embed them into any other file.

Example:

docs/page.md

The HTML specification is maintained by the W3C.

--8<-- "includes/abbreviations.md"

includes/abbreviations.md

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

Result:

The HTML specification is maintained by the W3C.

Remember to locate the Markdown file containing the definitions outside of the docs folder (here includes is used), or MkDocs may complain about an unreferenced file.