diff --git a/docs/insiders/index.md b/docs/insiders/index.md
index 99890dced..c5b2b89fe 100644
--- a/docs/insiders/index.md
+++ b/docs/insiders/index.md
@@ -150,7 +150,7 @@ The following features are currently exclusively available to sponsors:
 - [x] [Stay on page when switching versions][28]
 - [x] [Version warning][26]
 - [x] [Custom admonition icons][31]
-- [x] [Code block annotations][25]
+- [x] [Code annotations][25]
 - [x] [Anchor tracking ][24]
 - [x] [Mermaid.js integration][27]
 
@@ -173,7 +173,7 @@ the public for general availability.
 #### $ 4,000 – Ghost Pepper
 
 - [x] [Anchor tracking][24]
-- [x] [Code block annotations][25]
+- [x] [Code annotations][25]
 - [x] [Version warning][26]
 
 [24]: ../setup/setting-up-navigation.md#anchor-tracking
diff --git a/docs/reference/abbreviations.md b/docs/reference/abbreviations.md
index 8220d90e5..ff134ff2b 100644
--- a/docs/reference/abbreviations.md
+++ b/docs/reference/abbreviations.md
@@ -11,43 +11,31 @@ enable site-wide glossaries.
 
 ## Configuration
 
-### Abbreviations
-
-[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
-
-The [Abbreviations][2] 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:
+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
 markdown_extensions:
   - abbr
-```
-
-  [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_typeset.scss
-  [2]: https://python-markdown.github.io/extensions/abbreviations/
-
-### Snippets
-
-The [Snippets][3] extension, which is part of [Python Markdown Extensions][4], 
-allows to __insert content from other files__ or other, regular content, and can
-be enabled via `mkdocs.yml`:
-
-``` yaml
-markdown_extensions:
   - pymdownx.snippets
 ```
 
-  [3]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
-  [4]: https://facelessuser.github.io/pymdown-extensions/
+See additional configuration options:
+
+- [Abbreviations]
+- [Snippets]
+
+  [Abbreviations]: ../setup/extensions/python-markdown.md#abbreviations
+  [Snippets]: ../setup/extensions/python-markdown-extensions.md#snippets
 
 ## Usage
 
 ### Adding abbreviations
 
-When the [Abbreviations][5] extension is enabled, abbreviations can be defined
-with a special syntax similar to URLs and [footnotes][6] at any point in the
-Markdown document.
+Abbreviations can be defined by using a special syntax similar to URLs and 
+[footnotes], starting with a `*` and immediately followed by the term or
+acronym to be associated in square brackets.
 
 _Example_:
 
@@ -65,18 +53,23 @@ The HTML specification is maintained by the W3C.
 *[HTML]: Hyper Text Markup Language
 *[W3C]: World Wide Web Consortium
 
-  [5]: #abbreviations_1
-  [6]: footnotes.md
+  [footnotes]: footnotes.md
 
 ### Adding a glossary
 
-When [Snippets][7] 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.
+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
+[`--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.
 
 _Example_:
 
-=== "`docs/page.md`"
+=== ":octicons-file-code-16: docs/page.md"
 
     ```` markdown
     The HTML specification is maintained by the W3C.
@@ -84,7 +77,7 @@ _Example_:
     --8<-- "includes/abbreviations.md"
     ````
 
-=== "`includes/abbreviations.md`"
+=== ":octicons-file-code-16: includes/abbreviations.md"
 
     ```` markdown
     *[HTML]: Hyper Text Markup Language
@@ -95,8 +88,4 @@ _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._
-
-  [7]: #snippets
+  [Snippets notation]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippets-notation
diff --git a/docs/reference/admonitions.md b/docs/reference/admonitions.md
index a1895f4d0..c87a17e5a 100644
--- a/docs/reference/admonitions.md
+++ b/docs/reference/admonitions.md
@@ -11,9 +11,9 @@ inclusion and nesting of arbitrary content.
 
 ## Configuration
 
-The following configuration enables admonitions, allows to make them collapsible
-and to nest arbitrary content inside admonition bodies. Add the following lines
-to `mkdocs.yml`:
+This configuration enables admonitions, allows to make them collapsible and to
+nest arbitrary content inside admonition bodies. Add the following lines to
+`mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:
@@ -111,9 +111,9 @@ _Result_:
 
 ### Collapsible blocks
 
-If the [Details] extension is enabled and an admonition is started with `???` 
-instead of `!!!`, the admonition is rendered as a collapsible block with a
-small marker on the right side.
+When [Details] is enabled and an admonition block is started with `???` instead
+of `!!!`, the admonition is rendered as a collapsible block with a small toggle
+on the right side.
 
 _Example_:
 
@@ -155,6 +155,9 @@ _Result_:
 
 ### Inline blocks
 
+:octicons-beaker-24: Experimental ·
+[:octicons-tag-24: 7.0.0 ... present][Inline support]
+
 Admonitions can also be rendered as inline blocks (i.e. for sidebars), placing
 them to the right using the `inline` + `end` modifiers, or to the left using
 only the `inline` modifier.
@@ -208,6 +211,8 @@ prior to the content block you want to place them beside. If there's
 insufficient space to render the admonition next to the block, the admonition
 will stretch to the full width of the viewport, e.g. on mobile viewports.
 
+  [Inline support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.0.0
+
 ### Supported types
 
 Following is a list of type qualifiers provided by Material for MkDocs, whereas
@@ -318,7 +323,8 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
 
 ### Changing the icons
 
-> This feature is currently only available in [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders }
+[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
+[: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
@@ -385,6 +391,9 @@ a valid icon in `mkdocs.yml`:
 
 ### Custom admonitions
 
+[:octicons-file-code-24: Source][Source] ·
+:octicons-mortar-board-24: Difficulty: _easy_
+
 If you want to add a custom admonition type, all you need is a color and an
 `*.svg` icon. Copy the icon's code from the [`.icons`][Custom icons] folder
 and add the following CSS to an [additional stylesheet]:
@@ -439,6 +448,7 @@ _Example_:
 
 ``` markdown
 !!! pied-piper "Pied Piper"
+
     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.
@@ -452,6 +462,7 @@ _Result_:
     nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
     massa, nec semper lorem quam in massa.
 
+  [Source]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_admonition.scss
   [Custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
   [Custom animations]: icons-emojis.md#with-animations
   [additional stylesheet]: ../customization.md#additional-css
diff --git a/docs/reference/buttons.md b/docs/reference/buttons.md
index 6370a9e46..87f824294 100644
--- a/docs/reference/buttons.md
+++ b/docs/reference/buttons.md
@@ -10,74 +10,75 @@ useful for documents or landing pages with dedicated _call-to-actions_.
 
 ## Configuration
 
-### Attribute List
-
-The [Attribute List][1] 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`
+This configuration allows to add attributes to all inline- and block-level
+elements with a simple syntax, turning any link into a button. Add the
+following lines to `mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:
   - attr_list
 ```
 
-  [1]: https://python-markdown.github.io/extensions/attr_list/
+See additional configuration options:
+
+- [Attribute Lists]
+
+  [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
 
 ## Usage
 
 ### Adding buttons
 
-When the [Attribute List][2] extension is enabled, any clickable element can be
-converted into a button by adding the `.md-button` CSS class, which will receive
-the selected [primary color][3].
+In order to render a link as a button, suffix it with curly braces and add the
+`#!css .md-button` class selector to it. The button will receive the selected
+[primary color] and [accent color] if active.
 
 _Example_:
 
 ``` markdown
-[Subscribe to our mailing list](#){ .md-button }
+[Don't click me](#){ .md-button }
 ```
 
 _Result_:
 
-[Subscribe to our mailing list][4]{ .md-button }
+[Don't click me][Demo]{ .md-button }
 
-  [2]: #attribute-list
-  [3]: ../setup/changing-the-colors.md#primary-color
-  [4]: javascript:alert$.next("Done!")
+  [primary color]: ../setup/changing-the-colors.md#primary-color
+  [accent color]: ../setup/changing-the-colors.md#accent-color 
+  [Demo]: javascript:alert$.next("Hi!")
 
 ### Adding primary buttons
 
-If you want to display a filled, primary button (like on the [landing page][5]
-of Material for MkDocs), add both the `.md-button` and `.md-button--primary`
-CSS classes.
+If you want to display a filled, primary button (like on the [landing page]
+of Material for MkDocs), add both, the `#!css .md-button` and
+`#!css .md-button--primary` CSS class selectors.
 
 _Example_:
 
 ``` markdown
-[Subscribe to our mailing list](#){ .md-button .md-button--primary }
+[Don't click me](#){ .md-button .md-button--primary }
 ```
 
 _Result_:
 
-[Subscribe to our mailing list][4]{ .md-button .md-button--primary }
+[Don't click me][Demo]{ .md-button .md-button--primary }
 
-  [5]: ../index.md
+  [landing page]: ../index.md
 
 ### Adding icon buttons
 
-Of course, icons can be added to both types of buttons by using the [regular
-icon syntax][6] and referencing a valid path to [any icon bundled with the
-theme][7].
+Of course, icons can be added to all types of buttons by using the [icon syntax]
+together with any valid icon shortcode, which can be easily found with a few keystrokes through the [icon search].
 
 _Example_:
 
 ``` markdown
-[Submit :fontawesome-solid-paper-plane:](#){ .md-button .md-button--primary }
+[Send :fontawesome-solid-paper-plane:](#){ .md-button .md-button--primary }
 ```
 
 _Result_:
 
-[Submit :fontawesome-solid-paper-plane:][4]{ .md-button .md-button--primary }
+[Send :fontawesome-solid-paper-plane:][Demo]{ .md-button .md-button--primary }
 
-  [6]: icons-emojis.md#using-icons
-  [7]: icons-emojis.md#search
+  [icon syntax]: icons-emojis.md#using-icons
+  [icon search]: icons-emojis.md#search
diff --git a/docs/reference/code-blocks.md b/docs/reference/code-blocks.md
index 0b5201cd7..fe0b25ff3 100644
--- a/docs/reference/code-blocks.md
+++ b/docs/reference/code-blocks.md
@@ -6,191 +6,88 @@ template: overrides/main.html
 
 Code blocks and examples are an essential part of technical project
 documentation. Material for MkDocs provides different ways to set up syntax
-highlighting for code blocks, either during build time using [Pygments][1] or
+highlighting for code blocks, either during build time using [Pygments] or
 during runtime using a JavaScript syntax highlighter.
 
-  [1]: https://pygments.org
+  [Pygments]: https://pygments.org
 
 ## Configuration
 
-### Highlight
-
-[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3] ·
-:octicons-zap-24: Supersedes: [CodeHilite][4]
-
-The [Highlight][3] extension, which is part of [Python Markdown Extensions][5],
-integrates with Material for MkDocs and provides several options for
-configuring syntax highlighting of code blocks:
-
-`use_pygments`{ #use-pygments }
-
-:   :octicons-milestone-24: Default: `true` – This option allows to control
-    whether highlighting should be carried out during build time by
-    [Pygments][1] or runtime with a JavaScript highlighter. Remember to add the
-    necessary  [additional stylesheets][6] and [JavaScript][7] if you want to
-    use the latter:
-
-    === "Pygments"
-
-        ``` yaml
-        markdown_extensions:
-          - pymdownx.highlight
-          - pymdownx.superfences
-        ```
-
-    === "JavaScript"
-
-        ``` yaml
-        markdown_extensions:
-          - pymdownx.highlight:
-              use_pygments: false
-        ```
-
-    ??? example "Syntax highlighting with Highlight.js"
-
-        [Highlight.js][8] can be integrated by creating an [additional
-        JavaScript][7] file initializing the highlighter and including the 
-        respective stylesheet and JavaScript from a [CDN][9] serving
-        Highlight.js in `mkdocs.yml`:
-
-        === "`docs/javascripts/config.js`"
-
-            ``` js
-            document$.subscribe(() => {
-              hljs.highlightAll()
-            })
-            ```
-
-        === "`mkdocs.yml`"
-
-            ``` yaml
-            extra_javascript:
-              - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/highlight.min.js
-              - javascripts/config.js
-            extra_css:
-              - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/styles/default.min.css
-            ```
-
-        Note that Highlight.js has no affiliation with the Highlight extension.
-
-`linenums`{ #linenums }
-
-:   :octicons-milestone-24: Default: `false` – This option will add line numbers
-    to _all_ code blocks. If you wish to add line numbers to _some_, but not all
-    code blocks, consult the section on [adding line numbers][10] later in this
-    document, which also contains some tips on working with line numbers:
-
-    ``` yaml
-    markdown_extensions:
-      - pymdownx.highlight:
-          linenums: true
-    ```
-
-`linenums_style`{ #linenums-style }
-
-:   :octicons-milestone-24: Default: `table` – The Highlight extension provides
-    three ways to add line numbers, all of which are supported by Material for
-    MkDocs. While `table` wraps a code block in a table, `inline` and
-    `pymdownx-inline` render line numbers as part of the line itself:
-
-    ``` yaml
-    markdown_extensions:
-      - pymdownx.highlight:
-          linenums_style: pymdownx-inline
-    ```
-
-    Note that `inline` will put line numbers next to the actual code, which
-    means that they will be included when selecting text with the cursor or 
-    copying a code block to the clipboard. Thus, the usage of `table` or
-    `pymdownx-inline` is recommended.
-
-_Material for MkDocs doesn't provide official support for the other options of
-this extension, so they may be supported but might yield unexpected results.
-Use them at your own risk._
-
-  [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
-  [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-css
-  [7]: ../customization.md#additional-javascript
-  [8]: https://highlightjs.org/
-  [9]: https://cdnjs.com/libraries/highlight.js/
-  [10]: #adding-line-numbers
-
-### InlineHilite
-
-[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][11]
-
-The [InlineHilite][11] extension, which is part of [Python Markdown 
-Extensions][5] also integrates with Material for MkDocs and adds support for
-__syntax highlighting of inline code blocks__. It's built on top of the
-[Highlight][3] extension and can be enabled via `mkdocs.yml`:
+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`
 
 ``` yaml
 markdown_extensions:
+  - pymdownx.highlight
   - pymdownx.inlinehilite
-```
-
-See the section on [inline code blocks][12] for usage information.
-
-  [11]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
-  [12]: #highlighting-inline-code-blocks
-
-### Keys
-
-[:octicons-file-code-24: Source][13] · [:octicons-workflow-24: Extension][14]
-
-The [Keys][14] extension, which is part of [Python Markdown Extensions][5],
-allows for inserting __keyboard keys__, e.g. ++ctrl+alt+delete++ , and
-can be enabled via `mkdocs.yml`:
-
-``` yaml
-markdown_extensions:
-  - pymdownx.keys
-```
-
-  [13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_keys.scss
-  [14]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/
-
-### SuperFences
-
-The [SuperFences][15] extension, which is also part of [Python Markdown
-Extensions][5], allows for the __nesting of code blocks inside other blocks__,
-and is therefore strongly recommended:
-
-``` yaml
-markdown_extensions:
   - pymdownx.superfences
-```
-
-  [15]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
-
-### Snippets
-
-The [Snippets][16] extension, which is also part of [Python Markdown
-Extensions][5], allows to __insert content from other files__ or other, regular
-content, and can be enabled via `mkdocs.yml`:
-
-``` yaml
-markdown_extensions:
   - pymdownx.snippets
 ```
 
-  [16]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
+See additional configuration options:
+
+- [Highlight]
+- [InlineHilite]
+- [SuperFences]
+- [Snippets]
+
+  [Highlight]: ../setup/extensions/python-markdown-extensions.md#highlight
+  [InlineHilite]: ../setup/extensions/python-markdown-extensions.md#inlinehilite
+  [SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
+  [Snippets]: ../setup/extensions/python-markdown-extensions.md#snippets
+
+### Code annotations
+
+[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
+:octicons-beaker-24: Experimental ·
+[:octicons-tag-24: insiders-2.2.0 ... present][Insiders]
+
+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
+`mkdocs.yml` to enable them globally:
+
+``` yaml
+theme:
+  features:
+    - content.code.annotate # (1)
+```
+
+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"
+
+    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
+    code block by using a slightly different syntax based on the
+    [Attribute List] extension:
+
+    ```` yaml
+    ``` { .yaml .annotate }
+    # Code block content
+    ```
+    ````
+
+    Note that the language shortcode which has to come first must now also be 
+    prefixed by a `.`.
+
+  [Insiders]: ../insiders/index.md
+  [Attribute List]: ../setup/extensions/python-markdown.md#attribute-lists
 
 ## Usage
 
 This section discusses how to use different syntax highlighting features with
-[Pygments][1] – the default highlighter – so they don't apply when using
+[Pygments] – the default highlighter – so they don't apply when using
 a JavaScript syntax highlighter.
 
 ### Specifying the language
 
 Code blocks must be enclosed with two separate lines containing three backticks.
-To add code highlighting to those blocks, add the language short name directly
-after the opening block. See the [list of available lexers][17] to find the
-short name for a given language.
+To add syntax highlighting to those blocks, add the language shortcode directly
+after the opening block. See the [list of available lexers] to find the
+shortcode for a given language.
 
 _Example_:
 
@@ -206,117 +103,50 @@ _Result_:
 import tensorflow as tf
 ```
 
-  [17]: https://pygments.org/docs/lexers/
+  [list of available lexers]: https://pygments.org/docs/lexers/
 
 ### Adding annotations
 
-[:octicons-file-code-24: Source][18] ·
-:octicons-beaker-24: Experimental ·
-[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][18]{ .mdx-insiders }
+Code annotations can be placed anywhere in a code block where a comment for the
+language of the block can be placed, e.g. for JavaScript in `#!js // ...` and
+`#!js /* ... */`, for Yaml `#!yaml # ...`, etc.[^1]
 
-Annotations offer a comfortable and friendly way to attach explanations to
-arbitrary sections of code blocks by adding simple markers within block/inline
-comments that refer to items of a list following the code block, i.e. `(1)`,
-`(2)`, etc. Material for MkDocs detaches the list from the flow of the document,
-injects the content of each list item into a tooltip, and links each list marker
-to the corresponding tooltip.
+  [^1]:
+    Code annotations require syntax highlighting with [Pygments] – they're
+    currently not compatible with JavaScript syntax highlighters. Support will
+    be added at a later point, allowing to always place code annotations at the
+    end of lines.
 
-In order to opt-in to annotation support, a slightly different syntax is
-required – just add the respective [language short code][17] and the `.annotate`
-class, after the three backticks. Alternatively, if you want to enable annotations
-globally, add the following to `mkdocs.yml`:
+_Example_:
+
+```` markdown
+``` yaml
+theme:
+  features:
+    - content.code.annotate # (1)
+```
+
+1.  :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
+    text__, images, ... basically anything that can be expressed in Markdown.
+````
+
+_Result_:
 
 ``` yaml
 theme:
   features:
-    - content.code.annotate
+    - content.code.annotate # (1)
 ```
 
-Note that annotations can be __placed anywhere__ in a code block where a comment
-for the language can be placed, which for JavaScript is `// (1)` and
-`/* (2) */`, for Yaml `# (3)`, etc.
-
-_Example_:
-
-```` markdown
-``` js
-document$.subscribe(function() { // (1)
-  var tables = document.querySelectorAll(/* (2) */ "article table")
-  tables.forEach(function(table) {
-    new Tablesort(table)
-  })
-})
-```
-
-1. ...
-2. ...
-````
-
-_Result_:
-
-``` js
-document$.subscribe(function() { // (1)
-  var tables = document.querySelectorAll(/* (2) */ "article table")
-  tables.forEach(function(table) {
-    new Tablesort(table) // (3)
-  })
-})
-```
-
-1. Annotations can contain __arbitrary content__ which is shown when the marker
-   is focussed, including any kind of formatting, links, admonitions, details,
-   and even diagrams:
-
-    ``` mermaid
-    graph LR
-      A[I'm] --> B{a} --> C[diagram];
-    ```
-
-    :octicons-light-bulb-16:
-    **Tip:** You can use ++tab++ to navigate annotations.
-
-2. Annotations can be __placed anywhere__ in a code block were a comment for the
-   underlying language can be placed. 
-
-    === "Python"
-
-        ``` python
-        # (1)
-        ```
-
-    === "JavaScript"
-
-        ``` js
-        // (2)
-        /* (2) */
-        ```
-
-    === "Lua"
-
-        ``` lua
-        -- (3)
-        ```
-
-    _We're working on a solution for languages without comments, which will be
-    available shortly._
-
-  1. Of course, this can be combined with [line numbers][10], highlighting and
-     all other code block related features.
-
-_Annotations require syntax highlighting with [Pygments][26] – they're currently
-not compatible with other JavaScript-based syntax highlighters. Support may be
-added later on._
-
-  [18]: ../insiders/index.md
-  [19]: ../assets/screenshots/annotations.png
-  [20]: https://squidfunk.github.io/mkdocs-material-insiders/reference/code-blocks/#adding-annotations
+1.  :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
+    text__, images, ... basically anything that can be expressed in Markdown.
 
 ### Adding line numbers
 
 Line numbers can be added to a code block by using the `linenums="<start>"`
-option directly after the short name, whereas `<start>` represents the starting
+option directly after the shortcode, whereas `<start>` represents the starting
 line number. A code block can start from a line number other than `1`, which
-allows splitting large code blocks for readability.
+allows to split large code blocks for readability.
 
 _Example_:
 
@@ -343,60 +173,65 @@ def bubble_sort(items):
 ### Highlighting specific lines
 
 Specific lines can be highlighted by passing the line numbers to the `hl_lines`
-argument placed right after the language short name. Note that line counts start
-at `1`, regardless of the starting line number specified as part of `linenums`.
+argument placed right after the language shortcode. Note that line counts start
+at `1`, regardless of the starting line number specified as part of
+[`linenums`][Adding line numbers].
 
-_Example_:
+=== "Line numbers"
 
-```` markdown
-``` python hl_lines="2 3"
-def bubble_sort(items):
-    for i in range(len(items)):
-        for j in range(len(items) - 1 - i):
-            if items[j] > items[j + 1]:
-                items[j], items[j + 1] = items[j + 1], items[j]
-```
-````
+    _Example_:
 
-_Result_:
+    ```` markdown
+    ``` python hl_lines="2 3"
+    def bubble_sort(items):
+        for i in range(len(items)):
+            for j in range(len(items) - 1 - i):
+                if items[j] > items[j + 1]:
+                    items[j], items[j + 1] = items[j + 1], items[j]
+    ```
+    ````
 
-``` python hl_lines="2 3"
-def bubble_sort(items):
-    for i in range(len(items)):
-        for j in range(len(items) - 1 - i):
-            if items[j] > items[j + 1]:
-                items[j], items[j + 1] = items[j + 1], items[j]
-```
+    _Result_:
 
-Line ranges can also be used for conveniently specifying multiple lines.
+    ``` python hl_lines="2 3"
+    def bubble_sort(items):
+        for i in range(len(items)):
+            for j in range(len(items) - 1 - i):
+                if items[j] > items[j + 1]:
+                    items[j], items[j + 1] = items[j + 1], items[j]
+    ```
 
-_Example_:
+=== "Line ranges"
 
-```` markdown
-``` python hl_lines="2-5"
-def bubble_sort(items):
-    for i in range(len(items)):
-        for j in range(len(items) - 1 - i):
-            if items[j] > items[j + 1]:
-                items[j], items[j + 1] = items[j + 1], items[j]
-```
-````
+    _Example_:
 
-_Result_:
+    ```` markdown
+    ``` python hl_lines="2-5"
+    def bubble_sort(items):
+        for i in range(len(items)):
+            for j in range(len(items) - 1 - i):
+                if items[j] > items[j + 1]:
+                    items[j], items[j + 1] = items[j + 1], items[j]
+    ```
+    ````
 
-``` python hl_lines="2-5"
-def bubble_sort(items):
-    for i in range(len(items)):
-        for j in range(len(items) - 1 - i):
-            if items[j] > items[j + 1]:
-                items[j], items[j + 1] = items[j + 1], items[j]
-```
+    _Result_:
+
+    ``` python hl_lines="2-5"
+    def bubble_sort(items):
+        for i in range(len(items)):
+            for j in range(len(items) - 1 - i):
+                if items[j] > items[j + 1]:
+                    items[j], items[j + 1] = items[j + 1], items[j]
+    ```
+
+  [Adding line numbers]: #adding-line-numbers
 
 ### Highlighting inline code blocks
 
-When [InlineHilite][21] is enabled, inline code blocks can be highlighted by
-prefixing them with a shebang-like sequence, i.e. `#!`, directly followed by
-the [language short name][17].
+When [InlineHilite] is enabled, syntax highlighting can be applied to inline
+code blocks by prefixing them with a shebang, i.e. `#!`, directly followed by
+the corresponding [language shortcode][list of available lexers].
 
 _Example_:
 
@@ -408,33 +243,10 @@ _Result_:
 
 The `#!python range()` function is used to generate a sequence of numbers.
 
-  [21]: #inlinehilite
-
-### 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
-
 ### Embedding external files
 
-_Also known as transcludes or file transclusion in [MultiMarkdown][23]_.
-
-When [Snippets][24] is enabled, content from other files can be embedded, which
-is especially useful to reference and embed the contents of source files
-directly into your project documentation.
+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.
 
 _Example_:
 
@@ -450,23 +262,16 @@ _Result_:
 last 4 years
 ```
 
-Note that [Snippets][24] is not limited to code blocks, but can be used anywhere
-from a document to move repeating content to separate files, which is also
-explained in the [official documentation][16].
-
-  [23]: https://fletcher.github.io/MultiMarkdown-5/transclusion.html
-  [24]: #snippets
-
 ## Customization
 
 ### Custom syntax theme
 
-[:octicons-file-code-24: Source][25] ·
+[:octicons-file-code-24: Source][Source] ·
 :octicons-mortar-board-24: Difficulty: _easy_
 
-If [Pygments][26] is used, Material for MkDocs provides the [styles for code
-blocks][25], which are built with a custom and well-balanced palette that works
-equally well for both [color schemes][27]:
+If [Pygments] is used, Material for MkDocs provides the [styles for code blocks]
+[Source], which are built with a custom and well-balanced palette that works
+equally well for both [color schemes]:
 
 - :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-number-color) " } `--md-code-hl-number-color`
 - :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-special-color) " } `--md-code-hl-special-color`
@@ -488,10 +293,8 @@ Code block foreground, background and line highlight colors are defined via:
 - :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-color) " } `--md-code-hl-color`
 
 Let's say you want to change the color of `#!js "strings"`. While there are
-several [types of string tokens][28], Material for MkDocs assigns a single color
-to most of them.
-
-Create an [additional stylesheet][6], and add:
+several [types of string tokens], they use the same color. You can assign
+a new color by using an [additional stylesheet]:
 
 ``` css
 :root > * {
@@ -500,7 +303,7 @@ Create an [additional stylesheet][6], and add:
 ```
 
 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][29], and
+can lookup the specific class name in the [syntax theme definition], and
 override it as part of your additional stylesheet:
 
 ``` css
@@ -509,8 +312,8 @@ override it as part of your additional stylesheet:
 }
 ```
 
-  [25]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss#
-  [26]: #use-pygments
-  [27]: ../setup/changing-the-colors.md#color-scheme
-  [28]: https://pygments.org/docs/tokens/#literals
-  [29]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
+  [Source]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
+  [color schemes]: ../setup/changing-the-colors.md#color-scheme
+  [types of string tokens]: https://pygments.org/docs/tokens/#literals
+  [additional stylesheet]: ../customization.md#additional-css
+  [syntax theme definition]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
diff --git a/docs/reference/formatting.md b/docs/reference/formatting.md
index bb600c833..5bbab56a0 100644
--- a/docs/reference/formatting.md
+++ b/docs/reference/formatting.md
@@ -93,6 +93,24 @@ markdown_extensions:
   [7]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
   [8]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/
 
+### 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 
diff --git a/docs/setup/extensions/index.md b/docs/setup/extensions/index.md
index 40b826459..9bbe19b07 100644
--- a/docs/setup/extensions/index.md
+++ b/docs/setup/extensions/index.md
@@ -79,9 +79,9 @@ your documentation project.
 
 ### Minimal configuration
 
-The minimal configuration is a good starting point for when you're using
-Material for MkDocs for the first time. The best idea is to explore the
-[reference], and gradually add what you want to use:
+This configuration is a good starting point for when you're using Material for 
+MkDocs for the first time. The best idea is to explore the [reference], and 
+gradually add what you want to use:
 
 ``` yaml
 markdown_extensions:
@@ -100,8 +100,8 @@ markdown_extensions:
 
 ### Recommended configuration
 
-The recommended configuration enables all Markdown-related features of Material
-for MkDocs and is great for bootstrapping a new documentation project:
+This configuration enables all Markdown-related features of Material for MkDocs
+and is great for experienced users bootstrapping a new documentation project:
 
 ``` yaml
 markdown_extensions:
diff --git a/docs/setup/extensions/python-markdown.md b/docs/setup/extensions/python-markdown.md
index 82e50317b..f067af325 100644
--- a/docs/setup/extensions/python-markdown.md
+++ b/docs/setup/extensions/python-markdown.md
@@ -248,7 +248,7 @@ The following configuration options are supported:
 :   :octicons-milestone-24: Default: `headerid.slugify` – This option allows for
     customization of the slug function. For some languages, the default may not
     produce good and readable identifiers – consider using another slug function
-    like for example those from [Python Markdown Extensions][Pymdownx slug]:
+    like for example those from [Python Markdown Extensions][Slugs]:
 
     === "Unicode"
 
@@ -295,7 +295,7 @@ own risk.
 
   [Table of Contents]: https://python-markdown.github.io/extensions/toc/
   [Table of Contents support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
-  [Pymdownx slug]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
+  [Slugs]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
 
 ### Tables