Updated documentation

docs/reference/admonitions.md

@@ -299,7 +299,7 @@ will stretch to the full width of the viewport, e.g. on mobile viewports.
 Following is a list of type qualifiers provided by Material for MkDocs, whereas
 the default type, and thus fallback for unknown type qualifiers, is `note`:
 
-`note`{ #note }, ~~`seealso`~~ [^1]
+`note`{ #type-note }, ~~`seealso`~~ [^1]
 
 :   !!! note
 
@@ -307,7 +307,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-`abstract`{ #abstract }, `summary`, `tldr`
+`abstract`{ #type-abstract }, `summary`, `tldr`
 
 :   !!! abstract
 
@@ -315,7 +315,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-`info`{ #info }, `todo`
+`info`{ #type-info }, `todo`
 
 :   !!! info
 
@@ -323,7 +323,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-`tip`{ #tip }, `hint`, `important`
+`tip`{ #type-tip }, `hint`, `important`
 
 :   !!! tip
 
@@ -331,7 +331,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-`success`{ #success }, `check`, `done`
+`success`{ #type-success }, `check`, `done`
 
 :   !!! success
 
@@ -339,7 +339,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-`question`{ #question }, `help`, `faq`
+`question`{ #type-question }, `help`, `faq`
 
 :   !!! question
 
@@ -347,7 +347,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-`warning`{ #warning }, `caution`, `attention`
+`warning`{ #type-warning }, `caution`, `attention`
 
 :   !!! warning
 
@@ -355,7 +355,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-`failure`{ #failure }, `fail`, `missing`
+`failure`{ #type-failure }, `fail`, `missing`
 
 :   !!! failure
 
@@ -363,7 +363,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-`danger`{ #danger }, `error`
+`danger`{ #type-danger }, `error`
 
 :   !!! danger
 
@@ -371,7 +371,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-`bug`{ #bug }
+`bug`{ #type-bug }
 
 :   !!! bug
 
@@ -379,7 +379,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-`example`{ #example }
+`example`{ #type-example }
 
 :   !!! example
 
@@ -387,7 +387,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-`quote`{ #quote }, `cite`
+`quote`{ #type-quote }, `cite`
 
 :   !!! quote
 

docs/reference/images.md

@@ -120,16 +120,10 @@ _Result_:
 
 Modern browsers provide [native support for lazy-loading images][lazy-loading]
 through the `loading=lazy` directive, which degrades to eager-loading in
-browsers without support
+browsers without support:
-
-_Example_:
 
 ``` markdown
 ![Placeholder](https://dummyimage.com/600x400/eee/aaa){ loading=lazy }
 ```
 
-_Result_:
-
-![Placeholder](https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–){ loading=lazy width=300 }
-
   [lazy-loading]: https://caniuse.com/#feat=loading-lazy-attr

docs/setup/changing-the-colors.md

@@ -312,6 +312,9 @@ in the [color schemes][palette.scheme] section:
 === ":octicons-file-code-16: mkdocs.yml"
 
     ``` yaml
+    theme:
+      palette:
+        scheme: youtube
     extra_css:
       - stylesheets/extra.css
     ```

docs/setup/changing-the-language.md

@@ -132,12 +132,12 @@ The following properties must be set for each alternate language:
     the `hreflang` attribute of the link, improving discoverability via search
     engines.
 
-[![Language selector]][Language selector]
+[![Language selector preview]][Language selector preview]
 
   [alternate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.0.0
   [site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
   [ISO 639-1 language code]: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
-  [Language selector]: ../assets/screenshots/language-selection.png
+  [Language selector preview]: ../assets/screenshots/language-selection.png
 
 ### Directionality
 
@@ -180,23 +180,31 @@ Click on a tile to change the directionality:
 
 If you want to customize some of the translations for a language, just follow
 the guide on [theme extension] and create a new partial in the `overrides`
-folder. Then import the [translations] of your language as a fallback and only
+folder. Then, import the [translations] of the language as a fallback and only
 adjust the ones you want to override:
 
 === ":octicons-file-code-16: partials/languages/custom.html"
 
     ``` html
-    <!-- Import translations for your language as fallback -->
+    <!-- Import translations for language and fallback -->
-    {% import "partials/languages/" ~ config.theme.language ~ ".html" as fallback %}
+    {% import "partials/languages/de.html" as language %}
+    {% import "partials/languages/en.html" as fallback %} <!-- (1) -->
+
+    <!-- Define custom translations -->
     {% macro override(key) %}{{ {
-      "toc.title": "On this page" <!-- (1) -->
+      "toc.title": "Auf dieser Seite" <!-- (2) -->
     }[key] }}{% endmacro %}
 
     <!-- Re-export translations -->
-    {% macro t(key) %}{{ override(key) or fallback.t(key) }}{% endmacro %}
+    {% macro t(key) %}{{
+      override(key) or language(key) or fallback.t(key)
+    }}{% endmacro %}
     ```
 
-    1.  Check the [list of available languages], pick the translation you want
+    1.  Note that `en` must always be used as a fallback language, as it's the
+        default theme language.
+
+    2.  Check the [list of available languages], pick the translation you want
         to override for your language and add them here.
 
 === ":octicons-file-code-16: mkdocs.yml"

docs/setup/extensions/python-markdown-extensions.md

@@ -154,7 +154,7 @@ markdown_extensions:
 
 The following configuration options are supported:
 
-`mode`{ #mode }
+`mode`{ #critic-mode }
 
 :   :octicons-milestone-24: Default: `view` – This option defines how the markup 
     should be parsed, i.e. whether to just `view` all suggested changes, or
@@ -265,7 +265,7 @@ The following configuration options are supported:
 
 :   :octicons-milestone-24: Default: _none_ – This option allows to list folders
     with additional icon sets to be used in Markdown or `mkdocs.yml`, which is 
-    explained in more detail in the [icon customization guide].
+    explained in more detail in the [icon customization guide]:
 
     ``` yaml
     markdown_extensions:
@@ -318,7 +318,7 @@ markdown_extensions:
 
 The following configuration options are supported:
 
-`use_pygments`{ #use-pygments }
+`use_pygments`{ #highlight-use-pygments }
 
 :   :octicons-milestone-24: Default: `true` – This option allows to control
     whether highlighting should be carried out during build time using
@@ -365,7 +365,7 @@ The following configuration options are supported:
 
         Note that [Highlight.js] has no affiliation with the Highlight extension.
 
-`linenums`{ #linenums }
+`linenums`{ #highlight-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
@@ -379,7 +379,7 @@ The following configuration options are supported:
           linenums: true
     ```
 
-`linenums_style`{ #linenums-style }
+`linenums_style`{ #highlight-linenums-style }
 
 :   :octicons-milestone-24: Default: `table` – The [Highlight] extension
     provides three ways to add line numbers, all of which are supported by
@@ -544,7 +544,7 @@ markdown_extensions:
 
 The following configuration options are supported:
 
-`custom_fences`{ #custom-fences }
+`custom_fences`{ #superfences-custom-fences }
 
 :   :octicons-milestone-24: Default: _none_ – This option allows to define a
     handler for custom fences, e.g. to preserve the definitions of [Mermaid.js]
@@ -603,7 +603,7 @@ markdown_extensions:
 
 The following configuration options are supported:
 
-`alternate_style`{ #alternate-style }
+`alternate_style`{ #tabbed-alternate-style }
 
 :   :octicons-milestone-24: Default: `false` · [:octicons-tag-24: 7.3.1]
     [Tabbed alternate support] – This option enables the [alternate style] of
@@ -652,7 +652,7 @@ markdown_extensions:
 
 The following configuration options are supported:
 
-`custom_checkbox`{ #custom-checkbox }
+`custom_checkbox`{ #tasklist-custom-checkbox }
 
 :   :octicons-milestone-24: Default: `false` · This option toggles the rendering
     style of checkboxes, replacing native checkbox styles with beautiful icons, 
@@ -664,7 +664,7 @@ The following configuration options are supported:
           custom_checkbox: true
     ```
 
-`clickable_checkbox`{ #clickable-checkbox }
+`clickable_checkbox`{ #tasklist-clickable-checkbox }
 
 :   :octicons-milestone-24: Default: `false` · This option toggles whether
     checkboxes are clickable. As the state is not persisted, the use of this 

docs/setup/extensions/python-markdown.md

@@ -213,7 +213,7 @@ markdown_extensions:
 
 The following configuration options are supported:
 
-`permalink`{ #permalink }
+`permalink`{ #toc-permalink }
 
 :   :octicons-milestone-24: Default: `false` – This option adds an anchor link
     containing the paragraph symbol `¶` or another custom symbol at the end of
@@ -236,7 +236,7 @@ The following configuration options are supported:
               permalink: ⚓︎
         ```
 
-`slugify`{ #slugify }
+`slugify`{ #toc-slugify }
 
 :   :octicons-milestone-24: Default: `headerid.slugify` – This option allows for
     customization of the slug function. For some languages, the default may not
@@ -259,7 +259,7 @@ The following configuration options are supported:
               slugify: !!python/name:pymdownx.slugs.uslugify_cased
         ```
 
-`toc_depth`{ #toc_depth }
+`toc_depth`{ #toc-depth }
 
 :   :octicons-milestone-24: Default: `6` – Define the range of levels to be
     included in the table of contents. This may be useful for project

docs/setup/setting-up-navigation.md

@@ -317,7 +317,7 @@ hide:
 Material for MkDocs includes several keyboard shortcuts that make it possible
 to navigate your project documentation via keyboard. There're two modes:
 
-`search`{ #search }
+`search`{ #mode-search }
 
 :   This mode is active when the _search is focused_. It provides several key
     bindings to make search accessible and navigable via keyboard:
@@ -326,7 +326,7 @@ to navigate your project documentation via keyboard. There're two modes:
     * ++esc++ , ++tab++ : close search dialog
     * ++enter++ : follow selected result
 
-`global`{ #global }
+`global`{ #mode-global }
 
 :   This mode is active when _search is not focussed_ and when there's no other
     focussed element that is susceptible to keyboard input. The following keys

docs/setup/setting-up-site-analytics.md

@@ -6,25 +6,24 @@ template: overrides/main.html
 
 As with any other service offered on the web, understanding how your project
 documentation is actually used can be an essential success factor. Material for
-MkDocs natively integrates with [Google Analytics][1] and offers a customizable
+MkDocs natively integrates with [Google Analytics] and offers a customizable
-and extendable [cookie consent][2].
+and extendable [cookie consent][extra.consent].
 
-  [1]: https://developers.google.com/analytics
+  [Google Analytics]: https://developers.google.com/analytics
-  [2]: #cookie-consent
+  [extra.consent]: #cookie-consent
 
 ## Configuration
 
 ### Google Analytics
 
-:octicons-hash-24: Setting ·
+[:octicons-tag-24: 7.1.8][Google Analytics support] ·
-:octicons-milestone-24: Default: _none_ ·
+:octicons-milestone-24: Default: _none_
-[:octicons-tag-24: 7.1.8][Google Analytics support]
 
 Material for MkDocs integrates with both, Google Analytics 4 and the now phasing
-out Universal Analytics (`UA-*`). Depending on the prefix of the property, add
+out Universal Analytics (`UA-*`). Depending on the property prefix, add the
-the following to `mkdocs.yml`:
+following lines to `mkdocs.yml`:
 
-=== "Google Analytics 4"
+=== ":material-google-analytics: Google Analytics 4"
 
     ``` yaml
     extra:
@@ -33,7 +32,7 @@ the following to `mkdocs.yml`:
         property: G-XXXXXXXXXX
     ```
 
-=== "Universal Analytics"
+=== ":material-google-analytics: Universal Analytics"
 
     ``` yaml
     extra:
@@ -43,11 +42,10 @@ the following to `mkdocs.yml`:
     ```
 
   [Google Analytics support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.8
-  [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/integrations/analytics.html
 
 #### Site search tracking
 
-Besides basic page views, _site search_ can also be tracked to understand better
+Besides basic page views, site search can also be tracked to understand better
 how people use your documentation and what they expect to find. To enable
 search tracking:
 
@@ -57,21 +55,20 @@ search tracking:
 4.  Scroll down and enable __site search settings__
 5.  Set the __query parameter__ to `q`.
 
-_Site search tracking is not supported with Google Analytics 4 due to the much
+Site search tracking is not supported with Google Analytics 4 due to the more
-more complicated manual setup. If you want to set up site search tracking
+complicated manual setup. If you want to set up site search tracking yourself,
-yourself, [this tutorial][4] might be a good start._
+[this tutorial][tutorial] is a good start.
 
-  [4]: https://www.analyticsmania.com/post/track-site-search-with-google-tag-manager-and-google-analytics/
+  [tutorial]: https://www.analyticsmania.com/post/track-site-search-with-google-tag-manager-and-google-analytics/
 
 ### Cookie consent
 
 [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
-:octicons-hash-24: Setting ·
+[:octicons-tag-24: insiders-2.10.0][Insiders] ·
-:octicons-milestone-24: Default: _none_ ·
+:octicons-milestone-24: Default: _none_
-[:octicons-tag-24: insiders-2.10.0][Insiders]
 
-Material for MkDocs ships a native and extensible cookie consent form, which
+Material for MkDocs ships a native and extensible cookie consent form which
-asks the user for his consent prior to setting up analytics. Add the following
+asks the user for his consent prior to sending any analytics. Add the following
 to `mkdocs.yml`:
 
 ``` yaml
@@ -90,10 +87,10 @@ extra:
 
 Note that both, `title` and `description`, are required. If Google Analytics was
 configured via `mkdocs.yml`, the cookie consent will automatically include a
-setting for the user to disable it. Furthermore, [custom cookies][6] can be
+setting for the user to disable it. Furthermore, [custom cookies] can be
 integrated by using the `cookies` field:
 
-===  "Change cookie name"
+===  "Custom cookie name"
 
     ``` yaml
     extra:
@@ -104,7 +101,7 @@ integrated by using the `cookies` field:
 
     1. The default name of the `analytics` cookie is `Google Analytics`.
 
-===  "Add custom cookie"
+===  "Custom cookie"
 
     ``` yaml
     extra:
@@ -119,79 +116,87 @@ integrated by using the `cookies` field:
 
 When a user first visits your site, a cookie consent form is rendered:
 
-[![Cookie consent][7]][7]
+[![extra.consent enabled]][extra.consent enabled]
 
 In order to comply with GDPR, users must be able to change their cookie settings
 at any time. This can be done by creating a simple link as part of any document,
-e.g. privacy policy:
+e.g. your privacy policy:
 
 ``` markdown
 [Change cookie settings](#__consent){ .md-button }
 ```
 
   [Insiders]: ../insiders/index.md
-  [5]: ../insiders/index.md
+  [custom cookies]: #custom-cookies
-  [6]: #custom-cookies
+  [extra.consent enabled]: ../assets/screenshots/consent.png
-  [7]: ../assets/screenshots/consent.png
 
 ## Customization
 
 ### Custom site analytics
 
-[:octicons-file-code-24: Source][3] ·
-:octicons-mortar-board-24: Difficulty: _moderate_
-
 In order to integrate another analytics service provider offering a 
-JavaScript-based tracking solution, you can [extend the theme][8] and add a new 
+JavaScript-based tracking solution, just follow the guide on [theme extension]
-`custom.html` partial [here][9]. The name of the partial can then be used to 
+and create a new partial in the `overrides` folder. The name of the partial is
-configure the custom integration from `mkdocs.yml`:
+used to configure the custom integration via `mkdocs.yml`:
 
-``` yaml
+=== ":octicons-file-code-16: partials/integrations/analytics/custom.html"
-extra:
-  analytics:
-    provider: custom # (1)
-    key: value # (2)
-```
 
-1.  Of course, you can change the name to the partial to anything you like.
+    ``` html
-2.  You can add arbitrary `key` and `value` combinations to configure your custom
+    <script>
-    integration. This is especially useful if you're sharing the custom
+      /* Add custom analytics integration here, e.g. */
-    integration across multiple repositories.
+      var property = "{{ config.extra.analytics.property }}" // (1)
 
-  [8]: ../customization.md#extending-the-theme
+      /* Wait for page to load and application to mount */
-  [9]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/integrations/analytics
+      document.addEventListener("DOMContentLoaded", function() {
+        location$.subscribe(function(url) {
+          /* Add custom page event tracking here */ // (2)
+        })
+      })
+    </script>
+    ```
 
-#### Instant loading
+    1.  As an example, this variable receives the value set in `mkdocs.yml`,
+        which is `"foobar"` for `property`.
+    2.  If you're using [instant loading], you can use the `location$`
+        observable to listen for navigation events, which always emits the
+        current `URL`.
 
-If you're using [instant loading][10], you may use the `location$` observable,
+=== ":octicons-file-code-16: mkdocs.yml"
-which will emit the current `URL` to listen for navigation events and register
-a page view event with:
 
-``` js
+    ``` yaml
-location$.subscribe(function(url) {
+    extra:
-  /* Track a page event */
+      analytics:
-})
+        provider: custom
-```
+        property: foobar # (1)
+    ```
 
-Note that this must be integrated with [additional JavaScript][11].
+    1.  You can add arbitrary key-value combinations to configure your
+        custom integration. This is especially useful if you're sharing the
+        custom integration across multiple repositories.
 
-  [10]: setting-up-navigation.md#instant-loading
+  [theme extension]: ../customization.md#extending-the-theme
-  [11]: ../customization.md#additional-javascript
+  [instant loading]: setting-up-navigation.md#instant-loading
 
 ### Custom cookies
 
-[:octicons-file-code-24: Source][3] ·
+If you've customized the [cookie consent][extra.consent] and added a `custom`
-:octicons-mortar-board-24: Difficulty: _moderate_
+cookie, the user will be prompted to accept your custom cookie. Use [additional
+JavaScript] to check whether the user accepted it:
 
-If you've customized the [cookie consent][12] and added a `custom` cookie, the
+=== ":octicons-file-code-16: docs/javascripts/consent.js"
-user will be prompted to accept your custom cookie. Use
-[additional JavaScript][11] to check whether the user accepted it:
 
-``` js
+    ``` js
-var consent = __md_get("__consent")
+    var consent = __md_get("__consent")
-if (consent && consent.custom) {
+    if (consent && consent.custom) {
-  /* The user accepted the cookie */
+      /* The user accepted the cookie */
-}
+    }
-```
+    ```
 
-  [12]: #cookie-consent
+=== ":octicons-file-code-16: mkdocs.yml"
+
+    ``` yaml
+    extra_javascript:
+      - javascripts/consent.js
+    ```
+
+  [additional JavaScript]: ../customization.md#additional-javascript

docs/setup/setting-up-site-search.md

@@ -37,9 +37,9 @@ plugins:
 
 The following options are supported:
 
-`lang`{ #lang }
+`lang`{ #search-lang }
 
-:   :octicons-milestone-24: Default: _auto_ – This option allows
+:   :octicons-milestone-24: Default: _automatically set_ – This option allows
     to include the language-specific stemmers provided by [lunr-languages][5].
     Note that Material for MkDocs will set this automatically based on the
     [site language][6], but it may be overridden, e.g. to support multiple
@@ -98,9 +98,9 @@ The following options are supported:
         JavaScript payload by around 20kb (before `gzip`) and by another 15-30kb
         per language.
 
-`separator`{ #separator }
+`separator`{ #search-separator }
 
-:   :octicons-milestone-24: Default: _auto_ – The separator for
+:   :octicons-milestone-24: Default: _automatically set_ – The separator for
     indexing and query tokenization can be customized, making it possible to
     index parts of words separated by other characters than whitespace and `-`,
     e.g. by including `.`:
@@ -111,7 +111,7 @@ The following options are supported:
           separator: '[\s\-\.]+'
     ```
 
-~~`prebuild_index`~~{ #prebuild-index }[^1]
+~~`prebuild_index`~~{ #search-prebuild-index }[^1]
 
 :   :octicons-milestone-24: Default: `false` · :octicons-archive-24: Deprecated
     – MkDocs can generate a [prebuilt index][7] of all pages during

docs/setup/setting-up-social-cards.md

@@ -6,8 +6,8 @@ template: overrides/main.html
 
 Social cards, also known as social previews, are images that are displayed when
 a link to your project documentation is shared on social media. Material for
-MkDocs can generate beautiful social cards automatically, using the [colors][1],
+MkDocs can generate beautiful social cards automatically, using the [colors]
-[fonts][2] and [logo][3][^1] defined in `mkdocs.yml`.
+[palette.primary], [fonts][font.text] and [logo][^1] defined in `mkdocs.yml`.
 
   [^1]:
     Both types of logos, images (`theme.logo`) and icons (`theme.icon.logo`)
@@ -15,69 +15,66 @@ MkDocs can generate beautiful social cards automatically, using the [colors][1],
     color used in the header (white or black), which depends on the primary
     color.
 
-  [1]: changing-the-colors.md#primary-color
+  [palette.primary]: changing-the-colors.md#primary-color
-  [2]: changing-the-fonts.md#regular-font
+  [font.text]: changing-the-fonts.md#regular-font
-  [3]: changing-the-logo-and-icons.md#logo
+  [logo]: changing-the-logo-and-icons.md#logo
 
 ## Configuration
 
 ### Built-in social cards
 
 [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-2.12.0][Insiders] ·
 :octicons-cpu-24: Plugin ·
-:octicons-beaker-24: Experimental ·
+:octicons-beaker-24: Experimental
-[:octicons-tag-24: insiders-2.12.0][Insiders]
 
-The [built-in social cards plugin][4] generates a social card image for every
+The built-in social cards plugin generates a social preview image for every page
-page and adds the necessary meta tags, so it's displayed on social media when
+and adds the necessary meta tags, so it's displayed on social media when shared.
-shared. Enable it via `mkdocs.yml`:
+Enable it via `mkdocs.yml`:
 
 ``` yaml
 plugins:
   - social
 ```
 
-For example, the page on [setting up site analytics][5] renders as:
+For example, the page on [setting up site analytics] renders as:
 
 <figure markdown>
 
-[![Social Cards][6]][6]
+[![Social cards preview]][Social cards preview]
 
   <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.
+validator] to see how social cards look in action.
 
   </figcaption>
 </figure>
 
-This is a built-in plugin, which means that no third-party plugin needs to be 
+The following configuration options are available:
-installed, as Material for MkDocs already bundles it. The following options
-are available:
 
-`cards_color`{ #cards-color } :material-new-box:
+`cards_color`{ #cards-color }
 
-:   :octicons-milestone-24: Default: [`primary
+:   :octicons-milestone-24: Default: [primary color][palette.primary] + header
-    color`][8]_ – This option specifies which colors to use for the background
+    text color – This option specifies which colors to use for the background
-    `fill` and foreground `text` when generating the social card.
+    `fill` and foreground `text` when generating the social card:
 
     ``` yaml
     plugins:
       - social:
           cards_color:
-            fill: "#0FF1CE"
+            fill: "#0FF1CE" # (1)
             text: "#FFFFFF"
     ```
 
-    Note that the values for `fill` and `text` can either be HEX color values
+    1.  Colors can either be defined as HEX colors, or as [CSS color keywords].
-    (e.g. `#0FF1CE`, must be enclosed in quotes) or CSS color keywords (e.g.
+        Note that HEX colors must be enclosed in quotes.
-    `red`, `green`, etc.).
 
 `cards_directory`{ #cards-directory }
 
 :   :octicons-milestone-24: Default: `assets/images/social` – This option
-    specifies where the generated social card images will be written to. It
+    specifies where the generated social card images will be written to. It's
-    should normally not be necessary to change this option.
+    normally not necessary to change this option:
 
     ``` yaml
     plugins:
@@ -86,24 +83,23 @@ are available:
     ```
 
   [Insiders]: ../insiders/index.md
-  [4]: ../insiders/index.md
+  [setting up site analytics]: setting-up-site-analytics.md
-  [5]: setting-up-site-analytics.md
+  [Social cards preview]: ../assets/screenshots/social-cards.png
-  [6]: ../assets/screenshots/social-cards.png
+  [Twitter's Card validator]: https://cards-dev.twitter.com/validator
-  [7]: https://cards-dev.twitter.com/validator
+  [CSS color keywords]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords
-  [8]: changing-the-colors.md#primary-color
 
-#### Caching
+#### Caching <small>recommended</small> { data-toc-label="Caching" }
 
-When enabled, the [social cards plugin][9] automatically fetches the fonts you
+The [built-in social cards plugin] automatically fetches the fonts you define
-define in `mkdocs.yml` from Google Fonts, and uses them to render the text that
+in `mkdocs.yml` from Google Fonts, and uses them to render the text that is
-is displayed on the social card. The font files and generated cards are both
+displayed on the social card. The font files and generated cards are both
 written to the `.cache` directory, which is used in subsequent builds to detect
 whether the social cards need to be regenerated. You might want to:
 
 1.  Ignore the `.cache` directory in your project, by adding it to `.gitignore`.
 2.  When building your site for publishing, use a build cache to save the
     `.cache` directory in between builds. Taking the example from the
-    [publishing guide][10], add the following lines:
+    [publishing guide], add the following lines:
 
     ``` yaml hl_lines="15-18"
     name: ci
@@ -128,27 +124,14 @@ whether the social cards need to be regenerated. You might want to:
             - run: mkdocs gh-deploy --force
     ```
 
-  [9]: #built-in-social-cards
+  [built-in social cards plugin]: #built-in-social-cards
-  [10]: ../publishing-your-site.md#with-github-actions
+  [publishing guide]: ../publishing-your-site.md#with-github-actions
 
-## Usage
+#### Meta tags
 
-If you want to adjust the title or set a custom description for the social card,
+The [built-in social cards plugin] automatically sets all necessary `meta` tags,
-you can use the [Metadata][11] extension, which takes precedence over the
+equivalent to the following two customizations, which you can set manually when
-default values.
+you don't want to use it:
-
-- [Changing the title][12]
-- [Changing the description][13]
-
-  [11]: ../reference/meta-tags.md#metadata
-  [12]: ../reference/meta-tags.md#setting-the-page-title
-  [13]: ../reference/meta-tags.md#setting-the-page-description
-
-### Using social media meta tags
-
-The [built-in social cards plugin] generates beautiful image previews for social
-media during the build and sets all necessary `meta` tags, equivalent to the
-following two customizations:
 
 === ":material-graph: Open Graph"
 
@@ -158,7 +141,7 @@ following two customizations:
       {% if page and page.meta and page.meta.title %}
         {% set title = title ~ " - " ~ page.meta.title %}
       {% elif page and page.title and not page.is_homepage %}
-        {% set title = title ~ " - " ~ page.title | striptags %}
+        {% set title = title ~ " - " ~ page.title %}
       {% endif %}
       <meta property="og:type" content="website" />
       <meta property="og:title" content="{{ title }}" />
@@ -179,11 +162,9 @@ following two customizations:
       {% if page and page.meta and page.meta.title %}
         {% set title = title ~ " - " ~ page.meta.title %}
       {% elif page and page.title and not page.is_homepage %}
-        {% set title = title ~ " - " ~ page.title | striptags %}
+        {% set title = title ~ " - " ~ page.title %}
       {% endif %}
       <meta name="twitter:card" content="summary_large_image" />
-      <meta name="twitter:site" content="<username>" />
-      <meta name="twitter:creator" content="<username>" />
       <meta name="twitter:title" content="{{ title }}" />
       <meta name="twitter:description" content="{{ config.site_description }}" />
       <meta name="twitter:image" content="<url>" />
@@ -192,3 +173,17 @@ following two customizations:
 
   [Twitter Cards]: https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards
   [built-in social cards plugin]: ../setup/setting-up-social-cards.md#built-in-social-cards
+
+
+## Usage
+
+If you want to adjust the title or set a custom description for the social card,
+you can use the [Metadata] extension, which takes precedence over the
+default values.
+
+- [Changing the title]
+- [Changing the description]
+
+  [Metadata]: extensions/python-markdown.md#metadata
+  [Changing the title]: ../reference/meta-tags.md#setting-the-page-title
+  [Changing the description]: ../reference/meta-tags.md#setting-the-page-description

docs/setup/setting-up-tags.md

@@ -14,11 +14,11 @@ can help to discover relevant information faster.
 ### Built-in tags
 
 [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-2.7.0][Insiders] ·
 :octicons-cpu-24: Plugin ·
-:octicons-beaker-24: Experimental ·
+:octicons-beaker-24: Experimental
-[:octicons-tag-24: insiders-2.7.0][Insiders]
 
-The [built-in tags plugin][1] adds the ability to categorize any page with tags
+The built-in tags plugin adds the ability to categorize any page with tags
 as part of the front matter of the page. In order to add support for tags, add
 the following lines to `mkdocs.yml`:
 
@@ -27,15 +27,13 @@ plugins:
   - tags
 ```
 
-Note that no third-party plugin[^1] needs to be installed, as Material for
+The following configuration options are available:
-MkDocs provides its own implementation to allow for a meaningful integration.
-The following options are available:
 
 `tags_file`{ #tags-file }
 
 :   :octicons-milestone-24: Default: _none_ – This option specifies which file
     should be used to render the tags index. See the section on [adding a tags 
-    index][3] for more information. If this option is specified, tags will
+    index] for more information. If this option is specified, tags will
     become clickable, pointing to the corresponding section in the tags index:
 
     ``` yaml
@@ -49,29 +47,18 @@ The following options are available:
     option is not specified, tags are still rendered and searchable,
     but without a tags index.
 
-  [^1]:
-    The built-in tags plugin has no affiliation with [mkdocs-plugin-tags][2],
-    another option to add tag support to MkDocs, which has several caveats:
-    it requires a `title` set in the front matter for every page for which tags
-    should be added, doesn't support all syntactic flavors of front matter,
-    doesn't integrate tags in search and doesn't render tags on pages without
-    additional effort. The built-in tags plugin supports all of these
-    features out-of-the-box.
-
   [Insiders]: ../insiders/index.md
-  [1]: ../insiders/index.md
+  [adding a tags index]: #adding-a-tags-index
-  [2]: https://github.com/jldiaz/mkdocs-plugin-tags
-  [3]: #adding-a-tags-index
 
 ## Usage
 
 ### Adding tags
 
-If both, the [built-in tags plugin][4] and [Metadata][5] extension are enabled,
+When both, the [built-in tags plugin] and [Metadata] extension are enabled,
-tags can be added for any page as part of the front matter, e.g. to add the tags
+tags can be added for a document with custom front matter. Add the following
-`insiders` and `brand new` to this page, add:
+lines at the top of a Markdown file:
 
-``` yaml
+``` bash
 ---
 tags:
   - insiders
@@ -87,22 +74,22 @@ following screenshots:
 
 === "Tags"
 
-    [![Tags][6]][6]
+    [![Tags preview]][Tags preview]
 
 === "Tag search"
 
-    [![Tag search][7]][7]
+    [![Tag search preview]][Tag search preview]
 
-  [4]: #built-in-tags
+  [built-in tags plugin]: #built-in-tags
-  [5]: ../../reference/meta-tags/#metadata
+  [Metadata]: extensions/python-markdown.md#metadata
-  [6]: ../assets/screenshots/tags.png
+  [Tags preview]: ../assets/screenshots/tags.png
-  [7]: ../assets/screenshots/tags-search.png
+  [Tag search preview]: ../assets/screenshots/tags-search.png
 
 ### Adding a tags index
 
-The [built-in tags plugin][4] allows to define a file to render a [tags
+The [built-in tags plugin] allows to define a file to render a [tags index]
-index][8], which can be any page that is part of the `nav` section. To add a
+[tags.tags_file], which can be any page that is part of the `nav` section. To
-tags index, create a page, e.g. `tags.md`:
+add a tags index, create a page, e.g. `tags.md`:
 
 ``` markdown
 # Tags
@@ -118,14 +105,14 @@ arbitrary content before and after the marker:
 
 [![Tags index][9]][9]
 
-  [8]: #tags_file
+  [tags.tags_file]: #tags-file
   [9]: ../assets/screenshots/tags-index.png
 
 ### Hiding the tags
 
 While the tags are rendered above the main headline, sometimes, it might be
 desirable to hide them for a specific page, which can be achieved by using the
-[Metadata][10] extension:
+[Metadata] extension:
 
 ``` bash
 ---
@@ -136,5 +123,3 @@ hide:
 # Document title
 ...
 ```
-
-  [10]: ../../reference/meta-tags/#metadata

docs/setup/setting-up-the-footer.md

@@ -32,7 +32,7 @@ extra:
 
 For each entry, the following settings are available:
 
-`icon`{ #icon }
+`icon`{ #social-icon }
 
 :   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
     This field must point to a valid icon path referencing [any icon bundled
@@ -53,7 +53,7 @@ For each entry, the following settings are available:
   [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/social.html
   [2]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
 
-`link`{ #link }
+`link`{ #social-link }
 
 :   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
     This field must contain a valid relative or absolute URL including the URI 
@@ -77,7 +77,7 @@ For each entry, the following settings are available:
               link: mailto:<email-address>
         ```
 
-`name`{ #name }
+`name`{ #social-name }
 
 :   :octicons-milestone-24: Default: _domain name from_ `link`_, if available_ –
     This field is used as the link's `title` attribute and can be set to a 

docs/setup/setting-up-versioning.md

@@ -6,21 +6,21 @@ template: overrides/main.html
 
 Material for MkDocs makes it easy to deploy multiple versions of your project
 documentation by integrating with external utilities that add those capabilities
-to MkDocs, i.e. [mike][1]. When deploying a new version, older versions of your
+to MkDocs, i.e. [mike]. When deploying a new version, older versions of your
 documentation remain untouched.
 
-  [1]: https://github.com/jimporter/mike
+  [mike]: https://github.com/jimporter/mike
 
 ## Configuration
 
 ### Versioning
 
-[:octicons-file-code-24: Source][2] ·
+[:octicons-tag-24: 7.0.0][version support] ·
-[:octicons-package-24: Utility][1]
+[:octicons-package-24: Utility][mike]
 
-[mike][1] makes it easy to deploy multiple versions of your project
+[mike] makes it easy to deploy multiple versions of your project documentation.
-documentation. It integrates natively with Material for MkDocs and can be
+It integrates natively with Material for MkDocs and can be enabled via
-enabled via `mkdocs.yml`:
+`mkdocs.yml`:
 
 ``` yaml
 extra:
@@ -28,22 +28,21 @@ extra:
     provider: mike
 ```
 
-This will render a version selector in the header next to the title of your
+This renders a version selector in the header:
-project:
 
 <figure markdown>
 
-[![Version selection][3]][3]
+[![Version selector preview]][Version selector preview]
 
   <figcaption markdown>
 
-A demo is worth a thousand words — check it out at
+Check out the versioning example to see it in action –
-[squidfunk.github.io/mkdocs-material-example-versioning][4]
+[squidfunk.github.io/mkdocs-material-example-versioning][version example]
 
   </figcaption>
 </figure>
 
-!!! quote "[Why use mike?][5]"
+!!! quote "[Why use mike?]"
 
     mike is built around the idea that once you've generated your docs for a
     particular version, you should never need to touch that version again. This
@@ -56,15 +55,10 @@ A demo is worth a thousand words — check it out at
     to particularly notable versions. This makes it easy to make permalinks to
     whatever version of the documentation you want to direct people to.
 
-_Note that you don't need to run_ `mike install-extras` _as noted in the
+  [version support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.0
-[official documentation][6], as [mike][1] is now natively integrated with
+  [Version selector preview]: ../assets/screenshots/versioning.png
-Material for MkDocs._
+  [version example]: https://squidfunk.github.io/mkdocs-material-example-versioning/
-
+  [Why use mike?]: https://github.com/jimporter/mike#why-use-mike
-  [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/header.html
-  [3]: ../assets/screenshots/versioning.png
-  [4]: https://squidfunk.github.io/mkdocs-material-example-versioning/
-  [5]: https://github.com/jimporter/mike#why-use-mike
-  [6]: https://github.com/jimporter/mike#usage
 
 ### Version warning