From 9f01a6664b1f454af2523d9431f52efa7f908bbb Mon Sep 17 00:00:00 2001
From: squidfunk <martin.donath@squidfunk.com>
Date: Fri, 1 Apr 2022 17:55:19 +0200
Subject: [PATCH] Added documentation for changing annotation width

---
 docs/browser-support.md                       |  9 +++--
 docs/reference/code-blocks.md                 | 33 +++++++++++++++++++
 .../extensions/python-markdown-extensions.md  |  6 ++--
 3 files changed, 40 insertions(+), 8 deletions(-)

diff --git a/docs/browser-support.md b/docs/browser-support.md
index d5ce29855..bc7a8e190 100644
--- a/docs/browser-support.md
+++ b/docs/browser-support.md
@@ -59,14 +59,13 @@ the following older browser versions might work with some additional effort:
 
 - :fontawesome-brands-firefox: __Firefox 31-52__ – icons will render as little
   boxes due to missing support for [mask images]. While this cannot be
-  polyfilled, it might be mitigated by hiding icons with [additional CSS].
-- :fontawesome-brands-edge: __Edge 16-18__ – the spacing of some elements might be
-  a little off due to missing support for the [:is pseudo selector], which can be
-  mitigated with some [additional CSS].
+  polyfilled, it might be mitigated by hiding the icons altogether.
+- :fontawesome-brands-edge: __Edge 16-18__ – the spacing of some elements might
+  be a little off due to missing support for the [:is pseudo selector], which
+  can be mitigated with some additional effort.
 - :fontawesome-brands-internet-explorer: __Internet Explorer__ - no support,
   mainly due to missing support for [custom properties]. The last version of
   Material for MkDocs to support Internet Explorer is
   [:octicons-tag-24: 4.6.3][IE support].
 
-  [additional CSS]: customization.md#additional-css
   [IE support]: https://github.com/squidfunk/mkdocs-material/releases/tag/4.6.3
diff --git a/docs/reference/code-blocks.md b/docs/reference/code-blocks.md
index 80e89ca06..6a544ad00 100644
--- a/docs/reference/code-blocks.md
+++ b/docs/reference/code-blocks.md
@@ -396,6 +396,39 @@ override it as part of your [additional style sheet]:
   [additional style sheet]: ../customization.md#additional-css
   [syntax theme definition]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
 
+### Annotation tooltip width
+
+If you have a lot of content hosted inside your code annotations, it can be a
+good idea to increase the width of the tooltip by adding the following as part
+of an [additional style sheet]:
+
+=== ":octicons-file-code-16: docs/stylesheets/extra.css"
+
+    ``` css
+    :root {
+      --md-tooltip-width: 600px;
+    }
+    ```
+
+=== ":octicons-file-code-16: mkdocs.yml"
+
+    ``` yaml
+    extra_css:
+      - stylesheets/extra.css
+    ```
+
+This will render annotations with a larger width:
+
+<div style="--md-tooltip-width: 600px;" markdown>
+
+``` yaml
+# (1)!
+```
+
+1. Muuuuuuuuuuuuuuuch more space for content
+
+</div>
+
 ### Annotations with numbers
 
 Prior to [:octicons-tag-24: 8.1.0][code annotation markers], code annotations
diff --git a/docs/setup/extensions/python-markdown-extensions.md b/docs/setup/extensions/python-markdown-extensions.md
index 01f67155c..d75f593b7 100644
--- a/docs/setup/extensions/python-markdown-extensions.md
+++ b/docs/setup/extensions/python-markdown-extensions.md
@@ -343,8 +343,8 @@ The following configuration options are supported:
         ```
 
         As an example, [Highlight.js], a JavaScript syntax highlighter, can be 
-        integrated with some [additional JavaScript] and [additional CSS] in
-        `mkdocs.yml`:
+        integrated with some [additional JavaScript] and an [additional style
+        sheet] in `mkdocs.yml`:
 
         === ":octicons-file-code-16: docs/javascripts/highlight.js"
 
@@ -446,7 +446,7 @@ See reference for usage:
   [pymdownx.superfences]: #superfences
   [pymdownx.inlinehilite]: #inlinehilite
   [Pygments]: https://pygments.org
-  [additional CSS]: ../../customization.md#additional-css
+  [additional style sheet]: ../../customization.md#additional-css
   [Highlight.js]: https://highlightjs.org/
   [title]: ../../reference/code-blocks.md#adding-a-title
   [anchor_linenums support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.1.0