2.5 KiB
| template |
|---|
| overrides/main.html |
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
:octicons-file-code-24: Source · :octicons-workflow-24: 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.
*[HTML]: Hyper Text Markup Language *[W3C]: World Wide Web Consortium
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"
```` markdown
The HTML specification is maintained by the W3C.
--8<-- "includes/abbreviations.md"
````
=== "includes/abbreviations.md"
```` markdown
*[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.