2020-09-19 14:34:40 +02:00
|
|
|
|
---
|
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
|
|
The [Abbreviations][1] 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:
|
|
|
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
|
markdown_extensions:
|
|
|
|
|
|
- abbr
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
[1]: https://python-markdown.github.io/extensions/abbreviations/
|
|
|
|
|
|
|
|
|
|
|
|
### Snippets
|
|
|
|
|
|
|
|
|
|
|
|
The [Snippets][2] extension, which is part of [Python Markdown Extensions][3],
|
|
|
|
|
|
allows to __insert content from other files__ or other, regular content, and can
|
|
|
|
|
|
be enabled via `mkdocs.yml`:
|
|
|
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
|
markdown_extensions:
|
|
|
|
|
|
- pymdownx.snippets
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
[2]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
|
|
|
|
|
|
[3]: https://facelessuser.github.io/pymdown-extensions/
|
|
|
|
|
|
|
|
|
|
|
|
## Usage
|
|
|
|
|
|
|
|
|
|
|
|
### Adding abbreviations
|
|
|
|
|
|
|
|
|
|
|
|
When the [Abbreviations][4] extension is enabled, abbreviations can be defined
|
|
|
|
|
|
with a special syntax similar to URLs and [footnotes][5] at any point in the
|
|
|
|
|
|
Markdown document.
|
|
|
|
|
|
|
|
|
|
|
|
_Example_:
|
|
|
|
|
|
|
|
|
|
|
|
``` markdown
|
|
|
|
|
|
The HTML specification is maintained by the W3C.
|
|
|
|
|
|
|
|
|
|
|
|
*[HTML]: Hyper Text Markup Language
|
2020-09-19 16:19:18 +02:00
|
|
|
|
*[W3C]: World Wide Web Consortium
|
2020-09-19 14:34:40 +02:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
_Result_:
|
|
|
|
|
|
|
|
|
|
|
|
The HTML specification is maintained by the W3C.
|
|
|
|
|
|
|
|
|
|
|
|
*[HTML]: Hyper Text Markup Language
|
2020-09-19 16:19:18 +02:00
|
|
|
|
*[W3C]: World Wide Web Consortium
|
2020-09-19 14:34:40 +02:00
|
|
|
|
|
|
|
|
|
|
[4]: #abbreviations_1
|
|
|
|
|
|
[5]: footnotes.md
|
|
|
|
|
|
|
|
|
|
|
|
### Adding a glossary
|
|
|
|
|
|
|
|
|
|
|
|
When [Snippets][6] 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_:
|
|
|
|
|
|
|
2020-09-20 11:24:46 +02:00
|
|
|
|
=== "docs/page.md"
|
2020-09-19 14:34:40 +02:00
|
|
|
|
|
|
|
|
|
|
```` markdown
|
|
|
|
|
|
The HTML specification is maintained by the W3C.
|
|
|
|
|
|
|
|
|
|
|
|
--8<-- "includes/abbreviations.md"
|
|
|
|
|
|
````
|
|
|
|
|
|
|
|
|
|
|
|
=== "includes/abbreviations.md"
|
|
|
|
|
|
|
|
|
|
|
|
```` markdown
|
|
|
|
|
|
*[HTML]: Hyper Text Markup Language
|
2020-09-19 16:19:18 +02:00
|
|
|
|
*[W3C]: World Wide Web Consortium
|
2020-09-19 14:34:40 +02:00
|
|
|
|
````
|
|
|
|
|
|
|
|
|
|
|
|
_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._
|
|
|
|
|
|
|
|
|
|
|
|
[6]: #snippets
|
