Skip to content

Abbreviations

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
  - pymdownx.snippets

See additional configuration options:

Usage

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.

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

The Snippets extension can be used to implement a simple glossary by moving all abbreviations in a dedicated file1, and embedding it with the --8<-- notation at the end of each document.

Example:

The HTML specification is maintained by the W3C.

--8<-- "includes/abbreviations.md"
*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

Result:

The HTML specification is maintained by the W3C.


  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. 

Back to top