From 0436c9937b90b9bab4c9a6699a8859a93858d8bb Mon Sep 17 00:00:00 2001
From: squidfunk <martin.donath@squidfunk.com>
Date: Mon, 4 Oct 2021 23:36:31 +0200
Subject: [PATCH] Updated documentation

---
 .../2021/excluding-content-from-search.md     |   2 +-
 .../blog/2021/search-better-faster-smaller.md |   8 +-
 docs/creating-your-site.md                    |   2 +-
 docs/insiders/index.md                        |   8 +-
 docs/reference/abbreviations.md               |  10 +-
 docs/reference/admonitions.md                 | 103 +++++++-----
 docs/reference/code-blocks.md                 |  25 +--
 docs/reference/content-tabs.md                |   4 +-
 docs/reference/diagrams.md                    |  25 +--
 docs/reference/footnotes.md                   |  33 ++--
 docs/reference/formatting.md                  | 159 +++++-------------
 docs/reference/icons-emojis.md                |  72 +++-----
 docs/reference/images.md                      |  13 +-
 docs/reference/lists.md                       |   2 +-
 docs/setup/changing-the-language.md           |   2 +-
 docs/setup/extensions/index.md                |   5 +-
 .../extensions/python-markdown-extensions.md  |  43 ++---
 docs/setup/extensions/python-markdown.md      |  32 ++--
 docs/setup/setting-up-site-search.md          |   2 +-
 docs/setup/setting-up-social-cards.md         |   4 +-
 docs/setup/setting-up-versioning.md           |   8 +-
 .../main/extensions/markdown/_admonition.scss |   6 -
 22 files changed, 231 insertions(+), 337 deletions(-)

diff --git a/docs/blog/2021/excluding-content-from-search.md b/docs/blog/2021/excluding-content-from-search.md
index 1d52007f1..3d784d9b0 100644
--- a/docs/blog/2021/excluding-content-from-search.md
+++ b/docs/blog/2021/excluding-content-from-search.md
@@ -14,7 +14,7 @@ __The latest Insiders release brings three new simple ways to exclude
 dedicated parts of a document from the search index, allowing for more
 fine-grained control.__
 
-<aside class="mdx-author" markdown="1">
+<aside class="mdx-author" markdown>
 ![@squidfunk][1]
 
 <span>__Martin Donath__ · @squidfunk</span>
diff --git a/docs/blog/2021/search-better-faster-smaller.md b/docs/blog/2021/search-better-faster-smaller.md
index bb4f36fbb..4f8904dae 100644
--- a/docs/blog/2021/search-better-faster-smaller.md
+++ b/docs/blog/2021/search-better-faster-smaller.md
@@ -14,7 +14,7 @@ __This is the story of how we managed to completely rebuild client-side search,
 delivering a significantly better user experience while making it faster and
 smaller at the same time.__
 
-<aside class="mdx-author" markdown="1">
+<aside class="mdx-author" markdown>
 ![@squidfunk][1]
 
 <span>__Martin Donath__ · @squidfunk</span>
@@ -230,11 +230,11 @@ search previews appear not to include any occurrence of any of the search
 terms. This was due to the fact that search previews were [truncated after a
 maximum of 320 characters][15], as can be seen here:
 
-<figure markdown="1">
+<figure markdown>
 
 ![Search previews][16]
 
-  <figcaption markdown="1">
+  <figcaption markdown>
 
 The first two results look like they're not relevant, as they don't seem to
 include the query string the user just searched for. Yet, they are.
@@ -578,7 +578,7 @@ itself, and one with a very massive corpus of Markdown files with more than
 800,000 words – a size most documentation projects will likely never
 reach:
 
-<figure markdown="1">
+<figure markdown>
 
 |                         |   Before |            Now |     Relative |
 | ----------------------- | -------: | -------------: | -----------: |
diff --git a/docs/creating-your-site.md b/docs/creating-your-site.md
index afb512c81..22bbd7206 100644
--- a/docs/creating-your-site.md
+++ b/docs/creating-your-site.md
@@ -91,7 +91,7 @@ Material for MkDocs comes with many configuration options. The _setup_ section
 explains in great detail how to configure and customize colors, fonts, icons
 and much more:
 
-<div class="mdx-columns" markdown="1">
+<div class="mdx-columns" markdown>
 
 - [Changing the colors][5]
 - [Changing the fonts][6]
diff --git a/docs/insiders/index.md b/docs/insiders/index.md
index 01d310ebf..bd76d48c3 100644
--- a/docs/insiders/index.md
+++ b/docs/insiders/index.md
@@ -10,11 +10,11 @@ that _new features are first exclusively released to sponsors_ as part of
 __Insiders__. Read on to learn [how sponsorship works][1], and how easy it is
 to [get access to Insiders][2].
 
-<figure class="mdx-video" markdown="1">
+<figure class="mdx-video" markdown>
   <div class="mdx-video__inner">
     <iframe src="https://streamable.com/e/ihhxw0" allowfullscreen></iframe>
   </div>
-  <figcaption markdown="1">
+  <figcaption markdown>
 
 The official documentation is built with Insiders
 [squidfunk.github.io/mkdocs-material][3]
@@ -100,7 +100,7 @@ You can cancel your sponsorship anytime.[^4]
 
 <hr />
 
-<div class="mdx-premium" markdown="1">
+<div class="mdx-premium" markdown>
 
 **Special thanks** to our **premium sponsors**:
 
@@ -135,7 +135,7 @@ You can cancel your sponsorship anytime.[^4]
 
 The following features are currently exclusively available to sponsors:
 
-<div class="mdx-columns" markdown="1">
+<div class="mdx-columns" markdown>
 
 - [x] [Brand new search plugin :material-new-box:][35]
 - [x] [Rich search previews :material-new-box:][36]
diff --git a/docs/reference/abbreviations.md b/docs/reference/abbreviations.md
index ff134ff2b..608b45a40 100644
--- a/docs/reference/abbreviations.md
+++ b/docs/reference/abbreviations.md
@@ -11,8 +11,8 @@ enable site-wide glossaries.
 
 ## Configuration
 
-This configuration enables abbreviations, and allows to build a simple
-project-wide glossary sourcing definitions from a central location. Add the
+This configuration enables abbreviations and allows to build a simple
+project-wide glossary, sourcing definitions from a central location. Add the
 following line to `mkdocs.yml`:
 
 ``` yaml
@@ -57,8 +57,8 @@ The HTML specification is maintained by the W3C.
 
 ### Adding a glossary
 
-The [Snippets] extension can be used to implement a simple glossary, by moving
-all abbreviations in a dedicated file[^1] and include it with the
+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]:
@@ -73,7 +73,7 @@ _Example_:
 
     ```` markdown
     The HTML specification is maintained by the W3C.
-    
+
     --8<-- "includes/abbreviations.md"
     ````
 
diff --git a/docs/reference/admonitions.md b/docs/reference/admonitions.md
index c4cf6641f..035637e52 100644
--- a/docs/reference/admonitions.md
+++ b/docs/reference/admonitions.md
@@ -12,7 +12,7 @@ inclusion and nesting of arbitrary content.
 ## Configuration
 
 This configuration enables admonitions, allows to make them collapsible and to
-nest arbitrary content inside admonition bodies. Add the following lines to
+nest arbitrary content inside admonitions. Add the following lines to
 `mkdocs.yml`:
 
 ``` yaml
@@ -38,63 +38,76 @@ See additional configuration options:
 [:octicons-tag-24: insiders-2.4.0 ... present][Insiders]
 
 Each of the supported admonition types has a distinct icon, which can be changed
-to any icon bundled with the theme. Just set the name of the admonition type to
-a valid icon in `mkdocs.yml`:
+to any icon bundled with the theme. Add the following lines to `mkdocs.yml`:
 
-=== ":octicons-mark-github-16: Octicons"
+``` yaml
+theme:
+  icon:
+    admonition:
+      <type>: <icon> # (1)
+```
 
-    _Example_:
+1.  Set `<type`> to any of the [supported types] and `<icon>` to any valid icon 
+    shortcode, which you can find by using the [icon search].
 
-    ``` yaml
-    theme:
-      icon:
-        admonition:
-          note: octicons/tag-16
-          abstract: octicons/checklist-16
-          info: octicons/info-16
-          tip: octicons/squirrel-16
-          success: octicons/check-16
-          question: octicons/question-16
-          warning: octicons/alert-16
-          failure: octicons/x-circle-16
-          danger: octicons/zap-16
-          bug: octicons/bug-16
-          example: octicons/beaker-16
-          quote: octicons/quote-16
-    ```
+??? example "Example: using alternative icon sets"
 
-    _Result_:
+    === ":octicons-mark-github-16: Octicons"
 
-    [![Octicons]][Octicons]
+        _Example_:
+
+        ``` yaml
+        theme:
+          icon:
+            admonition:
+              note: octicons/tag-16
+              abstract: octicons/checklist-16
+              info: octicons/info-16
+              tip: octicons/squirrel-16
+              success: octicons/check-16
+              question: octicons/question-16
+              warning: octicons/alert-16
+              failure: octicons/x-circle-16
+              danger: octicons/zap-16
+              bug: octicons/bug-16
+              example: octicons/beaker-16
+              quote: octicons/quote-16
+        ```
+
+        _Result_:
+
+        [![Octicons]][Octicons]
 
 
-=== ":fontawesome-brands-font-awesome: FontAwesome"
+    === ":fontawesome-brands-font-awesome: FontAwesome"
 
-    _Example_:
+        _Example_:
 
-    ``` yaml
-    theme:
-      icon:
-        admonition:
-          note: fontawesome/solid/sticky-note
-          abstract: fontawesome/solid/book
-          info: fontawesome/solid/info-circle
-          tip: fontawesome/solid/bullhorn
-          success: fontawesome/solid/check
-          question: fontawesome/solid/question-circle
-          warning: fontawesome/solid/exclamation-triangle
-          failure: fontawesome/solid/bomb
-          danger: fontawesome/solid/skull
-          bug: fontawesome/solid/robot
-          example: fontawesome/solid/flask
-          quote: fontawesome/solid/quote-left
-    ```
+        ``` yaml
+        theme:
+          icon:
+            admonition:
+              note: fontawesome/solid/sticky-note
+              abstract: fontawesome/solid/book
+              info: fontawesome/solid/info-circle
+              tip: fontawesome/solid/bullhorn
+              success: fontawesome/solid/check
+              question: fontawesome/solid/question-circle
+              warning: fontawesome/solid/exclamation-triangle
+              failure: fontawesome/solid/bomb
+              danger: fontawesome/solid/skull
+              bug: fontawesome/solid/robot
+              example: fontawesome/solid/flask
+              quote: fontawesome/solid/quote-left
+        ```
 
-    _Result_:
+        _Result_:
 
-    [![FontAwesome]][FontAwesome]
+        [![FontAwesome]][FontAwesome]
 
   [Insiders]: ../insiders/index.md
+  [supported types]: #supported-types
+  [icon search]: icons-emojis.md#search
   [Octicons]: ../assets/screenshots/admonition-octicons.png
   [FontAwesome]: ../assets/screenshots/admonition-fontawesome.png
 
diff --git a/docs/reference/code-blocks.md b/docs/reference/code-blocks.md
index 3a5f734b1..f3ad558c4 100644
--- a/docs/reference/code-blocks.md
+++ b/docs/reference/code-blocks.md
@@ -15,7 +15,7 @@ during runtime using a JavaScript syntax highlighter.
 
 This configuration enables syntax highlighting on code blocks and inline code 
 blocks, and allows to include source code directly from other files. Add the 
-following lines to `mkdocs.yml`
+following lines to `mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:
@@ -46,7 +46,7 @@ See additional configuration options:
 
 Code annotations offer a comfortable and friendly way to attach arbitrary
 content to specific sections of code blocks by adding numeric markers in block
-and inline comments in the language of the block. Add the following to
+and inline comments in the language of the code block. Add the following to
 `mkdocs.yml` to enable them globally:
 
 ``` yaml
@@ -58,7 +58,7 @@ theme:
 1.  :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
     text__, images, ... basically anything that can be expressed in Markdown.
 
-??? info "Enabling code annotations only for specific code blocks"
+??? info "Enabling code annotations for a specific code block"
 
     If you don't want to enable code annotations globally, because you don't
     like the automatic inlining behavior, you can enable them for a specific
@@ -182,7 +182,7 @@ at `1`, regardless of the starting line number specified as part of
 
     _Example_:
 
-    ```` markdown
+    ```` markdown 
     ``` python hl_lines="2 3"
     def bubble_sort(items):
         for i in range(len(items)):
@@ -194,7 +194,7 @@ at `1`, regardless of the starting line number specified as part of
 
     _Result_:
 
-    ``` python hl_lines="2 3"
+    ``` python linenums="1" hl_lines="2 3"
     def bubble_sort(items):
         for i in range(len(items)):
             for j in range(len(items) - 1 - i):
@@ -218,7 +218,7 @@ at `1`, regardless of the starting line number specified as part of
 
     _Result_:
 
-    ``` python hl_lines="2-5"
+    ``` python linenums="1" hl_lines="2-5"
     def bubble_sort(items):
         for i in range(len(items)):
             for j in range(len(items) - 1 - i):
@@ -246,8 +246,9 @@ The `#!python range()` function is used to generate a sequence of numbers.
 
 ### Embedding external files
 
-When [Snippets] is enabled, content from other files can be embedded, which is particularly useful to reference and embed the contents of source files
-directly in a document without copying.
+When [Snippets] is enabled, content from other files (including source files)
+can be embedded by using the [`--8<--` notation][Snippets notation] directly
+from within a code block:
 
 _Example_:
 
@@ -263,6 +264,8 @@ _Result_:
 last 4 years
 ```
 
+  [Snippets notation]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippets-notation
+
 ## Customization
 
 ### Custom syntax theme
@@ -303,9 +306,9 @@ a new color by using an [additional stylesheet]:
 }
 ```
 
-If you want to tweak a specific type of string, i.e. ``#!js `backticks` ``, you
-can lookup the specific class name in the [syntax theme definition], and
-override it as part of your additional stylesheet:
+If you want to tweak a specific type of string, e.g. ``#!js `backticks` ``, you
+can lookup the specific CSS class name in the [syntax theme definition], and
+override it as part of your [additional stylesheet]:
 
 ``` css
 .highlight .sb {
diff --git a/docs/reference/content-tabs.md b/docs/reference/content-tabs.md
index c084feaa7..7323add79 100644
--- a/docs/reference/content-tabs.md
+++ b/docs/reference/content-tabs.md
@@ -11,9 +11,9 @@ grouping code blocks and other content.
 
 ## Configuration
 
-This configuration enables content tabs, and allows to nest arbirtrary content
+This configuration enables content tabs, and allows to nest arbitrary content
 inside content tabs, including code blocks and ... more content tabs! Add the 
-following lines to `mkdocs.yml`
+following lines to `mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:
diff --git a/docs/reference/diagrams.md b/docs/reference/diagrams.md
index 140a33f67..c82b5b0c1 100644
--- a/docs/reference/diagrams.md
+++ b/docs/reference/diagrams.md
@@ -30,42 +30,25 @@ markdown_extensions:
           format: !!python/name:pymdownx.superfences.fence_code_format
 ```
 
-No further configuration is necessary. Advantages over custom integration:
+No further configuration is necessary. Advantages over a custom integration:
 
 - [x] Works with [instant loading] without any additional effort
 - [x] Diagrams automatically use fonts and colors defined in `mkdocs.yml`[^1]
 - [x] Fonts and colors can be customized with [additional stylesheets]
 - [x] Support for both, light and dark color schemes
 
-_While it's also possible to integrate [Mermaid.js] using existing
-third-party plugins[^2], the new native integration is recommended as it
-ensures interoperability with all Material for MkDocs features._
-
   [^1]:
     While all [Mermaid.js] features should work out-of-the-box, Material for
-    MkDocs will currently adjust the fonts and colors for flow charts, sequence
-    diagrams, class diagams, state diagrams and entity relationship diagrams.
-
-  [^2]:
-    If you don't want to use the native integration, [mkdocs-mermaid2-plugin]
-    might be a good alternative. However, note that this plugin cannot be used
-    in conjunction with the [mkdocs-minify-plugin] and doesn't adapt to
-    dark mode.
+    MkDocs will currently only adjust the fonts and colors for flowcharts,
+    sequence diagrams, class diagams, state diagrams and entity relationship 
+    diagrams.
 
   [Insiders]: ../insiders/index.md
   [instant loading]: ../setup/setting-up-navigation.md#instant-loading
   [additional stylesheets]: ../customization.md#additional-css
-  [mkdocs-mermaid2-plugin]: https://github.com/fralau/mkdocs-mermaid2-plugin
-  [mkdocs-minify-plugin]: https://github.com/byrnereese/mkdocs-minify-plugin
 
 ## Usage
 
-Mermaid diagrams are written as code blocks with the help of the [SuperFences]extension. They must be enclosed with two separate lines containing three
-backticks.
-
-  [code blocks]: code-blocks.md
-  [SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
-
 ### Using flowcharts
 
 [Flowcharts] are diagrams that represent workflows or processes. The steps
diff --git a/docs/reference/footnotes.md b/docs/reference/footnotes.md
index 5f15b5c7f..0674e8d93 100644
--- a/docs/reference/footnotes.md
+++ b/docs/reference/footnotes.md
@@ -5,27 +5,26 @@ template: overrides/main.html
 # Footnotes
 
 Footnotes are a great way to add references to supplemental or additional
-information for a specific section of a document without interrupting the
-document flow. Material for MkDocs provides the ability to insert inline
-footnotes and render them at the bottom of the page.
+information to a specific word, phrase or sentence without interrupting the
+flow of a document. Material for MkDocs provides the ability to define and
+render footnotes.
 
 ## Configuration
 
-### Footnotes
-
-[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
-
-The [Footnotes][2] extension, which is part of the standard Markdown library,
-adds the ability to add inline footnotes to a document and can be enabled via
-`mkdocs.yml`:
+This configuration adds the ability to define footnotes inline with the content,
+which are then rendered below all Markdown content of a document. Add the 
+following lines to `mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:
   - footnotes
 ```
 
-  [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_footnotes.scss
-  [2]: https://python-markdown.github.io/extensions/footnotes/
+See additional configuration options:
+
+- [Footnotes]
+
+  [Footnotes]: ../setup/extensions/python-markdown.md#footnotes
 
 ## Usage
 
@@ -54,7 +53,7 @@ reference is automatically added.
 
 #### on a single line
 
-Short statements can be written on the same line.
+Short footnotes can be written on the same line.
 
 _Example_:
 
@@ -83,9 +82,9 @@ _Example_:
 
 _Result_:
 
-  [^2]:
-      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-      nulla. Curabitur feugiat, tortor non consequat finibus, justo purus
-      auctor massa, nec semper lorem quam in massa.
+[^2]:
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus
+    auctor massa, nec semper lorem quam in massa.
 
 [Jump to footnote at the bottom of the page](#fn:2)
diff --git a/docs/reference/formatting.md b/docs/reference/formatting.md
index 5bbab56a0..fa4976597 100644
--- a/docs/reference/formatting.md
+++ b/docs/reference/formatting.md
@@ -6,135 +6,40 @@ template: overrides/main.html
 
 Material for MkDocs provides support for several HTML elements that can be used 
 to highlight sections of a document or apply specific formatting. Additionally, 
-[Critic Markup][1] is supported, adding the ability to display suggested changes
+[Critic Markup] is supported, adding the ability to display suggested changes
 for a document.
 
-  [1]: http://criticmarkup.com/
+  [Critic Markup]: https://github.com/CriticMarkup/CriticMarkup-toolkit
 
 ## Configuration
 
-### Critic
-
-[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3]
-
-The [Critic][3] extension, which is part of [Python Markdown Extensions][4], 
-allows for the __usage of [Critic Markup][1] to highlight changes__ in a
-document, and can be enabled via `mkdocs.yml`:
+This configuration enables support for keyboard keys, highlighting changes
+to documents, highlighting text and defining sub- and superscript. Add the 
+following lines to `mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:
   - pymdownx.critic
-```
-
-The following options are supported:
-
-`mode`{ #mode }
-
-:   :octicons-milestone-24: Default: `view` – This option defines how the markup 
-    should be parsed, i.e. whether to just `view` all suggest changes, or
-    alternatively `accept` or `reject` them:
-
-    === "View changes"
-
-        ``` yaml
-        markdown_extensions:
-          - pymdownx.critic:
-              mode: view
-        ```
-
-    === "Accept changes"
-
-        ``` yaml
-        markdown_extensions:
-          - pymdownx.critic:
-              mode: accept
-        ```
-
-    === "Reject changes"
-
-        ``` yaml
-        markdown_extensions:
-          - pymdownx.critic:
-              mode: reject
-        ```
-
-  [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_critic.scss
-  [3]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/
-  [4]: https://facelessuser.github.io/pymdown-extensions/
-
-### BetterEm
-
-The [BetterEm][5] extension, which is part of [Python Markdown Extensions][4], 
-improves the handling of Markup to emphasize text (e.g. __bold__  and _italic_), 
-and can be enabled via `mkdocs.yml`:
-
-``` yaml
-markdown_extensions:
-  - pymdownx.betterem:
-      smart_enable: all
-```
-
-  [5]: https://facelessuser.github.io/pymdown-extensions/extensions/betterem/
-
-### Caret, Mark & Tilde
-
-The [Caret][6], [Mark][7] and [Tilde][8] extensions, which are part of [Python 
-Markdown Extensions][4], allow for the __highlighting of text__, as well as
-__handling sub- and superscripts__:
-
-``` yaml
-markdown_extensions:
   - pymdownx.caret
+  - pymdownx.keys
   - pymdownx.mark
   - pymdownx.tilde
 ```
 
-  [6]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/
-  [7]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
-  [8]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/
+- [Critic]
+- [Caret, Mark & Tilde]
+- [Keys]
 
-### Adding keyboard keys
-
-When [Keys][22] is enabled, keyboard keys can be rendered with a simple syntax.
-Consult the [Python Markdown Extensions][14] documentation to learn about all
-available key codes.
-
-_Example_:
-
-``` markdown
-++ctrl+alt+del++
-```
-
-_Result_:
-
-++ctrl+alt+del++
-
-  [22]: #keys
-
-### SmartSymbols
-
-The [SmartSymbols][9] extension, which is also part of [Python Markdown 
-Extensions][4], __converts special characters into their corresponding
-symbols__, and can be enabled via `mkdocs.yml`:
-
-``` yaml
-markdown_extensions:
-  - pymdownx.smartsymbols
-```
-
-See the [official documentation][9] for a list of supported symbols.
-
-  [9]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
+  [Critic]: ../setup/extensions/python-markdown-extensions.md#critic
+  [Caret, Mark & Tilde]: ../setup/extensions/python-markdown-extensions.md#caret-mark-tilde
+  [Keys]: ../setup/extensions/python-markdown-extensions.md#keys
 
 ## Usage
 
 ### Highlighting changes
 
-When [Critic][10] is enabled, [Critic Markup][1] can be used, which adds the
-ability to _highlight suggested changes_, as well as add _inline comments_ to a 
-document:
-
-  [10]: #critic
+When [Critic] is enabled, [Critic Markup] can be used, which adds the ability to 
+highlight suggested changes, as well as add inline comments to a document.
 
 _Example_:
 
@@ -145,7 +50,7 @@ possible {>>and comments can be added inline<<}.
 
 {==
 
-Formatting can also be applied to blocks, by putting the opening and closing
+Formatting can also be applied to blocks by putting the opening and closing
 tags on separate lines and adding new lines between the tags and the content.
 
 ==}
@@ -162,7 +67,7 @@ Text can be <del class="critic">deleted</del> and replacement text
 <div>
   <mark class="critic block">
     <p>
-      Formatting can also be applied to blocks, by putting the opening and
+      Formatting can also be applied to blocks by putting the opening and
       closing tags on separate lines and adding new lines between the tags and
       the content.
     </p>
@@ -171,9 +76,9 @@ Text can be <del class="critic">deleted</del> and replacement text
 
 ### Highlighting text
 
-When the [Caret, Mark & Tilde][11] extensions are enabled, text can be 
-highlighted with a nicer syntax than using the corresponding `mark`, `ins` and 
-`del` HTML tags:
+When [Caret, Mark & Tilde] are enabled, text can be highlighted with a simple 
+syntax, which is more convenient that directly using the corresponding `mark`, 
+`ins` and `del` HTML tags.
 
 _Example_:
 
@@ -189,13 +94,11 @@ _Result_:
 - ^^This was inserted^^
 - ~~This was deleted~~
 
-  [11]: #caret-mark-tilde
-
 ### Sub- and superscripts
 
-When the [Caret & Tilde][11] extensions are enabled, text can be sub- and 
-superscripted with a nicer syntax than using the corresponding `sub` and `sup` 
-HTML tags:
+When [Caret & Tilde][Caret, Mark & Tilde] are enabled, text can be sub- and 
+superscripted with a simple syntax, which is more convenient that directly
+using the corresponding `sub` and `sup`  HTML tags:
 
 _Example_:
 
@@ -209,4 +112,20 @@ _Result_:
 - H~2~0
 - A^T^A
 
-  [11]: #caret-mark-tilde
+### Adding keyboard keys
+
+When [Keys] is enabled, keyboard keys can be rendered with a simple syntax.
+Consult the [Python Markdown Extensions] documentation to learn about all
+available shortcodes.
+
+_Example_:
+
+``` markdown
+++ctrl+alt+del++
+```
+
+_Result_:
+
+++ctrl+alt+del++
+
+  [Python Markdown Extensions]: [#keys](https://facelessuser.github.io/pymdown-extensions/extensions/keys/#extendingmodifying-key-map-index)
diff --git a/docs/reference/icons-emojis.md b/docs/reference/icons-emojis.md
index 84ce626cb..9eee37dd1 100644
--- a/docs/reference/icons-emojis.md
+++ b/docs/reference/icons-emojis.md
@@ -5,9 +5,11 @@ template: overrides/main.html
 # Icons + Emojis
 
 One of the best features of Material for MkDocs is the possibility to use [more
-than 8.000 icons][1] and thousands of emojis in your project documentation
-with practically zero additional effort. Furthermore, custom icons can be added
-and used in `mkdocs.yml`, documents and templates.
+than 8.000 icons][icon search] and thousands of emojis in your project 
+documentation with practically zero additional effort. Moreover, custom icons 
+can be added and used in `mkdocs.yml`, documents and templates.
+
+  [icon search]: #search
 
 ## Search
 
@@ -24,19 +26,15 @@ and used in `mkdocs.yml`, documents and templates.
 </div>
 <small>
   :octicons-light-bulb-16:
-  **Tip:** Enter some keywords to find the perfect icon or emoji and click on
-  the shortcode to copy it to your clipboard.
+  **Tip:** Enter some keywords to find icons and emojis and click on the
+  shortcode to copy it to your clipboard.
 </small>
 
 ## Configuration
 
-### Emoji
-
-[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3]
-
-The [Emoji][3] extension, which is part of [Python Markdown Extensions][4],
-adds the ability to __integrate emojis and icons__ in the `*.svg` file format,
-which are inlined when [building your site][5]:
+This configuration enables the use of icons and emojis by using simple
+shortcodes which can be discovered through the [icon search]. Add the following
+lines to `mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:
@@ -47,44 +45,29 @@ markdown_extensions:
 
 The following icon sets are bundled with Material for MkDocs:
 
-- :material-material-design: – [Material Design][6]
-- :fontawesome-brands-font-awesome-flag: – [FontAwesome][7]
-- :octicons-mark-github-16: – [Octicons][8]
+- :material-material-design: – [Material Design]
+- :fontawesome-brands-font-awesome: – [FontAwesome]
+- :octicons-mark-github-16: – [Octicons]
 
-You can also add [additional icons][9]. When using emojis, it's recommended to
-consult the official documentation of [Python Markdown Extensions][3] to learn
-about configuration options.
+See additional configuration options:
 
-  [1]: icons-emojis.md#search
-  [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_emoji.scss
-  [3]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
-  [4]: https://facelessuser.github.io/pymdown-extensions/
-  [5]: ../creating-your-site.md#building-your-site
-  [6]: https://materialdesignicons.com/
-  [7]: https://fontawesome.com/icons?d=gallery&m=free
-  [8]: https://octicons.github.com/
-  [9]: ../setup/changing-the-logo-and-icons.md#additional-icons
+- [Emoji]
+- [Emoji with custom icons]
 
-### Attribute List
-
-The [Attribute List][10] extension, which is part of the standard Markdown
-library, allows to __add HTML attributes and CSS classes to Markdown elements__,
-and can be enabled via `mkdocs.yml`
-
-``` yaml
-markdown_extensions:
-  - attr_list
-```
-
-  [10]: https://python-markdown.github.io/extensions/attr_list/
+  [Material Design]: https://materialdesignicons.com/
+  [FontAwesome]: https://fontawesome.com/icons?d=gallery&m=free
+  [Octicons]: https://octicons.github.com/
+  [additional icons]: ../setup/changing-the-logo-and-icons.md#additional-icons
+  [Emoji]: ../setup/extensions/python-markdown-extensions.md#emoji
+  [Emoji with custom icons]: ../setup/extensions/python-markdown-extensions.md#custom_icons
 
 ## Usage
 
 ### Using emojis
 
 Emojis can be integrated in Markdown by putting the shortcode of the emoji
-between two colons. If you're using [Twemoji][11] (recommended), you can look up
-the shortcodes at [Emojipedia][12].
+between two colons. If you're using [Twemoji] (recommended), you can look up
+the shortcodes at [Emojipedia].
 
 _Example_:
 
@@ -96,12 +79,12 @@ _Result_:
 
 :smile:
 
-  [11]: https://twemoji.twitter.com/
-  [12]: https://emojipedia.org/twitter/
+  [Twemoji]: https://twemoji.twitter.com/
+  [Emojipedia]: https://emojipedia.org/twitter/
 
 ### Using icons
 
-When [Emoji][13] is enabled, icons can be used similar to emojis, by referencing
+When [Emoji] is enabled, icons can be used similar to emojis, by referencing
 a valid path to any icon bundled with the theme, which are located in the
 [`.icons`][1] directory, and replacing `/` with `-`:
 
@@ -119,7 +102,6 @@ _Result_:
 - :fontawesome-regular-laugh-wink: – [`.icons/fontawesome/regular/laugh-wink.svg`][15]
 - :octicons-repo-push-16: – [`.icons/octicons/repo-push-16.svg`][16]
 
-  [13]: #emoji
   [14]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/material/account-circle.svg
   [15]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/fontawesome/regular/laugh-wink.svg
   [16]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/octicons/repo-push-16.svg
diff --git a/docs/reference/images.md b/docs/reference/images.md
index 4e4ba28f2..0606c3775 100644
--- a/docs/reference/images.md
+++ b/docs/reference/images.md
@@ -78,19 +78,24 @@ but it's always possible to resort to HTML. Using `figure` and `figcaption`, cap
 _Example_:
 
 ```html
-<figure>
-  <img src="https://dummyimage.com/600x400/eee/aaa" width="300" />
+<figure markdown> <!-- (1) -->
+  ![Dummy image](https://dummyimage.com/600x400/){ width="300" }
   <figcaption>Image caption</figcaption>
 </figure>
 ```
 
+1.  :man_raising_hand: Remember to enable the [Markdown in HTML] extension.
+
 _Result_:
 
-<figure>
-  <img src="https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–" width="300" />
+<figure markdown>
+  ![Dummy image]{ width="300" }
   <figcaption>Image caption</figcaption>
 </figure>
 
+  [Dummy image]: https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–
+  [Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html
+
 ### Image lazy-loading
 
 Modern browsers provide [native support for lazy-loading images][4] through the
diff --git a/docs/reference/lists.md b/docs/reference/lists.md
index 4944e2112..a11ade55f 100644
--- a/docs/reference/lists.md
+++ b/docs/reference/lists.md
@@ -39,7 +39,7 @@ configuring the style:
 
 :   :octicons-milestone-24: Default: `false` · This option toggles the rendering
     style of checkboxes, replacing native checkbox styles with beautiful icons, 
-    and is therefore _strongly recommended_:
+    and is therefore strongly recommended:
 
     ``` yaml
     markdown_extensions:
diff --git a/docs/setup/changing-the-language.md b/docs/setup/changing-the-language.md
index 4c53f2280..0794a34e6 100644
--- a/docs/setup/changing-the-language.md
+++ b/docs/setup/changing-the-language.md
@@ -24,7 +24,7 @@ theme:
 
 The following languages are supported:
 
-<div class="mdx-columns" markdown="1">
+<div class="mdx-columns" markdown>
 
 - `af` – Afrikaans
 - `ar` – Arabic
diff --git a/docs/setup/extensions/index.md b/docs/setup/extensions/index.md
index 9bbe19b07..77527429a 100644
--- a/docs/setup/extensions/index.md
+++ b/docs/setup/extensions/index.md
@@ -16,10 +16,11 @@ syntax extensions for technical writing.
 
 ## Supported extensions
 
-The following extensions are all supported by Material for MkDocs and therefore _strongly recommended_. Click on each extension to learn about its purpose and
+The following extensions are all supported by Material for MkDocs and therefore 
+strongly recommended. Click on each extension to learn about its purpose and
 configuration:
 
-<div class="mdx-columns" markdown="1">
+<div class="mdx-columns" markdown>
 
 - [Abbreviations]
 - [Admonition]
diff --git a/docs/setup/extensions/python-markdown-extensions.md b/docs/setup/extensions/python-markdown-extensions.md
index f2c2b1376..f06e2bcdf 100644
--- a/docs/setup/extensions/python-markdown-extensions.md
+++ b/docs/setup/extensions/python-markdown-extensions.md
@@ -13,19 +13,13 @@ installed with a supported version.
 
 ## Supported extensions
 
-The following extensions are all supported by Material for MkDocs and therefore
-_strongly recommended_. See the [overview][Extensions] page for a minimal and
-recommended configuration.
-
-  [Extensions]: index.md
-
 ### Arithmatex
 
 [:octicons-workflow-24: Extension][Arithmatex] ·
 [:octicons-tag-24: 1.0.0 ... present][Arithmatex support]
 
 The [Arithmatex] extension allows for rendering of block and inline block
-equations, and integrates seamlessly with [MathJax][^1] – a library for
+equations and integrates seamlessly with [MathJax][^1] – a library for
 mathematical typesetting. Enable it via `mkdocs.yml`:
 
   [^1]:
@@ -74,8 +68,8 @@ of [additional JavaScript]:
     ```
 
 The other configuration options of this extension are not officially supported
-by Material for MkDocs, so they may yield unexpected results. Use them at your
-own risk.
+by Material for MkDocs, which is why they may yield unexpected results. Use
+them at your own risk.
 
 See reference for usage:
 
@@ -284,8 +278,8 @@ The following configuration options are supported:
     ```
 
 The other configuration options of this extension are not officially supported
-by Material for MkDocs, so they may yield unexpected results. Use them at your
-own risk.
+by Material for MkDocs, which is why they may yield unexpected results. Use
+them at your own risk.
 
 See reference for usage:
 
@@ -323,7 +317,7 @@ markdown_extensions:
 
     However, this only applies for when [Pygments] is used. If you use a
     JavaScript syntax highlighter, [SuperFences][SuperFences #] might not
-    be necessary, but it's _strongly recommended_ anyway.
+    be necessary, but it's strongly recommended anyway.
 
 The following configuration options are supported:
 
@@ -407,8 +401,8 @@ The following configuration options are supported:
     or `pymdownx-inline` is recommended.
 
 The other configuration options of this extension are not officially supported
-by Material for MkDocs, so they may yield unexpected results. Use them at your
-own risk.
+by Material for MkDocs, which is why they may yield unexpected results. Use
+them at your own risk.
 
 See reference for usage:
 
@@ -478,9 +472,14 @@ MkDocs, as they only impact the Markdown parsing stage. The only exception is
 the [`class`][Keys options] option, which must not be changed. See the 
 [Keys documentation][Keys] for more information.
 
+See reference for usage:
+
+- [Adding keyboard keys]
+
   [Keys]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/
   [Keys support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
   [Keys options]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/#options
+  [Adding keyboard keys]: ../../reference/formatting.md#adding-keyboard-keys
 
 ### SmartSymbols
 
@@ -523,10 +522,12 @@ documentation][Snippets] for more information.
 
 See reference for usage:
 
+- [Adding a glossary]
 - [Embedding external files]
 
   [Snippets]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
   [Snippets support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
+  [Adding a glossary]: ../../reference/abbreviations.md#adding-a-glossary
   [Embedding external files]: ../../reference/code-blocks.md#embedding-external-files
 
 ### SuperFences
@@ -566,8 +567,8 @@ The following configuration options are supported:
     integrated with Material for MkDocs.
 
 The other configuration options of this extension are not officially supported
-by Material for MkDocs, so they may yield unexpected results. Use them at your
-own risk.
+by Material for MkDocs, which is why they may yield unexpected results. Use
+them at your own risk.
 
 See reference for usage:
 
@@ -619,8 +620,8 @@ The following configuration options are supported:
     ```
 
 The other configuration options of this extension are not officially supported
-by Material for MkDocs, so they may yield unexpected results. Use them at your
-own risk.
+by Material for MkDocs, which is why they may yield unexpected results. Use
+them at your own risk.
 
 See reference for usage:
 
@@ -658,7 +659,7 @@ The following configuration options are supported:
 
 :   :octicons-milestone-24: Default: `false` · This option toggles the rendering
     style of checkboxes, replacing native checkbox styles with beautiful icons, 
-    and is therefore _strongly recommended_:
+    and is therefore strongly recommended:
 
     ``` yaml
     markdown_extensions:
@@ -679,8 +680,8 @@ The following configuration options are supported:
     ```
 
 The other configuration options of this extension are not officially supported
-by Material for MkDocs, so they may yield unexpected results. Use them at your
-own risk.
+by Material for MkDocs, which is why they may yield unexpected results. Use
+them at your own risk.
 
 See reference for usage:
 
diff --git a/docs/setup/extensions/python-markdown.md b/docs/setup/extensions/python-markdown.md
index f067af325..86521bc74 100644
--- a/docs/setup/extensions/python-markdown.md
+++ b/docs/setup/extensions/python-markdown.md
@@ -7,18 +7,12 @@ template: overrides/main.html
 Material for MkDocs supports a large number of [Python Markdown] extensions,
 which is part of what makes it so attractive for technical writing. Following
 is a list of all supported extensions, linking to the relevant sections of the
-reference for what features they need to be enabled.
+reference for which features they need to be enabled.
 
   [Python Markdown]: https://python-markdown.github.io/
 
 ## Supported extensions
 
-The following extensions are all supported by Material for MkDocs and therefore
-_strongly recommended_. See the [overview][Extensions] page for a minimal and
-recommended configuration.
-
-  [Extensions]: index.md
-
 ### Abbreviations
 
 [:octicons-workflow-24: Extension][Abbreviations] ·
@@ -129,7 +123,7 @@ No configuration options are available. See reference for usage:
 [:octicons-tag-24: 1.0.0 ... present][Footnotes support]
 
 The [Footnotes] extension allows to define footnotes inline with the content,
-which are then rendered after the Markdown content of a document. Enable it
+which are then rendered below all Markdown content of a document. Enable it
 via `mkdocs.yml`:
 
 ``` yaml
@@ -153,8 +147,8 @@ No configuration options are supported. See reference for usage:
 [:octicons-tag-24: 1.0.0 ... present][Metadata support]
 
 The [Metadata] extension adds the ability to attach arbitrary key-value pairs
-to a document via front matter written in YAML syntax before the Markdown. It
-can be enabled via `mkdocs.yml`:
+to a document via front matter written in YAML syntax before the Markdown.
+Enable it via `mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:
@@ -180,9 +174,9 @@ No configuration options are available. See reference for usage:
 [:octicons-workflow-24: Extension][Markdown in HTML] ·
 [:octicons-tag-24: 0.1.0 ... present][Markdown in HTML support]
 
-The [Markdown in HTML] extension allows the author to write Markdown inside of
-HTML, which is useful for wrapping Markdown with custom markup. Enable it via
-`mkdocs.yml`:
+The [Markdown in HTML] extension allows for writing Markdown inside of HTML,
+which is useful for wrapping Markdown content with custom elements. Enable it
+via `mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:
@@ -191,8 +185,8 @@ markdown_extensions:
 
 > By default, Markdown ignores any content within a raw HTML block-level
 > element. With the `md_in_html` extension enabled, the content of a raw HTML
-> block-level element can be parsed as Markdown by including a markdown
-> attribute on the opening tag. The markdown attribute will be stripped from
+> block-level element can be parsed as Markdown by including a `markdown`
+> attribute on the opening tag. The `markdown` attribute will be stripped from
 > the output, while all other attributes will be preserved.
 
 No configuration options are available. See reference for usage:
@@ -290,7 +284,7 @@ The following configuration options are supported:
         ```
 
 The other configuration options of this extension are not officially supported
-by Material for MkDocs, so they may yield unexpected results. Use them at your
+by Material for MkDocs, which is why they may yield unexpected results. Use them at your
 own risk.
 
   [Table of Contents]: https://python-markdown.github.io/extensions/toc/
@@ -345,9 +339,9 @@ nesting, and therefore strongly recommended.
 [:octicons-workflow-24: Extension][CodeHilite] ·
 [:octicons-tag-24: 0.1.0 ... 5.5.14][CodeHilite support]
 
-Superseded by [Highlight]. Support for CodeHilite was dropped in version 6.0.0,
-as [Highlight] has a better integration with other essential extensions like 
-[SuperFences] and [InlineHilite].
+Superseded by [Highlight]. Support for CodeHilite was dropped in
+:octicons-tag-24: 6.0.0, as [Highlight] has a better integration with other 
+essential extensions like [SuperFences] and [InlineHilite].
 
   [CodeHilite]: https://python-markdown.github.io/extensions/code_hilite/
   [CodeHilite support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
diff --git a/docs/setup/setting-up-site-search.md b/docs/setup/setting-up-site-search.md
index a5c8b3dc1..35b8e8199 100644
--- a/docs/setup/setting-up-site-search.md
+++ b/docs/setup/setting-up-site-search.md
@@ -65,7 +65,7 @@ The following options are supported:
 
     The following languages are supported:
 
-    <div class="mdx-columns" markdown="1">
+    <div class="mdx-columns" markdown>
 
     - `ar` – Arabic
     - `da` – Danish
diff --git a/docs/setup/setting-up-social-cards.md b/docs/setup/setting-up-social-cards.md
index b86fa5085..8771c6ffa 100644
--- a/docs/setup/setting-up-social-cards.md
+++ b/docs/setup/setting-up-social-cards.md
@@ -39,11 +39,11 @@ plugins:
 
 For example, the page on [setting up site analytics][5] renders as:
 
-<figure markdown="1">
+<figure markdown>
 
 [![Social Cards][6]][6]
 
-  <figcaption markdown="1">
+  <figcaption markdown>
 
 Want to try it out? Copy the current URL and paste it into [Twitter's Card
 validator][7] to see how social cards look in action.
diff --git a/docs/setup/setting-up-versioning.md b/docs/setup/setting-up-versioning.md
index 9257cc737..afc5fb790 100644
--- a/docs/setup/setting-up-versioning.md
+++ b/docs/setup/setting-up-versioning.md
@@ -31,11 +31,11 @@ extra:
 This will render a version selector in the header next to the title of your
 project:
 
-<figure markdown="1">
+<figure markdown>
 
 [![Version selection][3]][3]
 
-  <figcaption markdown="1">
+  <figcaption markdown>
 
 A demo is worth a thousand words — check it out at
 [squidfunk.github.io/mkdocs-material-example-versioning][4]
@@ -141,8 +141,8 @@ the current page:
     docs.example.com/0.1/bar/ -> docs.example.com/0.2/
     ```
 
-<figure markdown="1">
-  <figcaption markdown="1">
+<figure markdown>
+  <figcaption markdown>
 
 A demo is worth a thousand words — check it out at
 [squidfunk.github.io/mkdocs-material-example-versioning][4]
diff --git a/src/assets/stylesheets/main/extensions/markdown/_admonition.scss b/src/assets/stylesheets/main/extensions/markdown/_admonition.scss
index b707db33f..f24e79a7c 100644
--- a/src/assets/stylesheets/main/extensions/markdown/_admonition.scss
+++ b/src/assets/stylesheets/main/extensions/markdown/_admonition.scss
@@ -150,12 +150,6 @@ $admonitions: (
         left: initial;
       }
     }
-
-    // Adjust spacing on last tabbed block container child - if the tabbed
-    // block container is the sole child, it looks better to omit the margin
-    + .tabbed-set:last-child {
-      margin-top: 0;
-    }
   }
 }