1
0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-12-25 13:54:58 +01:00
mkdocs-material/docs/reference/abbreviations.md

100 lines
2.3 KiB
Markdown
Raw Normal View History

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
*[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
*[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
*[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