Prepare 8.2.14 release

Author: squidfunk

CHANGELOG

@@ -1,3 +1,12 @@
+mkdocs-material-8.2.14+insiders-4.15.0 (2022-05-08)
+
+  * Added support for improved tooltips
+
+mkdocs-material-8.2.14 (2022-05-08)
+
+  * Fixed missing top right rounded border on admonition
+  * Fixed #3886: 4xx status codes not handled when using instant loading
+
 mkdocs-material-8.2.13+insiders-4.14.0 (2022-05-05)
 
   * Added Chinese language support to built-in search plugin

README.md

@@ -147,7 +147,7 @@ Material for MkDocs can be installed with `pip`:
 pip install mkdocs-material
 ```
 
-Add the following line to `mkdocs.yml`:
+Add the following lines to `mkdocs.yml`:
 
 ``` yaml
 theme:

docs/reference/abbreviations.md

@@ -1,6 +1,6 @@
 ---
 template: overrides/main.html
-icon: material/alphabet-greek
+icon: material/math-integral
 ---
 
 # MathJax

docs/reference/mathjax.md

@@ -0,0 +1,144 @@
+---
+template: overrides/main.html
+icon: material/comment-processing-outline
+---
+
+# Tooltips
+
+Material for MkDocs makes it trivial to add tooltips to links, abbreviations
+and all other elements, which allows for implementing glossary-like
+functionality, as well as small hints that are shown when the user hovers or 
+focuses an element.
+
+## Configuration
+
+This configuration enables support for tooltips and abbreviations and allows to 
+build a simple glossary, sourcing definitions from a central location. Add the 
+following lines to `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - abbr
+  - pymdownx.snippets
+```
+
+See additional configuration options:
+
+- [Abbreviations]
+- [Snippets]
+
+  [Abbreviations]: ../setup/extensions/python-markdown.md#abbreviations
+  [Snippets]: ../setup/extensions/python-markdown-extensions.md#snippets
+
+### Improved tooltips
+
+[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-4.15.0][Insiders] ·
+:octicons-beaker-24: Experimental
+
+When improved tooltips are enabled, Material for MkDocs replaces the browser's
+rendering logic for `title` attribute with beautiful little tooltips.
+Add the following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+  features:
+    - content.tooltips
+```
+
+Now, tooltips will be rendered for the following elements:
+
+- __Content__ – elements with a `title`, permalinks and copy-to-clipboard button
+- __Header__ – home button, header title, color palette switch and repository link
+- __Navigation__ – links that are shortened with ellipsis, i.e. `...`
+
+[Insiders]: ../insiders/index.md
+
+## Usage
+
+### Adding tooltips
+
+The [Markdown syntax] allows to specify a `title` for each link, which will
+render as a beautiful tooltip when [improved tooltips] are enabled. Add a 
+tooltip to an link with the following lines:
+
+``` markdown title="Link with title, inline syntax"
+[Hover me](https://example.com "I'm a tooltip!")
+```
+
+<div class="result" markdown>
+
+[Hover me](https://example.com "I'm a tooltip!")
+
+</div>
+
+Tooltips can also be added to link references:
+
+``` markdown title="Link with title, reference syntax"
+[Hover me][example]
+
+  [example]: https://example.com "I'm a tooltip!"
+```
+
+<div class="result" markdown>
+
+[Hover me](https://example.com "I'm a tooltip!")
+
+</div>
+
+  [Markdown syntax]: https://daringfireball.net/projects/markdown/syntax#link
+  [improved tooltips]: #improved-tooltips
+
+### Adding abbreviations
+
+Abbreviations can be defined by using a special syntax similar to [links] and 
+[footnotes], starting with a `*` and immediately followed by the term or
+acronym to be associated in square brackets:
+
+``` markdown title="Text with abbreviations"
+The HTML specification is maintained by the W3C.
+
+*[HTML]: Hyper Text Markup Language
+*[W3C]: World Wide Web Consortium
+```
+
+<div class="result" markdown>
+
+The HTML specification is maintained by the W3C.
+
+*[HTML]: Hyper Text Markup Language
+*[W3C]: World Wide Web Consortium
+
+</div>
+
+  [links]: #adding-tooltips
+  [footnotes]: footnotes.md
+
+### Adding a glossary
+
+The [Snippets] extension can be used to implement a simple glossary by moving
+all abbreviations in a dedicated file[^1], and embedding it with the
+[`--8<--` notation][Snippets notation] at the end of each document:
+
+  [^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.
+
+=== ":octicons-file-code-16: docs/example.md"
+
+    ```` markdown
+    The HTML specification is maintained by the W3C.
+
+    --8<-- "includes/abbreviations.md"
+    ````
+
+=== ":octicons-file-code-16: includes/abbreviations.md"
+
+    ```` markdown
+    *[HTML]: Hyper Text Markup Language
+    *[W3C]: World Wide Web Consortium
+    ````
+
+  [Snippets notation]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippets-notation

docs/reference/tooltips.md

@@ -557,6 +557,13 @@
               "content.tabs.link"
             ]
           },
+          {
+            "title": "Improved tooltips",
+            "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/tooltips/#improved-tooltips",
+            "enum": [
+              "content.tooltips"
+            ]
+          },
           {
             "title": "Header hides automatically when scrolling",
             "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-header/#automatic-hiding",

docs/schema/theme.json

@@ -179,11 +179,11 @@ theme:
   palette: # (1)!
     - scheme: default
       toggle:
-        icon: material/toggle-switch-off-outline # (2)!
+        icon: material/toggle-switch # (2)!
         name: Switch to dark mode
     - scheme: slate # (3)!
       toggle:
-        icon: material/toggle-switch
+        icon: material/toggle-switch-off-outline
         name: Switch to light mode
 ```
 
@@ -214,11 +214,11 @@ The following properties must be set for each toggle:
     This property must point to a valid icon path referencing any icon bundled
     with the theme, or the build will not succeed. Some popular combinations:
 
-    * :material-toggle-switch-off-outline: + :material-toggle-switch: – `material/toggle-switch-off-outline` + `material/toggle-switch`
-    * :material-weather-sunny: + :material-weather-night: – `material/weather-sunny` + `material/weather-night`
-    * :material-eye-outline: + :material-eye: – `material/eye-outline` + `material/eye`
-    * :material-lightbulb-outline: + :material-lightbulb: – `material/lightbulb-outline` + `material/lightbulb`
-    * :material-brightness-4: + :material-brightness-7: – `material/brightness-4` + `material/brightness-7`
+    * :material-toggle-switch: + :material-toggle-switch-off-outline: – `material/toggle-switch` + `material/toggle-switch-off-outline`
+    * :material-weather-night: + :material-weather-sunny: – `material/weather-night` + `material/weather-sunny`
+    * :material-eye: + :material-eye-outline: – `material/eye` + `material/eye-outline`
+    * :material-lightbulb: + :material-lightbulb-outline: – `material/lightbulb` + `material/lightbulb-outline`
+    * :material-brightness-7: + :material-brightness-4: – `material/brightness-7` + `material/brightness-4`
 
 `name`{ #toggle-name }
 

docs/setup/changing-the-colors.md

@@ -22,7 +22,7 @@
         <link rel="canonical" href="{{ page.canonical_url }}">
       {% endif %}
       <link rel="icon" href="{{ config.theme.favicon | url }}">
-      <meta name="generator" content="mkdocs-{{ mkdocs_version }}, mkdocs-material-8.2.13">
+      <meta name="generator" content="mkdocs-{{ mkdocs_version }}, mkdocs-material-8.2.14">
     {% endblock %}
     {% block htmltitle %}
       {% if page and page.meta and page.meta.title %}

material/base.html

@@ -51,6 +51,7 @@ theme:
   features:
     - content.code.annotate
     # - content.tabs.link
+    - content.tooltips
     # - header.autohide
     # - navigation.expand
     - navigation.indexes
@@ -73,8 +74,8 @@ theme:
         icon: material/toggle-switch
         name: Switch to dark mode
     - scheme: slate
-      primary: red
-      accent: red
+      primary: indigo
+      accent: indigo
       toggle:
         icon: material/toggle-switch-off-outline
         name: Switch to light mode
@@ -92,6 +93,7 @@ plugins:
       redirect_maps:
         changelog/insiders.md: insiders/changelog.md
         conventions.md: philosophy.md
+        reference/abbreviations.md: reference/tooltips.md
         reference/meta-tags.md: reference/index.md
         reference/variables.md: https://mkdocs-macros-plugin.readthedocs.io/
         sponsorship.md: insiders/index.md
@@ -195,7 +197,6 @@ nav:
       - Python Markdown Extensions: setup/extensions/python-markdown-extensions.md
   - Reference:
     - reference/index.md
-    - Abbreviations: reference/abbreviations.md
     - Admonitions: reference/admonitions.md
     - Annotations: reference/annotations.md
     - Buttons: reference/buttons.md
@@ -210,6 +211,7 @@ nav:
     - Images: reference/images.md
     - Lists: reference/lists.md
     - MathJax: reference/mathjax.md
+    - Tooltips: reference/tooltips.md
   - Insiders:
     - insiders/index.md
     - Getting started:

mkdocs.yml

@@ -1,6 +1,6 @@
 {
   "name": "mkdocs-material",
-  "version": "8.2.13",
+  "version": "8.2.14",
   "description": "Documentation that simply works",
   "keywords": [
     "mkdocs",