Added documentation for abbreviations

docs/customization.md

@@ -17,7 +17,7 @@ files to the `docs` directory.
 
   [1]: https://www.mkdocs.org
 
-### Additional stylesheets
+### Additional CSS
 
 If you want to tweak some colors or change the spacing of certain elements,
 you can do this in a separate stylesheet. The easiest way is by creating a

docs/reference/abbreviations.md

@@ -0,0 +1,99 @@
+---
+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
+```
+
+_Result_:
+
+The HTML specification is maintained by the W3C.
+
+*[HTML]: Hyper Text Markup Language
+*[W3C]:  World Wide Web Consortium
+
+  [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_:
+
+=== "docs/path/to/a/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._
+
+  [6]: #snippets

docs/reference/admonitions.md

@@ -396,5 +396,5 @@ _Result_:
     massa, nec semper lorem quam in massa.
 
   [9]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
-  [10]: ../customization.md#additional-stylesheets
+  [10]: ../customization.md#additional-css
   [11]: https://facelessuser.github.io/pymdown-extensions/extensions/details/

docs/reference/code-blocks.md

@@ -110,7 +110,7 @@ them at your own risk._
   [3]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
   [4]: https://python-markdown.github.io/extensions/code_hilite/
   [5]: https://facelessuser.github.io/pymdown-extensions/
-  [6]: ../customization.md#additional-stylesheets
+  [6]: ../customization.md#additional-css
   [7]: ../customization.md#additional-javascript
   [8]: https://highlightjs.org/
   [9]: https://cdnjs.com/libraries/highlight.js/

docs/reference/icons-emojis.md

@@ -154,7 +154,7 @@ _Result_:
 
   [17]: #attribute-list
   [18]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style
-  [19]: ../customization.md#additional-stylesheets
+  [19]: ../customization.md#additional-css
 
 #### with animations
 

docs/setup/changing-the-colors.md

@@ -272,7 +272,7 @@ variables.
 
   [12]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
   [13]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
-  [14]: ../customization.md#additional-stylesheets
+  [14]: ../customization.md#additional-css
 
 
 ### Custom color schemes

material/assets/manifest.json

@@ -5,8 +5,8 @@
   "assets/javascripts/vendor.js.map": "assets/javascripts/vendor.11f47dfd.min.js.map",
   "assets/javascripts/worker/search.js": "assets/javascripts/worker/search.5eca75d3.min.js",
   "assets/javascripts/worker/search.js.map": "assets/javascripts/worker/search.5eca75d3.min.js.map",
-  "assets/stylesheets/main.css": "assets/stylesheets/main.4dd2dd8d.min.css",
-  "assets/stylesheets/main.css.map": "assets/stylesheets/main.4dd2dd8d.min.css.map",
+  "assets/stylesheets/main.css": "assets/stylesheets/main.92f59ee9.min.css",
+  "assets/stylesheets/main.css.map": "assets/stylesheets/main.92f59ee9.min.css.map",
   "assets/stylesheets/overrides.css": "assets/stylesheets/overrides.2b41d529.min.css",
   "assets/stylesheets/overrides.css.map": "assets/stylesheets/overrides.2b41d529.min.css.map",
   "assets/stylesheets/palette.css": "assets/stylesheets/palette.6a5ad368.min.css",

material/base.html

@@ -44,7 +44,7 @@
       {% endif %}
     {% endblock %}
     {% block styles %}
-      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.4dd2dd8d.min.css' | url }}">
+      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.92f59ee9.min.css' | url }}">
       {% if palette.scheme or palette.primary or palette.accent %}
         <link rel="stylesheet" href="{{ 'assets/stylesheets/palette.6a5ad368.min.css' | url }}">
       {% endif %}

mkdocs.yml

@@ -103,6 +103,7 @@ extra:
 # Extensions
 markdown_extensions:
   - markdown.extensions.admonition
+  - markdown.extensions.abbr
   - markdown.extensions.attr_list
   - markdown.extensions.def_list
   - markdown.extensions.footnotes
@@ -166,6 +167,7 @@ nav:
     - Adding a comment system: setup/adding-a-comment-system.md
     #- Adding a landing page: setup/adding-a-landing-page.md
   - Reference:
+    - Abbreviations: reference/abbreviations.md
     - Admonitions: reference/admonitions.md
     - Buttons: reference/buttons.md
     - Code blocks: reference/code-blocks.md