Merge pull request #3093 from squidfunk/docs/restructure-docs

Restructure documentation
2024-11-30 18:24:35 +01:00 · 2021-10-10 22:35:39 +02:00 · 2021-10-10 22:35:39 +02:00 · 77c62c9b55
commit 77c62c9b55
parent 999fc3d39d 47dee18980
62 changed files with 3114 additions and 2717 deletions
--- a/2
+++ b/2
@ -138,7 +138,7 @@ mkdocs-material-7.1.11+insiders-2.11.1 (2021-07-20)
 mkdocs-material-7.1.11+insiders-2.11.0 (2021-07-18)
-  * Improved Mermaid.js intergration, now stable
+  * Improved Mermaid.js integration, now stable
  * Added support for sequence diagrams
  * Added support for entity relationship diagrams
  * Added support for cookie consent configuration
--- 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>
--- 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.
@ -499,7 +499,7 @@ digit `\d`, which leaves version numbers discoverable. Searching for
 [:octicons-search-24: 7.2.6][28] brings up the [7.2.6][29] release notes.
  [28]: ?q=7.2.6
-  [29]: ../../changelog.md#726-_-september-1-2021
+  [29]: ../../changelog/index.md#726-_-september-1-2021
 #### HTML/XML tags
@ -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 |
 | ----------------------- | -------: | -------------: | -----------: |
--- a/docs/changelog/index.md
+++ b/docs/changelog/index.md
--- a/docs/creating-your-site.md
+++ b/docs/creating-your-site.md
@ -4,7 +4,7 @@ template: overrides/main.html
 # Creating your site
-After you've [installed][1] Material for MkDocs, you can bootstrap your project 
+After you've [installed] Material for MkDocs, you can bootstrap your project 
 documentation using the `mkdocs` executable. Go to the directory where you want
 your project to be located and enter:
@ -35,14 +35,14 @@ This will create the following structure:
 └─ mkdocs.yml
 ```
-  [1]: getting-started.md
+  [installed]: getting-started.md
 ## Configuration
 ### Minimal configuration
 Simply add the following lines to `mkdocs.yml` to enable the theme. Note that
-since there are several [installation methods][2], configuration might be
+since there are several [installation methods], minimal configuration might be
 slightly different:
 === "pip, docker"
@ -77,53 +77,53 @@ slightly different:
        logo: logo
    ```
-_If you cloned Material for MkDocs from GitHub, you must list all of the themes'
+    When you clone from GitHub, you must list all of the themes' defaults
-defaults, because_ [`mkdocs_theme.yml`][3] _is not loaded automatically as
+    explicitly, because [`mkdocs_theme.yml`][mkdocs_theme.yml] is not
-[described in the official documentation][4]._
+    loaded automatically as described in the [custom theme guide].
-  [2]: getting-started.md#installation
+  [installation methods]: getting-started.md#installation
-  [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/mkdocs_theme.yml
+  [mkdocs_theme.yml]: https://github.com/squidfunk/mkdocs-material/blob/master/src/mkdocs_theme.yml
-  [4]: https://www.mkdocs.org/user-guide/custom-themes/#creating-a-custom-theme
+  [custom theme guide]: https://www.mkdocs.org/user-guide/custom-themes/#creating-a-custom-theme
 ### Advanced configuration
-Material for MkDocs comes with many configuration options. The _setup_ section
+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 colors]
- [Changing the fonts][6]
+- [Changing the fonts]
- [Changing the language][7]
+- [Changing the language]
- [Changing the logo and icons][8]
+- [Changing the logo and icons]
- [Setting up navigation][9]
+- [Setting up navigation]
- [Setting up site search][10]
+- [Setting up site search]
- [Setting up site analytics][11]
+- [Setting up site analytics]
- [Setting up social cards][12]
+- [Setting up social cards]
- [Setting up tags][13]
+- [Setting up tags]
- [Setting up versioning][14]
+- [Setting up versioning]
- [Setting up the header][15]
+- [Setting up the header]
- [Setting up the footer][16]
+- [Setting up the footer]
- [Adding a git repository][17]
+- [Adding a git repository]
- [Adding a comment system][18]
+- [Adding a comment system]
 </div>
-  [5]: setup/changing-the-colors.md
+  [Changing the colors]: setup/changing-the-colors.md
-  [6]: setup/changing-the-fonts.md
+  [Changing the fonts]: setup/changing-the-fonts.md
-  [7]: setup/changing-the-language.md
+  [Changing the language]: setup/changing-the-language.md
-  [8]: setup/changing-the-logo-and-icons.md
+  [Changing the logo and icons]: setup/changing-the-logo-and-icons.md
-  [9]: setup/setting-up-navigation.md
+  [Setting up navigation]: setup/setting-up-navigation.md
-  [10]: setup/setting-up-site-search.md
+  [Setting up site search]: setup/setting-up-site-search.md
-  [11]: setup/setting-up-site-analytics.md
+  [Setting up site analytics]: setup/setting-up-site-analytics.md
-  [12]: setup/setting-up-social-cards.md
+  [Setting up social cards]: setup/setting-up-social-cards.md
-  [13]: setup/setting-up-tags.md
+  [Setting up tags]: setup/setting-up-tags.md
-  [14]: setup/setting-up-versioning.md
+  [Setting up versioning]: setup/setting-up-versioning.md
-  [15]: setup/setting-up-the-header.md
+  [Setting up the header]: setup/setting-up-the-header.md
-  [16]: setup/setting-up-the-footer.md
+  [Setting up the footer]: setup/setting-up-the-footer.md
-  [17]: setup/adding-a-git-repository.md
+  [Adding a git repository]: setup/adding-a-git-repository.md
-  [18]: setup/adding-a-comment-system.md
+  [Adding a comment system]: setup/adding-a-comment-system.md
 ## Previewing as you write
@ -149,12 +149,12 @@ If you're running Material for MkDocs from within Docker, use:
    docker run --rm -it -p 8000:8000 -v "%cd%":/docs squidfunk/mkdocs-material
    ```
-Point your browser to [localhost:8000][19] and you should see:
+Point your browser to [localhost:8000][live preview] and you should see:
-[![Creating your site][20]][20]
+[![Creating your site]][Creating your site]
-  [19]: http://localhost:8000
+  [live preview]: http://localhost:8000
-  [20]: assets/screenshots/creating-your-site.png
+  [Creating your site]: assets/screenshots/creating-your-site.png
 ## Building your site
@ -167,8 +167,8 @@ mkdocs build
 The contents of this directory make up your project documentation. There's no
 need for operating a database or server, as it is completely self-contained.
-The site can be hosted on [GitHub Pages][21], [GitLab Pages][22], a CDN of your
+The site can be hosted on [GitHub Pages], [GitLab Pages], a CDN of your choice
-choice or your private web space.
+or your private web space.
-  [21]: publishing-your-site.md#github-pages
+  [GitHub Pages]: publishing-your-site.md#github-pages
-  [22]: publishing-your-site.md#gitlab-pages
+  [GitLab pages]: publishing-your-site.md#gitlab-pages
--- a/docs/customization.md
+++ b/docs/customization.md
@ -11,11 +11,11 @@ necessary to preserve your brand's style.
 ## Adding assets
-[MkDocs][1] provides several ways to customize a theme. In order to make a few
+[MkDocs] provides several ways to customize a theme. In order to make a few
-tweaks to Material for MkDocs, you can just add your stylesheets and JavaScript
+small tweaks to Material for MkDocs, you can just CSS and JavaScript files to
-files to the `docs` directory.
+the `docs` directory.
-  [1]: https://www.mkdocs.org
+  [MkDocs]: https://www.mkdocs.org
 ### Additional CSS
@ -31,23 +31,17 @@ new stylesheet file in the `docs` directory:
 └─ mkdocs.yml
 ```
-Then, add the following line to `mkdocs.yml`:
+Then, add the following lines to `mkdocs.yml`:
 ``` yaml
 extra_css:
  - stylesheets/extra.css
 ```
 Spin up the [live preview server][2] and start typing your changes in your
 additional stylesheet file – you should see them almost instantly after saving.
  [2]: creating-your-site.md#previewing-as-you-write
 ### Additional JavaScript
-The same is true for additional JavaScript. If you want to integrate another
+If you want to integrate another syntax highlighter or add some custom logic to
-syntax highlighter or add some custom logic to your theme, create a new
+your theme, create a new JavaScript file in the `docs` directory:
 JavaScript file in the `docs` directory:
 ``` sh
 .
@ -57,30 +51,27 @@ JavaScript file in the `docs` directory:
 └─ mkdocs.yml
 ```
-Then, add the following line to `mkdocs.yml`:
+Then, add the following lines to `mkdocs.yml`:
 ``` yaml
 extra_javascript:
  - javascripts/extra.js
 ```
 Further assistance can be found in the [MkDocs documentation][3].
  [3]: https://www.mkdocs.org/user-guide/styling-your-docs/#customizing-a-theme
 ## Extending the theme
 If you want to alter the HTML source (e.g. add or remove some parts), you can
-extend the theme. MkDocs supports [theme extension][4], an easy way to override
+extend the theme. MkDocs supports [theme extension], an easy way to override
 parts of Material for MkDocs without forking from git. This ensures that you
 can update to the latest version more easily.
-  [4]: https://www.mkdocs.org/user-guide/styling-your-docs/#using-the-theme-custom_dir
+  [theme extension]: https://www.mkdocs.org/user-guide/styling-your-docs/#using-the-theme-custom_dir
 ### Setup and theme structure
 Enable Material for MkDocs as usual in `mkdocs.yml`, and create a new folder
-for `overrides` which you then reference using the `custom_dir` key:
+for `overrides` which you then reference using the [`custom_dir`][custom_dir]
 setting:
 ``` yaml
 theme:
@ -90,16 +81,15 @@ theme:
 !!! warning "Theme extension prerequisites"
-    As the `custom_dir` variable is used for the theme extension process,
+    As the [`custom_dir`][custom_dir] setting is used for the theme extension
-    Material for MkDocs needs to be installed via `pip` and referenced with the
+    process, Material for MkDocs needs to be installed via `pip` and referenced
-    `name` parameter in `mkdocs.yml`. It will not work when cloning from `git`.
+    with the [`name`][name] setting in `mkdocs.yml`. It will not work when
    cloning from `git`.
 The structure in the `overrides` directory must mirror the directory structure
 of the original theme, as any file in the `overrides` directory will replace the
 file with the same name which is part of the original theme. Besides, further
-assets may also be put in the `overrides` directory.
+assets may also be put in the `overrides` directory:
 The directory layout of the theme is as follows:
 ``` sh
 .
@ -123,8 +113,7 @@ The directory layout of the theme is as follows:
 │  ├─ search.html                      # Search box
 │  ├─ social.html                      # Social links
 │  ├─ source.html                      # Repository information
-│  ├─ source-date.html                 # Last updated date
+│  ├─ source-file.html                 # Source file information
 │  ├─ source-link.html                 # Link to source file
 │  ├─ tabs.html                        # Tabs navigation
 │  ├─ tabs-item.html                   # Tabs navigation item
 │  ├─ toc.html                         # Table of contents
@ -134,11 +123,14 @@ The directory layout of the theme is as follows:
 └─ main.html                           # Default page
 ```
  [custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
  [name]: https://www.mkdocs.org/user-guide/configuration/#name
 ### Overriding partials
 In order to override a partial, we can replace it with a file of the same name
 and location in the `overrides` directory. For example, to replace the original
-`footer.html`, create a `footer.html` file in the `overrides/partials`
+`footer.html` partial, create a new `footer.html` partial in the `overrides`
 directory:
 ``` sh
@ -152,12 +144,12 @@ directory:
 MkDocs will now use the new partial when rendering the theme. This can be done
 with any file.
-### Overriding blocks <small>recommended</small> { data-toc-label="Overriding blocks" }
+### Overriding blocks <small>recommended</small> { #overriding-blocks data-toc-label="Overriding blocks" }
 Besides overriding partials, it's also possible to override (and extend)
-_template blocks_, which are defined inside the templates and wrap specific
+template blocks, which are defined inside the templates and wrap specific
-features. To override a block, create a `main.html` file inside the `overrides`
+features. In order to set up block overrides, create a `main.html` file inside
-directory:
+the `overrides` directory:
 ``` sh
 .
@ -166,7 +158,7 @@ directory:
 └─ mkdocs.yml
 ```
-Then, e.g. to override the site title, add the following line to `main.html`:
+Then, e.g. to override the site title, add the following lines to `main.html`:
 ``` html
 {% extends "base.html" %}
@ -176,7 +168,7 @@ Then, e.g. to override the site title, add the following line to `main.html`:
 {% endblock %}
 ```
-Material for MkDocs provides the following template blocks:
+The following template blocks are provided by the theme:
 | Block name        | Purpose                                         |
 |:------------------|:------------------------------------------------|
@ -194,16 +186,11 @@ Material for MkDocs provides the following template blocks:
 | `libs`            | Wraps the JavaScript libraries (header)         |
 | `outdated`        | Wraps the version warning                       |
 | `scripts`         | Wraps the JavaScript application (footer)       |
 | `source`          | Wraps the linked source files                   |
 | `site_meta`       | Wraps the meta tags in the document head        |
 | `site_nav`        | Wraps the site navigation and table of contents |
-| `styles`          | Wraps the stylesheets (also extra sources)      |
+| `styles`          | Wraps the style sheets (also extra sources)     |
 | `tabs`            | Wraps the tabs navigation (if available)        |
 For more on this topic refer to the [MkDocs documentation][5].
 [5]: https://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks
 #### Additional variables
 Besides template blocks, Material for MkDocs provides extra variables for parts
@ -216,11 +203,11 @@ with Material for MkDocs_ hint in the footer, add the following line to
 {% extends "base.html" %}
 {% set extracopyright %}
-  <!-- Add your additional information here -->
+  <!-- Add additional copyright information here -->
 {% endset %}
 ```
-Material for MkDocs provides the following additional variables:
+The following template variables are provided by the theme:
 | Block name        | Purpose                                         |
 |:------------------|:------------------------------------------------|
@ -228,25 +215,25 @@ Material for MkDocs provides the following additional variables:
 ## Theme development
-Material for MkDocs is built on top of [TypeScript][6], [RxJS][7] and [SASS][8],
+Material for MkDocs is built on top of [TypeScript], [RxJS] and [SASS], and
-and uses a lean, custom build process to put everything together.[^1] If you
+uses a lean, custom build process to put everything together.[^1] If you want
-want to make more fundamental changes, it may be necessary to make the
+to make more fundamental changes, it may be necessary to make the adjustments
-adjustments directly in the source of the theme and recompile it.
+directly in the source of the theme and recompile it.
  [^1]:
-    Prior to version 7.0, the build was based on Webpack. This led to broken
+    Prior to :octicons-tag-24: 7.0.0 the build was based on Webpack, resulting
-    builds due to frequent incompatibilities with loaders and plugins, so we
+    in occasional broken builds due to incompatibilities with loaders and
-    decided to swap Webpack for a leaner custom solution which is now based on
+    plugins. Therefore, we decided to swap Webpack for a leaner solution which
-    [RxJS][7] as the application itself. This enabled us to remove more than
+    is now based on [RxJS] as the application itself. This allowed for the
-    500 dependencies (~30% less).
+    pruning of more than 500 dependencies (~30% less).
-  [6]: https://www.typescriptlang.org/
+  [TypeScript]: https://www.typescriptlang.org/
-  [7]: https://github.com/ReactiveX/rxjs
+  [RxJS]: https://github.com/ReactiveX/rxjs
-  [8]: https://sass-lang.com
+  [SASS]: https://sass-lang.com
 ### Environment setup
-In order to start development on Material for MkDocs, a [Node.js][9] version of
+In order to start development on Material for MkDocs, a [Node.js] version of
 at least 14 is required. First, clone the repository:
 ```
@ -263,7 +250,7 @@ pip install mkdocs-redirects
 npm install
 ```
-  [9]: https://nodejs.org
+  [Node.js]: https://nodejs.org
 ### Development mode
@ -273,14 +260,14 @@ Start the watcher with:
 npm start
 ```
-Then, in a second session, start the MkDocs live preview server with:
+Then, in a second terminal window, start the MkDocs live preview server with:
 ```
 mkdocs serve
 ```
-Point your browser to [localhost:8000][10] and you should see this documentation
+Point your browser to [localhost:8000][live preview] and you should see this
-in front of you.
+very documentation in front of you.
 !!! warning "Automatically generated files"
@ -288,7 +275,7 @@ in front of you.
    directory are automatically generated from the `src` directory and will be
    overwritten when the theme is built.
-  [10]: http://localhost:8000
+  [live preview]: http://localhost:8000
 ### Building the theme
@ -298,10 +285,7 @@ When you're finished making your changes, you can build the theme by invoking:
 npm run build
 ```
-This triggers the production-level compilation and minification of all
+This triggers the production-level compilation and minification of all style
-stylesheets and JavaScript sources. When the command exits, the final files are
+sheets and JavaScript files. After the command exits, the compiled files are
-located in the `material` directory. Add the `theme_dir` variable pointing to
+located in the `material` directory. When running `mkdocs build`, you should
-the aforementioned directory in the original `mkdocs.yml`.
+now see your changes to the original theme.
 Now you can run `mkdocs build` and you should see your documentation with your
 changes to the original theme.
--- a/docs/data-privacy.md
+++ b/docs/data-privacy.md
@ -1,31 +0,0 @@
 ---
 template: overrides/main.html
 ---
 # Data privacy
 In itself, Material for MkDocs does not perform any tracking and adheres to the
 [General Data Protection Regulation][1] (GDPR), but it integrates with some
 third-party services that may not.
  [1]: https://en.wikipedia.org/wiki/General_Data_Protection_Regulation
 ## Third-party services
 ### Google Fonts
 Material for MkDocs makes fonts [configurable][2] by relying on Google Fonts
 CDN, which may be in breach with GDPR. The usage of Google's CDN can be [easily
 disabled][3] via `mkdocs.yml`.
  [2]: setup/changing-the-fonts.md
  [3]: setup/changing-the-fonts.md#disabling-font-loading
 ### Google Analytics and Disqus
 Material for MkDocs comes with optional [Google Analytics][4] and [Disqus][5]
 integrations, both of which must be enabled explicitly, so there's no immediate
 action if you don't use those.
  [4]: setup/setting-up-site-analytics.md#google-analytics
  [5]: setup/adding-a-comment-system.md#disqus
--- a/docs/deprecations.md
+++ b/docs/deprecations.md
@ -124,7 +124,7 @@ templates can be shared among multiple pages:
    {% endblock %}
    ```
-  [5]: customization.md#overriding-blocks-recommended
+  [5]: customization.md#overriding-blocks
  [6]: customization.md#extending-the-theme
 ## Docker image
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@ -5,21 +5,18 @@ title: Getting started
 # Getting started
-Material for MkDocs is a theme for [MkDocs][1], a static site generator geared
+Material for MkDocs is a theme for [MkDocs], a static site generator geared
 towards (technical) project documentation. If you're familiar with Python, you
-can install Material for MkDocs with [`pip`][2], the Python package manager.
+can install Material for MkDocs with [`pip`][pip], the Python package manager.
-If not, we recommended using [`docker`][3].
+If not, we recommended using [`docker`][docker].
-In case you're running into problems, consult the [troubleshooting][4] section.
+  [MkDocs]: https://www.mkdocs.org
-
+  [pip]: #with-pip
-  [1]: https://www.mkdocs.org
+  [docker]: #with-docker
  [2]: #with-pip-recommended
  [3]: #with-docker
  [4]: troubleshooting.md
 ## Installation
-### with pip <small>recommended</small> { data-toc-label="with pip" }
+### with pip <small>recommended</small> { #with-pip data-toc-label="with pip" }
 Material for MkDocs can be installed with `pip`:
@ -28,17 +25,17 @@ pip install mkdocs-material
 ```
 This will automatically install compatible versions of all dependencies:
-[MkDocs][1], [Markdown][5], [Pygments][6] and [Python Markdown Extensions][7].
+[MkDocs], [Markdown], [Pygments] and [Python Markdown Extensions]. Material for
-Material for MkDocs always strives to support the latest versions, so there's
+MkDocs always strives to support the latest versions, so there's no need to
-no need to install those packages separately.
+install those packages separately.
-  [5]: https://python-markdown.github.io/
+  [Markdown]: https://python-markdown.github.io/
-  [6]: https://pygments.org/
+  [Pygments]: https://pygments.org/
-  [7]: https://facelessuser.github.io/pymdown-extensions/
+  [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
 ### with docker
-The official [Docker image][8] is a great way to get up and running in a few
+The official [Docker image] is a great way to get up and running in a few
 minutes, as it comes with all dependencies pre-installed. Pull the image for the 
 `latest` version with:
@ -52,12 +49,12 @@ covered in the following sections.
 The following plugins are bundled with the Docker image:
- [mkdocs-minify-plugin][9]
+- [mkdocs-minify-plugin]
- [mkdocs-redirects][10]
+- [mkdocs-redirects]
-  [8]: https://hub.docker.com/r/squidfunk/mkdocs-material/
+  [Docker image]: https://hub.docker.com/r/squidfunk/mkdocs-material/
-  [9]: https://github.com/byrnereese/mkdocs-minify-plugin
+  [mkdocs-minify-plugin]: https://github.com/byrnereese/mkdocs-minify-plugin
-  [10]: https://github.com/datarobot/mkdocs-redirects
+  [mkdocs-redirects]: https://github.com/datarobot/mkdocs-redirects
 ??? question "How to add plugins to the Docker image?"
@ -82,19 +79,19 @@ The following plugins are bundled with the Docker image:
 !!! info ":material-apple: Apple Silicon (M1) and :fontawesome-brands-raspberry-pi: Raspberry Pi"
    The official Docker image is only available for `linux/amd64`. We recommend
-    the [third-party image][11] by @afritzler if you want to run Material for
+    the [third-party image] by @afritzler if you want to run Material for MkDocs
-    MkDocs via Docker on `arm64` or `armv7`, as it is automatically built on
+    via Docker on `arm64` or `armv7`, as it is automatically built on every
-    every release:
+    release:
    ```
    docker pull ghcr.io/afritzler/mkdocs-material
    ```
-  [11]: https://github.com/afritzler/mkdocs-material
+  [third-party image]: https://github.com/afritzler/mkdocs-material
 ### with git
-Material for MkDocs can be directly used from [GitHub][12] by cloning the
+Material for MkDocs can be directly used from [GitHub] by cloning the
 repository into a subfolder of your project root which might be useful if you
 want to use the very latest version:
@ -106,7 +103,7 @@ The theme will reside in the folder `mkdocs-material/material`. When cloning
 from `git`, you must install all required dependencies yourself:
 ```
-pip install -r mkdocs-material/requirements.txt
+pip install -e mkdocs-material
 ```
-  [12]: https://github.com/squidfunk/mkdocs-material
+  [GitHub]: https://github.com/squidfunk/mkdocs-material
--- a/docs/insiders/getting-started.md
+++ b/docs/insiders/getting-started.md
@ -7,13 +7,13 @@ title: Switching to Insiders
 Material for MkDocs Insiders is a fully compatible drop-in replacement for 
 Material for MkDocs, and can be installed similar to the public version using
-[`pip`][1], [`docker`][2] or [`git`][3]. When you sponsor @squidfunk, your
+[`pip`][pip], [`docker`][docker] or [`git`][git]. When you sponsor @squidfunk,
-account is added to the list of collaborators of the private Insiders
+your account is added to the list of collaborators of the private Insiders
 repository.
-  [1]: #with-pip-recommended
+  [pip]: #with-pip
-  [2]: #with-docker
+  [docker]: #with-docker
-  [3]: #with-git
+  [git]: #with-git
 ## Requirements
@ -21,10 +21,10 @@ In order to access the Insiders repository programmatically (from the command
 line or GitHub Actions workflows), you need to create a [personal access 
 token][4]:
-1. Go to https://github.com/settings/tokens
+1.  Go to https://github.com/settings/tokens
-2. Click on [Generate a new token][5]
+2.  Click on [Generate a new token][5]
-3. Enter a name and select the [`repo`][6] scope
+3.  Enter a name and select the [`repo`][6] scope
-4. Generate the token and store it in a safe place
+4.  Generate the token and store it in a safe place
  [4]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
  [5]: https://github.com/settings/tokens/new
@ -52,18 +52,18 @@ additional steps are necessary. While we cannot provide a hosted Docker image
 for Insiders[^1], [GitHub Container Registry][7] allows for simple and
 comfortable self-hosting:
-1. [Fork the Insiders repository][8]
+1.  [Fork the Insiders repository][8]
-2. Enable [GitHub Actions][9] on your fork[^2]
+2.  Enable [GitHub Actions][9] on your fork[^2]
-3. Create a new personal access token[^3]
+3.  Create a new personal access token[^3]
-    1. Go to https://github.com/settings/tokens
+    1.  Go to https://github.com/settings/tokens
-    2. Click on [Generate a new token][5]
+    2.  Click on [Generate a new token][5]
-    3. Enter a name and select the [`write:packages`][10] scope
+    3.  Enter a name and select the [`write:packages`][10] scope
-    4. Generate the token and store it in a safe place
+    4.  Generate the token and store it in a safe place
-4. Add a [GitHub Actions secret][11] on your fork
+4.  Add a [GitHub Actions secret][11] on your fork
-    1. Set the name to `GHCR_TOKEN`
+    1.  Set the name to `GHCR_TOKEN`
-    2. Set the value to the personal access token created in the previous step
+    2.  Set the value to the personal access token created in the previous step
-5. [Create a new release][12] to build and publish the Docker image
+5.  [Create a new release][12] to build and publish the Docker image
-6. Install [Pull App][13] on your fork to stay in-sync with upstream
+6.  Install [Pull App][13] on your fork to stay in-sync with upstream
 The [`publish`][14] workflow[^4] is automatically run when a new tag (release)
 is created. When a new Insiders version is released on the upstream repository,
--- 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]
@ -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
@ -197,8 +197,8 @@ the public for general availability.
 - [x] [Linking content tabs][32]
  [30]: ../setup/setting-up-site-search.md#search-boosting
-  [31]: ../reference/admonitions.md#changing-the-icons
+  [31]: ../reference/admonitions.md#admonition-icons
-  [32]: ../reference/content-tabs.md#linking-content-tabs
+  [32]: ../reference/content-tabs.md#linked-content-tabs
 #### $ 7,000 – Royal Gold
@ -240,7 +240,7 @@ the public for general availability.
  [21]: ../setup/setting-up-navigation.md#sticky-navigation-tabs
  [22]: ../setup/setting-up-navigation.md#section-index-pages
-  [23]: ../setup/setting-up-the-footer.md#remove-generator
+  [23]: ../setup/setting-up-the-footer.md#generator-notice
 #### $ 2,500 – Biquinho Vermelho
--- a/docs/publishing-your-site.md
+++ b/docs/publishing-your-site.md
@ -10,15 +10,15 @@ makes this ridiculously simple.
 ## GitHub Pages
-If you're already hosting your code on GitHub, [GitHub Pages][1] is certainly
+If you're already hosting your code on GitHub, [GitHub Pages] is certainly
 the most convenient way to publish your project documentation. It's free of
 charge and pretty easy to set up.
-  [1]: https://pages.github.com/
+  [GitHub Pages]: https://pages.github.com/
 ### with GitHub Actions
-Using [GitHub Actions][2] you can automate the deployment of your project
+Using [GitHub Actions] you can automate the deployment of your project
 documentation. At the root of your repository, create a new GitHub Actions
 workflow, e.g. `.github/workflows/ci.yml`, and copy and paste the following
 contents:
@ -49,7 +49,7 @@ contents:
    2. At some point, GitHub renamed `master` to `main`. If your default branch
       is named `master`, you can safely remove `main`, vice versa.
-    3. This is the place to install further [MkDocs plugins][3] or Markdown
+    3. This is the place to install further [MkDocs plugins] or Markdown
       extensions with `pip` to be used during the build:
        ``` sh
@ -80,24 +80,24 @@ contents:
          - run: pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
          - run: mkdocs gh-deploy --force
    env:
-      GH_TOKEN: ${{ secrets.GH_TOKEN }}
+      GH_TOKEN: ${{ secrets.GH_TOKEN }} # (1)
    ```
    1.  Remember to set the `GH_TOKEN` environment variable to the value of your
        [personal access token] when deploying [Insiders], which can be done
        using [GitHub secrets].
 Now, when a new commit is pushed to either the `master` or `main` branches,
 the static site is automatically built and deployed. Push your changes to see
 the workflow in action.
 Your documentation should shortly appear at `<username>.github.io/<repository>`.
-_Remember to set the_ `GH_TOKEN` _environment variable to the value of your
+  [GitHub Actions]: https://github.com/features/actions
-[personal access token][4] when deploying [Insiders][5], which can be done
+  [MkDocs plugins]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins
-using [secrets][6]._
+  [personal access token]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
-
+  [Insiders]: insiders/index.md
-  [2]: https://github.com/features/actions
+  [GitHub secrets]: https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets
  [3]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins
  [4]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
  [5]: insiders/index.md
  [6]: https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets
 ### with MkDocs
@ -110,10 +110,10 @@ mkdocs gh-deploy --force
 ## GitLab Pages
-If you're hosting your code on GitLab, deploying to [GitLab Pages][7] can be
+If you're hosting your code on GitLab, deploying to [GitLab Pages] can be done
-done by using the [GitLab CI][8] task runner. At the root of your repository,
+by using the [GitLab CI] task runner. At the root of your repository, create a
-create a task definition named `.gitlab-ci.yml` and copy and paste the
+task definition named `.gitlab-ci.yml` and copy and paste the following
-following contents:
+contents:
 === "Material for MkDocs"
@ -139,7 +139,7 @@ following contents:
      stage: deploy
      only:
        - master
-      script:
+      script: # (1)
        - pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
        - mkdocs build --site-dir public
      artifacts:
@ -147,16 +147,16 @@ following contents:
          - public
    ```
    1.  Remember to set the `GH_TOKEN` environment variable to the value of your
        [personal access token] when deploying [Insiders], which can be done
        using [masked custom variables].
 Now, when a new commit is pushed to `master`, the static site is automatically
 built and deployed. Commit and push the file to your repository to see the
 workflow in action.
 Your documentation should shortly appear at `<username>.gitlab.io/<repository>`.
-_Remember to set the_ `GH_TOKEN` _environment variable to the value of your
+  [GitLab Pages]: https://gitlab.com/pages
-[personal access token][4] when deploying [Insiders][5], which can be done
+  [GitLab CI]: https://docs.gitlab.com/ee/ci/
-using [masked custom variables][9]._
+  [masked custom variables]: https://docs.gitlab.com/ee/ci/variables/#create-a-custom-variable-in-the-ui
  [7]: https://gitlab.com/pages
  [8]: https://docs.gitlab.com/ee/ci/
  [9]: https://docs.gitlab.com/ee/ci/variables/#create-a-custom-variable-in-the-ui
--- a/docs/reference/abbreviations.md
+++ b/docs/reference/abbreviations.md
@ -4,50 +4,38 @@ template: overrides/main.html
 # Abbreviations
-Technical documentation often incurs the usage of a lot of acronyms, which may
+Technical documentation often incurs the usage of many acronyms, which may
 need additional explanation, especially for new user of your project. For these
 matters, Material for MkDocs uses a combination of Markdown extensions to
 enable site-wide glossaries.
 ## Configuration
-### Abbreviations
+This configuration enables abbreviations and allows to build a simple
-
+project-wide glossary, sourcing definitions from a central location. Add the
-[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
+following line to `mkdocs.yml`:
 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:
 ``` 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/
+See additional configuration options:
-  [4]: https://facelessuser.github.io/pymdown-extensions/
+
 - [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
+Abbreviations can be defined by using a special syntax similar to URLs and 
-with a special syntax similar to URLs and [footnotes][6] at any point in the
+[footnotes], starting with a `*` and immediately followed by the term or
-Markdown document.
+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
+  [footnotes]: footnotes.md
  [6]: footnotes.md
 ### Adding a glossary
-When [Snippets][7] is enabled, content from other files can be embedded, which
+The [Snippets] extension can be used to implement a simple glossary by moving
-is especially useful to include abbreviations from a central file – a glossary –
+all abbreviations in a dedicated file[^1], and embedding it with the
-and embed them into any other file.
+[`--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/example.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_
+  [Snippets notation]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippets-notation
 `docs` _folder (here_ `includes` _is used), or MkDocs may complain about an 
 unreferenced file._
  [7]: #snippets
--- a/docs/reference/admonitions.md
+++ b/docs/reference/admonitions.md
@ -11,61 +11,119 @@ inclusion and nesting of arbitrary content.
 ## Configuration
-### Admonition
+This configuration enables admonitions, allows to make them collapsible and to
-
+nest arbitrary content inside admonitions. Add the following lines to
 [:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
 The [Admonition][2] extension, which is part of the standard Markdown
 library, is integrated with Material for MkDocs and can be enabled via
 `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - admonition
 ```
  [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_admonition.scss
  [2]: https://python-markdown.github.io/extensions/admonition/
 ### Details
 [:octicons-file-code-24: Source][3] · [:octicons-workflow-24: Extension][4]
 The [Details][4] extension, which is part of [Python Markdown Extensions][5],
 adds the ability to __make admonitions collapsible__. It can be enabled via
 `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - pymdownx.details
 ```
  [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_details.scss
  [4]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
  [5]: https://facelessuser.github.io/pymdown-extensions/
 ### SuperFences
 The [SuperFences][6] extension, which is also part of [Python Markdown
 Extensions][5], allows for the __nesting of code and content blocks inside
 admonitions__, and is therefore strongly recommended:
 ``` yaml
 markdown_extensions:
  - pymdownx.superfences
 ```
-  [6]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
+
 See additional configuration options:
 - [Admonition]
 - [Details]
 - [SuperFences]
  [Admonition]: ../setup/extensions/python-markdown.md#admonition
  [Details]: ../setup/extensions/python-markdown-extensions.md#details
  [SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
 ### Admonition icons
 [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
 [:octicons-tag-24: insiders-2.4.0][Insiders]
 Each of the supported admonition types has a distinct icon, which can be changed
 to any icon bundled with the theme, or even a [custom icon]. Add the following
 lines to `mkdocs.yml`:
 ``` yaml
 theme:
  icon:
    admonition:
      <type>: <icon> # (1)
 ```
 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].
 ??? example "Example: using alternative icon sets"
    === ":octicons-mark-github-16: 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"
        _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
        ```
        _Result_:
        [![FontAwesome]][FontAwesome]
  [Insiders]: ../insiders/index.md
  [custom icon]: icons-emojis.md#additional-icons
  [supported types]: #supported-types
  [icon search]: icons-emojis.md#search
  [Octicons]: ../assets/screenshots/admonition-octicons.png
  [FontAwesome]: ../assets/screenshots/admonition-fontawesome.png
 ## Usage
-Admonitions follow a simple syntax: a block must start with `!!!`, followed
+Admonitions follow a simple syntax: a block starts with `!!!`, followed by a
-by a single keyword which is used as the [type qualifier][7] of the block. The
+single keyword used as a [type qualifier]. The content of the block follows on
-content of the block then follows on the next line, indented by four spaces.
+the next line, indented by four spaces.
 _Example_:
 ``` markdown
 !!! note
    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.
@ -79,7 +137,7 @@ _Result_:
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.
-  [7]: #supported-types
+  [type qualifier]: #supported-types
 ### Changing the title
@ -91,6 +149,7 @@ _Example_:
 ``` markdown
 !!! note "Phasellus posuere in sem ut cursus"
    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.
@ -106,14 +165,15 @@ _Result_:
 ### Removing the title
-Similar to [changing the title][8], the icon and title can be omitted entirely
+Similar to [changing the title], the icon and title can be omitted entirely by
-by adding an empty string directly after the type qualifier. Note that this 
+adding an empty string directly after the type qualifier. Note that this will
-will not work for [collapsible blocks][9].
+not work for [collapsible blocks].
 _Example_:
 ``` markdown
 !!! note ""
    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.
@ -127,70 +187,20 @@ _Result_:
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.
-  [8]: #changing-the-title
+  [changing the title]: #changing-the-title
-  [9]: #collapsible-blocks
+  [collapsible blocks]: #collapsible-blocks
 ### Embedded content
 Admonitions can contain all kinds of text content, including headlines, lists,
 paragraphs and other blocks. While the parser from the standard Markdown library
 doesn't account for nested blocks, the [SuperFences][10] extension adds the
 ability to nest arbitrary content inside admonitions.
 _Example_:
 ``` markdown
 !!! note
    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.
    ``` python
    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]
    ```
    Nunc eu odio eleifend, blandit leo a, volutpat sapien. Phasellus posuere in
    sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis.
    Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim.
 ```
 _Result_:
 !!! note
    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.
    ``` python
    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]
    ```
    Nunc eu odio eleifend, blandit leo a, volutpat sapien. Phasellus posuere in
    sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis.
    Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim.
  [10]: #superfences
 ### Collapsible blocks
-The [Details][11] extension adds support for rendering collapsible admonition
+When [Details] is enabled and an admonition block is started with `???` instead
-blocks. This is useful for FAQs or content that is of secondary nature. A
+of `!!!`, the admonition is rendered as a collapsible block with a small toggle
-details block follows the syntax and semantics of admonition blocks, but must
+on the right side.
 start with `???`.
 _Example_:
 ``` markdown
 ??? note
    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.
@ -204,12 +214,13 @@ _Result_:
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.
-Adding a `+` after `???` will render the block as open on page load:
+Adding a `+` after the `???` token will render the block as open.
 _Example_:
 ``` markdown
 ???+ note
    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.
@ -223,23 +234,16 @@ _Result_:
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.
  [11]: #details
 ### Inline blocks
-[:octicons-file-code-24: Source][12] ·
+[:octicons-tag-24: 7.0.0][Inline support] ·
 :octicons-beaker-24: Experimental
-Admonitions and [Details][11] can also be rendered as inline blocks (i.e.
+Admonitions can also be rendered as inline blocks (i.e. for sidebars), placing
-sidebars), placing them to the right using the `inline` + `end` modifiers, or
+them to the right using the `inline` + `end` modifiers, or to the left using
-to the left using only the `inline` modifier.
+only the `inline` modifier.
-__Important__: Admonitions that use the `inline` modifiers _must_ be declared
+=== ":octicons-arrow-right-16: inline end"
 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 end"
    _Example_ / _Result_:
@ -251,6 +255,7 @@ will stretch to the full width of the viewport, e.g. on mobile viewports.
    ``` markdown
    !!! info inline end
        Lorem ipsum dolor sit amet, consectetur
        adipiscing elit. Nulla et euismod nulla.
        Curabitur feugiat, tortor non consequat
@ -260,7 +265,7 @@ will stretch to the full width of the viewport, e.g. on mobile viewports.
    Use `inline end` to align to the right (left for rtl languages).
-=== "inline"
+=== ":octicons-arrow-left-16: inline"
    _Example_ / _Result_:
@ -272,6 +277,7 @@ will stretch to the full width of the viewport, e.g. on mobile viewports.
    ``` markdown
    !!! info inline
        Lorem ipsum dolor sit amet, consectetur
        adipiscing elit. Nulla et euismod nulla.
        Curabitur feugiat, tortor non consequat
@ -281,14 +287,19 @@ will stretch to the full width of the viewport, e.g. on mobile viewports.
    Use `inline` to align to the left (right for rtl languages).
-  [12]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_modifiers.scss
+__Important__: Admonitions that use the `inline` modifiers _must_ be declared
 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
 the default type, and thus fallback for unknown type qualifiers, is `note`:
-`note`{ #note }, ~~`seealso`~~ [^1]
+`note`{ #type-note }, ~~`seealso`~~ [^1]
 :   !!! note
@ -296,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
@ -304,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
@ -312,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
@ -320,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
@ -328,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
@ -336,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
@ -344,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
@ -352,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
@ -360,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
@ -368,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
@ -376,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
@ -389,106 +400,15 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
    in order to make it easier for authors to migrate to Material for MkDocs.
    However, when the title is omitted, the admonition extension will render it
    as `Seealso`, which is incorrect English. For this reason, it was deprecated
-    as of 7.1.5 and will be removed in 8.x.
+    in :octicons-tag-24: 7.1.5 and will be removed in :octicons-tag-24: 8.0.0.
 ### Changing the icons
 [:octicons-file-code-24: Source][13] ·
 [:octicons-heart-fill-24:{ .mdx-heart } Insiders only][13]{ .mdx-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`:
 === "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_:
    [![Admonition with Octicons icons][14]][14]
 === "FontAwesome"
    _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
    ```
    _Result_:
    [![Admonition with FontAwesome icons][15]][15]
  [13]: ../insiders/index.md
  [14]: ../assets/screenshots/admonition-octicons.png
  [15]: ../assets/screenshots/admonition-fontawesome.png
 ## Customization
 ### Custom admonitions
 If you want to add a custom admonition type, all you need is a color and an
-`svg` icon. Copy the icon's `svg` code from the [`.icons`][16] folder and add the
+`*.svg` icon. Copy the icon's code from the [`.icons`][custom icons] folder
-following CSS to an [additional stylesheet][17]:
+and add the following CSS to an [additional style sheet]:
 ``` css
 :root {
  --md-admonition-icon--pied-piper: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M244 246c-3.2-2-6.3-2.9-10.1-2.9-6.6 0-12.6 3.2-19.3 3.7l1.7 4.9zm135.9 197.9c-19 0-64.1 9.5-79.9 19.8l6.9 45.1c35.7 6.1 70.1 3.6 106-9.8-4.8-10-23.5-55.1-33-55.1zM340.8 177c6.6 2.8 11.5 9.2 22.7 22.1 2-1.4 7.5-5.2 7.5-8.6 0-4.9-11.8-13.2-13.2-23 11.2-5.7 25.2-6 37.6-8.9 68.1-16.4 116.3-52.9 146.8-116.7C548.3 29.3 554 16.1 554.6 2l-2 2.6c-28.4 50-33 63.2-81.3 100-31.9 24.4-69.2 40.2-106.6 54.6l-6.3-.3v-21.8c-19.6 1.6-19.7-14.6-31.6-23-18.7 20.6-31.6 40.8-58.9 51.1-12.7 4.8-19.6 10-25.9 21.8 34.9-16.4 91.2-13.5 98.8-10zM555.5 0l-.6 1.1-.3.9.6-.6zm-59.2 382.1c-33.9-56.9-75.3-118.4-150-115.5l-.3-6c-1.1-13.5 32.8 3.2 35.1-31l-14.4 7.2c-19.8-45.7-8.6-54.3-65.5-54.3-14.7 0-26.7 1.7-41.4 4.6 2.9 18.6 2.2 36.7-10.9 50.3l19.5 5.5c-1.7 3.2-2.9 6.3-2.9 9.8 0 21 42.8 2.9 42.8 33.6 0 18.4-36.8 60.1-54.9 60.1-8 0-53.7-50-53.4-60.1l.3-4.6 52.3-11.5c13-2.6 12.3-22.7-2.9-22.7-3.7 0-43.1 9.2-49.4 10.6-2-5.2-7.5-14.1-13.8-14.1-3.2 0-6.3 3.2-9.5 4-9.2 2.6-31 2.9-21.5 20.1L15.9 298.5c-5.5 1.1-8.9 6.3-8.9 11.8 0 6 5.5 10.9 11.5 10.9 8 0 131.3-28.4 147.4-32.2 2.6 3.2 4.6 6.3 7.8 8.6 20.1 14.4 59.8 85.9 76.4 85.9 24.1 0 58-22.4 71.3-41.9 3.2-4.3 6.9-7.5 12.4-6.9.6 13.8-31.6 34.2-33 43.7-1.4 10.2-1 35.2-.3 41.1 26.7 8.1 52-3.6 77.9-2.9 4.3-21 10.6-41.9 9.8-63.5l-.3-9.5c-1.4-34.2-10.9-38.5-34.8-58.6-1.1-1.1-2.6-2.6-3.7-4 2.2-1.4 1.1-1 4.6-1.7 88.5 0 56.3 183.6 111.5 229.9 33.1-15 72.5-27.9 103.5-47.2-29-25.6-52.6-45.7-72.7-79.9zm-196.2 46.1v27.2l11.8-3.4-2.9-23.8zm-68.7-150.4l24.1 61.2 21-13.8-31.3-50.9zm84.4 154.9l2 12.4c9-1.5 58.4-6.6 58.4-14.1 0-1.4-.6-3.2-.9-4.6-26.8 0-36.9 3.8-59.5 6.3z"/></svg>')
 }
 .md-typeset .admonition.pied-piper,
 .md-typeset details.pied-piper {
  border-color: rgb(43, 155, 70);
 }
 .md-typeset .pied-piper > .admonition-title,
 .md-typeset .pied-piper > summary {
  background-color: rgba(43, 155, 70, 0.1);
  border-color: rgb(43, 155, 70);
 }
 .md-typeset .pied-piper > .admonition-title::before,
 .md-typeset .pied-piper > summary::before {
  background-color: rgb(43, 155, 70);
  -webkit-mask-image: var(--md-admonition-icon--pied-piper);
          mask-image: var(--md-admonition-icon--pied-piper);
 }
 ```
 You should now be able to create an admonition of the `pied-piper` type. Note
 that you can also use this technique to override existing admonition icons or
 colors. [You can even add animations][18].
 <style>
  :root {
@ -513,12 +433,45 @@ colors. [You can even add animations][18].
 _Example_:
-``` markdown
+=== ":octicons-file-code-16: docs/example.md"
-!!! pied-piper "Pied Piper"
+
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+    ``` markdown
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+    !!! pied-piper "Pied Piper"
-    massa, nec semper lorem quam in massa.
+
-```
+        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.
    ```
 === ":octicons-file-code-16: docs/stylesheets/extra.css"
    ``` css
    :root {
      --md-admonition-icon--pied-piper: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M244 246c-3.2-2-6.3-2.9-10.1-2.9-6.6 0-12.6 3.2-19.3 3.7l1.7 4.9zm135.9 197.9c-19 0-64.1 9.5-79.9 19.8l6.9 45.1c35.7 6.1 70.1 3.6 106-9.8-4.8-10-23.5-55.1-33-55.1zM340.8 177c6.6 2.8 11.5 9.2 22.7 22.1 2-1.4 7.5-5.2 7.5-8.6 0-4.9-11.8-13.2-13.2-23 11.2-5.7 25.2-6 37.6-8.9 68.1-16.4 116.3-52.9 146.8-116.7C548.3 29.3 554 16.1 554.6 2l-2 2.6c-28.4 50-33 63.2-81.3 100-31.9 24.4-69.2 40.2-106.6 54.6l-6.3-.3v-21.8c-19.6 1.6-19.7-14.6-31.6-23-18.7 20.6-31.6 40.8-58.9 51.1-12.7 4.8-19.6 10-25.9 21.8 34.9-16.4 91.2-13.5 98.8-10zM555.5 0l-.6 1.1-.3.9.6-.6zm-59.2 382.1c-33.9-56.9-75.3-118.4-150-115.5l-.3-6c-1.1-13.5 32.8 3.2 35.1-31l-14.4 7.2c-19.8-45.7-8.6-54.3-65.5-54.3-14.7 0-26.7 1.7-41.4 4.6 2.9 18.6 2.2 36.7-10.9 50.3l19.5 5.5c-1.7 3.2-2.9 6.3-2.9 9.8 0 21 42.8 2.9 42.8 33.6 0 18.4-36.8 60.1-54.9 60.1-8 0-53.7-50-53.4-60.1l.3-4.6 52.3-11.5c13-2.6 12.3-22.7-2.9-22.7-3.7 0-43.1 9.2-49.4 10.6-2-5.2-7.5-14.1-13.8-14.1-3.2 0-6.3 3.2-9.5 4-9.2 2.6-31 2.9-21.5 20.1L15.9 298.5c-5.5 1.1-8.9 6.3-8.9 11.8 0 6 5.5 10.9 11.5 10.9 8 0 131.3-28.4 147.4-32.2 2.6 3.2 4.6 6.3 7.8 8.6 20.1 14.4 59.8 85.9 76.4 85.9 24.1 0 58-22.4 71.3-41.9 3.2-4.3 6.9-7.5 12.4-6.9.6 13.8-31.6 34.2-33 43.7-1.4 10.2-1 35.2-.3 41.1 26.7 8.1 52-3.6 77.9-2.9 4.3-21 10.6-41.9 9.8-63.5l-.3-9.5c-1.4-34.2-10.9-38.5-34.8-58.6-1.1-1.1-2.6-2.6-3.7-4 2.2-1.4 1.1-1 4.6-1.7 88.5 0 56.3 183.6 111.5 229.9 33.1-15 72.5-27.9 103.5-47.2-29-25.6-52.6-45.7-72.7-79.9zm-196.2 46.1v27.2l11.8-3.4-2.9-23.8zm-68.7-150.4l24.1 61.2 21-13.8-31.3-50.9zm84.4 154.9l2 12.4c9-1.5 58.4-6.6 58.4-14.1 0-1.4-.6-3.2-.9-4.6-26.8 0-36.9 3.8-59.5 6.3z"/></svg>')
    }
    .md-typeset .admonition.pied-piper,
    .md-typeset details.pied-piper {
      border-color: rgb(43, 155, 70);
    }
    .md-typeset .pied-piper > .admonition-title,
    .md-typeset .pied-piper > summary {
      background-color: rgba(43, 155, 70, 0.1);
      border-color: rgb(43, 155, 70);
    }
    .md-typeset .pied-piper > .admonition-title::before,
    .md-typeset .pied-piper > summary::before {
      background-color: rgb(43, 155, 70);
      -webkit-mask-image: var(--md-admonition-icon--pied-piper);
              mask-image: var(--md-admonition-icon--pied-piper);
    }
    ```
 === ":octicons-file-code-16: mkdocs.yml"
    ``` yaml
    extra_css:
      - stylesheets/extra.css
    ```
 _Result_:
@ -528,6 +481,5 @@ _Result_:
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.
-  [16]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
+  [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
-  [17]: ../customization.md#additional-css
+  [additional style sheet]: ../customization.md#additional-css
  [18]: icons-emojis.md#with-animations
--- 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
+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
-The [Attribute List][1] extension, which is part of the standard Markdown
+following lines to `mkdocs.yml`:
 library, allows to __add HTML attributes and CSS classes to Markdown elements__,
 and can be enabled via `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
+In order to render a link as a button, suffix it with curly braces and add the
-converted into a button by adding the `.md-button` CSS class, which will receive
+`.md-button` class selector to it. The button will receive the selected
-the selected [primary color][3].
+[primary color] and [accent color] if active.
 _Example_:
 ``` markdown
-[Subscribe to our mailing list](#){ .md-button }
+[Subscribe to our newsletter](#){ .md-button }
 ```
 _Result_:
-[Subscribe to our mailing list][4]{ .md-button }
+[Subscribe to our newsletter][Demo]{ .md-button }
-  [2]: #attribute-list
+  [primary color]: ../setup/changing-the-colors.md#primary-color
-  [3]: ../setup/changing-the-colors.md#primary-color
+  [accent color]: ../setup/changing-the-colors.md#accent-color 
-  [4]: javascript:alert$.next("Done!")
+  [Demo]: javascript:alert$.next("Demo")
 ### Adding primary buttons
-If you want to display a filled, primary button (like on the [landing page][5]
+If you want to display a filled, primary button (like on the [landing page]
-of Material for MkDocs), add both the `.md-button` and `.md-button--primary`
+of Material for MkDocs), add both, the `.md-button` and `.md-button--primary`
-CSS classes.
+CSS class selectors.
 _Example_:
 ``` markdown
-[Subscribe to our mailing list](#){ .md-button .md-button--primary }
+[Subscribe to our newsletter](#){ .md-button .md-button--primary }
 ```
 _Result_:
-[Subscribe to our mailing list][4]{ .md-button .md-button--primary }
+[Subscribe to our newsletter][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
+Of course, icons can be added to all types of buttons by using the [icon syntax]
-icon syntax][6] and referencing a valid path to [any icon bundled with the
+together with any valid icon shortcode, which can be easily found with a few keystrokes through the [icon search].
 theme][7].
 _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
+  [icon syntax]: icons-emojis.md#using-icons
-  [7]: icons-emojis.md#search
+  [icon search]: icons-emojis.md#search
--- a/docs/reference/code-blocks.md
+++ b/docs/reference/code-blocks.md
@ -6,191 +6,89 @@ 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
+This configuration enables syntax highlighting on code blocks and inline code 
-
+blocks, and allows to include source code directly from other files. Add the 
-[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3] ·
+following lines to `mkdocs.yml`:
 :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`:
 ``` 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-tag-24: insiders-2.2.0][Insiders] ·
 :octicons-unlock-24: Feature flag ·
 :octicons-beaker-24: Experimental
 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 code 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 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
    code block by using a slightly different syntax based on the
    [Attribute Lists] 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 Lists]: ../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
+To add syntax highlighting to those blocks, add the language shortcode directly
-after the opening block. See the [list of available lexers][17] to find the
+after the opening block. See the [list of available lexers] to find the
-short name for a given language.
+shortcode for a given language.
 _Example_:
@ -206,117 +104,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] ·
+Code annotations can be placed anywhere in a code block where a comment for the
-:octicons-beaker-24: Experimental ·
+language of the block can be placed, e.g. for JavaScript in `#!js // ...` and
-[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][18]{ .mdx-insiders }
+`#!js /* ... */`, for YAML in `#!yaml # ...`, etc.[^1]
-Annotations offer a comfortable and friendly way to attach explanations to
+  [^1]:
-arbitrary sections of code blocks by adding simple markers within block/inline
+    Code annotations require syntax highlighting with [Pygments] – they're
-comments that refer to items of a list following the code block, i.e. `(1)`,
+    currently not compatible with JavaScript syntax highlighters. Support will
-`(2)`, etc. Material for MkDocs detaches the list from the flow of the document,
+    be added at a later point, allowing to always place code annotations at the
-injects the content of each list item into a tooltip, and links each list marker
+    end of lines.
 to the corresponding tooltip.
-In order to opt-in to annotation support, a slightly different syntax is
+_Example_:
-required – just add the respective [language short code][17] and the `.annotate`
+
-class, after the three backticks. Alternatively, if you want to enable annotations
+```` markdown
-globally, add the following to `mkdocs.yml`:
+``` 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
+1.  :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
-for the language can be placed, which for JavaScript is `// (1)` and
+    text__, images, ... basically anything that can be expressed in Markdown.
 `/* (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
 ### 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 +174,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
+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`.
+at `1`, regardless of the starting line number specified as part of
 [`linenums`][Adding line numbers].
-_Example_:
+=== "Line numbers"
-```` markdown
+    _Example_:
 ``` 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_:
+    ```` 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"
+    _Result_:
 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]
 ```
-Line ranges can also be used for conveniently specifying multiple lines.
+    ``` 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):
                if items[j] > items[j + 1]:
                    items[j], items[j + 1] = items[j + 1], items[j]
    ```
-_Example_:
+=== "Line number ranges"
-```` markdown
+    _Example_:
 ``` 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_:
+    ```` 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"
+    _Result_:
-def bubble_sort(items):
+
-    for i in range(len(items)):
+    ``` python linenums="1" hl_lines="2-5"
-        for j in range(len(items) - 1 - i):
+    def bubble_sort(items):
-            if items[j] > items[j + 1]:
+        for i in range(len(items)):
-                items[j], items[j + 1] = items[j + 1], items[j]
+            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
+When [InlineHilite] is enabled, syntax highlighting can be applied to inline
-prefixing them with a shebang-like sequence, i.e. `#!`, directly followed by
+code blocks by prefixing them with a shebang, i.e. `#!`, directly followed by
-the [language short name][17].
+the corresponding [language shortcode][list of available lexers].
 _Example_:
@ -408,33 +244,11 @@ _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] is enabled, content from other files (including source files)
-
+can be embedded by using the [`--8<--` notation][Snippets notation] directly
-When [Snippets][24] is enabled, content from other files can be embedded, which
+from within a code block:
 is especially useful to reference and embed the contents of source files
 directly into your project documentation.
 _Example_:
@ -450,23 +264,15 @@ _Result_:
 last 4 years
 ```
-Note that [Snippets][24] is not limited to code blocks, but can be used anywhere
+  [Snippets notation]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippets-notation
 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] ·
+If [Pygments] is used, Material for MkDocs provides the [styles for code blocks]
-:octicons-mortar-board-24: Difficulty: _easy_
+[colors], which are built with a custom and well-balanced palette that works
-
+equally well for both [color schemes]:
 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]:
 - :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,29 +294,45 @@ 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
+several [types of string tokens], they use the same color. You can assign
-to most of them.
+a new color by using an [additional style sheet]:
-Create an [additional stylesheet][6], and add:
+=== ":octicons-file-code-16: docs/stylesheets/extra.css"
-``` css
+    ``` css
-:root > * {
+    :root > * {
-  --md-code-hl-string-color: #0FF1CE;
+      --md-code-hl-string-color: #0FF1CE;
-}
+    }
-```
+    ```
-If you want to tweak a specific type of string, i.e. ``#!js `backticks` ``, you
+=== ":octicons-file-code-16: mkdocs.yml"
 can lookup the specific class name in the [syntax theme definition][29], and
 override it as part of your additional stylesheet:
-``` css
+    ``` yaml
-.highlight .sb {
+    extra_css:
-  color: #0FF1CE;
+      - stylesheets/extra.css
-}
+    ```
 ```
-  [25]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss#
+If you want to tweak a specific type of string, e.g. ``#!js `backticks` ``, you
-  [26]: #use-pygments
+can lookup the specific CSS class name in the [syntax theme definition], and
-  [27]: ../setup/changing-the-colors.md#color-scheme
+override it as part of your [additional style sheet]:
-  [28]: https://pygments.org/docs/tokens/#literals
+
-  [29]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
+=== ":octicons-file-code-16: docs/stylesheets/extra.css"
    ``` css
    .highlight .sb {
      color: #0FF1CE;
    }
    ```
 === ":octicons-file-code-16: mkdocs.yml"
    ``` yaml
    extra_css:
      - stylesheets/extra.css
    ```
  [colors]: 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 style sheet]: ../customization.md#additional-css
  [syntax theme definition]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
--- a/docs/reference/content-tabs.md
+++ b/docs/reference/content-tabs.md
@ -11,53 +11,59 @@ grouping code blocks and other content.
 ## Configuration
-### Tabbed
+This configuration enables content tabs, and allows to nest arbitrary content
-
+inside content tabs, including code blocks and ... more content tabs! Add the 
-[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
+following lines to `mkdocs.yml`:
 The [Tabbed][2] extension, which is part of [Python Markdown Extensions][3],
 integrates with Material for MkDocs and can be enabled via `mkdocs.yml`:
 === "Modern"
    ``` yaml
    markdown_extensions:
      - pymdownx.tabbed:
          alternate_style: true # (1)
    ```
    1. As of 7.3.1, support was added for the new [`alternate_style`][12] flag,
       which has much better behavior on smaller screen sizes, as content tabs
       are now scrollable and will overflow instead of break across multiple
       lines.
        __The legacy style will be deprecated with the next major release.__
  [12]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#alternate-style
 === "Legacy"
    ``` yaml
    markdown_extensions:
      - pymdownx.tabbed
    ```
  [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_tabbed.scss
  [2]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
  [3]: https://facelessuser.github.io/pymdown-extensions/
 ### SuperFences
 The [SuperFences][4] extension, which is also part of [Python Markdown
 Extensions][3], allows for the __nesting of code and content blocks inside
 tabs__, and is therefore strongly recommended:
 ``` yaml
 markdown_extensions:
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true 
 ```
-  [4]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
+See additional configuration options:
 - [SuperFences]
 - [Tabbed]
  [SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
  [Tabbed]: ../setup/extensions/python-markdown-extensions.md#tabbed
 ### Linked content tabs
 [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
 [:octicons-tag-24: insiders-2.9.0][Insiders] ·
 :octicons-unlock-24: Feature flag ·
 :octicons-beaker-24: Experimental
 When enabled, all content tabs across the whole documentation site will be
 linked and switch to the same label when the user clicks on a tab. Add the 
 following lines to `mkdocs.yml`:
 ``` yaml
 theme:
  features:
    - content.tabs.link
 ```
 Content tabs are linked based on their label, not offset. This means that all
 tabs with the same label will be activated when a user clicks a content tab
 regardless of order inside a container. Furthermore, this feature is fully
 integrated with [instant loading] and persisted across page loads.
 === ":octicons-check-circle-fill-16: Enabled"
    [![content.tabs.link enabled]][content.tabs.link enabled]
 === ":octicons-skip-16: Disabled"
    [![content.tabs.link disabled]][content.tabs.link disabled]
  [Insiders]: ../insiders/index.md
  [instant loading]: ../setup/setting-up-navigation.md#instant-loading
  [content.tabs.link enabled]: ../assets/screenshots/content-tabs-link.png
  [content.tabs.link disabled]: ../assets/screenshots/content-tabs.png
 ## Usage
@ -153,45 +159,11 @@ _Result_:
    2. Donec vitae suscipit est
    3. Nulla tempor lobortis orci
 ### Linking content tabs
 [:octicons-file-code-24: Source][5] ·
 :octicons-beaker-24: Experimental ·
 [:octicons-heart-fill-24:{ .mdx-heart } Insiders only][5]{ .mdx-insiders }
 When _linking_ is enabled, all content tabs on a page will be linked and show
 the same active tab when the user clicks on a label. Add the following lines
 to `mkdocs.yml`:
 ``` yaml
 theme:
  features:
    - content.tabs.link
 ```
 Content tabs are linked based on their label, not offset. This means that all
 tabs with the same label will be activated when a user clicks a content tab
 regardless of order inside a container. Furthermore, this feature is fully
 integrated with [instant loading][6] and persisted across page loads.
 === "With linking"
    [![With linking][7]][7]
 === "Without linking"
    [![Without linking][8]][8]
  [5]: ../insiders/index.md
  [6]: ../setup/setting-up-navigation.md#instant-loading
  [7]: ../assets/screenshots/content-tabs-link.png
  [8]: ../assets/screenshots/content-tabs.png
 ### Embedded content
-When [SuperFences][9] is enabled, content tabs can contain arbitrary nested
+When [SuperFences] is enabled, content tabs can contain arbitrary nested
 content, including further content tabs, and can be nested in other blocks like
-[admonitions][10], [details][11] or blockquotes:
+[admonitions] or blockquotes:
 _Example_:
@ -267,6 +239,4 @@ _Result_:
        2. Donec vitae suscipit est
        3. Nulla tempor lobortis orci
-  [9]: #superfences
+  [admonitions]: admonitions.md
  [10]: admonitions.md
  [11]: admonitions.md#details
--- a/docs/reference/data-tables.md
+++ b/docs/reference/data-tables.md
@ -6,15 +6,27 @@ template: overrides/main.html
 Material for MkDocs defines default styles for data tables – an excellent way
 of rendering tabular data in project documentation. Furthermore, customizations
-like [sortable tables][1] can be achieved with a third-party library and some
+like [sortable tables] can be achieved with a third-party library and some
-[additional JavaScript][2].
+[additional JavaScript].
-  [1]: #sortable-tables
+  [sortable tables]: #sortable-tables
-  [2]: ../customization.md#additional-javascript 
+  [additional JavaScript]: ../customization.md#additional-javascript 
 ## Configuration
-None.
+This configuration enables Markdown table support, which should normally be
 enabled by default, but to be sure, add the following lines to `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - tables
 ```
 See additional configuration options:
 - [Tables]
  [Tables]: ../setup/extensions/python-markdown.md#tables
 ## Usage
@ -22,7 +34,7 @@ None.
 Data tables can be used at any position in your project documentation and can
 contain arbitrary Markdown, including inline code blocks, as well as [icons and
-emojis][3].
+emojis].
 _Example_:
@ -42,12 +54,12 @@ _Result_:
 | `PUT`       | :material-check-all: Update resource |
 | `DELETE`    | :material-close:     Delete resource |
-  [3]: icons-emojis.md
+  [icons and emojis]: icons-emojis.md
 ### Column alignment
 If you want to align a specific column to the `left`, `center` or `right`, you
-can use the [regular Markdown syntax][4] placing `:` characters at the beginning
+can use the [regular Markdown syntax] placing `:` characters at the beginning
 and/or end of the divider.
 === "Left"
@ -110,17 +122,17 @@ and/or end of the divider.
    | `PUT`       | :material-check-all: Update resource |
    | `DELETE`    | :material-close:     Delete resource |
-  [4]: https://www.markdownguide.org/extended-syntax/#tables
+  [regular Markdown syntax]: https://www.markdownguide.org/extended-syntax/#tables
 ## Customization
 ### Sortable tables
-If you want to make data tables sortable, you can add [tablesort][5], which is
+If you want to make data tables sortable, you can add [tablesort], which is
 natively integrated with Material for MkDocs and will also work with [instant
-loading][6] via [additional JavaScript][2]:
+loading] via [additional JavaScript]:
-=== "`docs/javascripts/tables.js`"
+=== ":octicons-file-code-16: docs/javascripts/tablesort.js"
    ``` js
    document$.subscribe(function() {
@ -131,17 +143,17 @@ loading][6] via [additional JavaScript][2]:
    })
    ```
-=== "`mkdocs.yml`"
+=== ":octicons-file-code-16: mkdocs.yml"
    ``` yaml
    extra_javascript:
      - https://cdnjs.cloudflare.com/ajax/libs/tablesort/5.2.1/tablesort.min.js
-      - javascripts/tables.js
+      - javascripts/tablesort.js
    ```
-_Note that [tablesort][5] provides alternative comparison implementations like
+Note that [tablesort] provides alternative comparison implementations like
-numbers, dates, filesizes and month names. See the official documentation for
+numbers, filesizes, dates and month names. See the [tablesort documentation]
-more information._
+[tablesort] for more information.
 _Example_:
@ -167,5 +179,5 @@ _Result_:
  new Tablesort(tables.item(tables.length - 1));
 </script>
-  [5]: http://tristen.ca/tablesort/demo/
+  [tablesort]: http://tristen.ca/tablesort/demo/
-  [6]: ../setup/setting-up-navigation.md#instant-loading
+  [instant loading]: ../setup/setting-up-navigation.md#instant-loading
--- a/docs/reference/diagrams.md
+++ b/docs/reference/diagrams.md
@ -6,22 +6,20 @@ template: overrides/main.html
 Diagrams help to communicate complex relationships and interconnections between
 different technical components, and are a great addition to project
-documentation. Material for MkDocs integrates with [Mermaid.js][1], a very
+documentation. Material for MkDocs integrates with [Mermaid.js], a very
 popular and flexible solution for drawing diagrams.
-  [1]: https://mermaid-js.github.io/mermaid/
+  [Mermaid.js]: https://mermaid-js.github.io/mermaid/
 ## Configuration
-### SuperFences
+[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
 [:octicons-tag-24: insiders-1.15.0][Insiders] ·
 :octicons-beaker-24: Experimental
-[:octicons-file-code-24: Source][2] ·
+This configuration enables native support for [Mermaid.js] diagrams. Material
-:octicons-beaker-24: Experimental ·
+for MkDocs will automatically initialize the JavaScript runtime when a page 
-[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][2]{ .mdx-insiders }
+includes a `mermaid` code block:
 The [SuperFences][3] extension, which is part of [Python Markdown
 Extensions][4], allows for adding __custom fences__, which can be used to
 render [Mermaid.js][1] diagrams with zero effort:
 ``` yaml
 markdown_extensions:
@ -32,51 +30,28 @@ markdown_extensions:
          format: !!python/name:pymdownx.superfences.fence_code_format
 ```
-No further configuration is necessary. Material for MkDocs will automatically
+No further configuration is necessary. Advantages over a custom integration:
 load and initialize the [Mermaid.js][1] runtime when a page includes a [fenced
 `mermaid` block][5]. Furthermore:
- [x] Works with [instant loading][6] without any additional effort
+- [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][7]
+- [x] Fonts and colors can be customized with [additional style sheets]
- [x] Support for both, light and dark color schemes
+- [x] Support for both, light and dark color schemes – _try it on this page!_
 _While it's also possible to integrate [Mermaid.js][1] 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][1] features should work out-of-the-box, Material for
+    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
+    MkDocs will currently only adjust the fonts and colors for flowcharts,
-    diagrams, class diagams, state diagrams and entity relationship diagrams.
+    sequence diagrams, class diagams, state diagrams and entity relationship 
    diagrams.
-  [^2]:
+  [Insiders]: ../insiders/index.md
-    If you don't want to use the native integration, [mkdocs-mermaid2-plugin][8]
+  [instant loading]: ../setup/setting-up-navigation.md#instant-loading
-    might be a good alternative. However, note that this plugin cannot be used
+  [additional style sheets]: ../customization.md#additional-css
    in conjunction with the [mkdocs-minify-plugin][9] and doesn't adapt to
    dark mode.
  [2]: ../insiders/index.md
  [3]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
  [4]: https://facelessuser.github.io/pymdown-extensions/
  [5]: #usage
  [6]: ../setup/setting-up-navigation.md#instant-loading
  [7]: ../customization.md#additional-css
  [8]: https://github.com/fralau/mkdocs-mermaid2-plugin
  [9]: https://github.com/byrnereese/mkdocs-minify-plugin
 ## Usage
 Mermaid diagrams are written as [code blocks][10] with the help of the
 [SuperFences][11] extension. They must be enclosed with two separate lines
 containing three backticks.
  [10]: code-blocks.md
  [11]: #superfences
 ### Using flowcharts
-[Flowcharts][12] are diagrams that represent workflows or processes. The steps
+[Flowcharts] are diagrams that represent workflows or processes. The steps
 are rendered as nodes of various kinds and are connected by edges, describing
 the necessary order of steps.
@ -104,11 +79,11 @@ graph LR
  B ---->|No| E[Yay!];
 ```
-  [12]: https://mermaid-js.github.io/mermaid/#/flowchart
+  [Flowcharts]: https://mermaid-js.github.io/mermaid/#/flowchart
 ### Using sequence diagrams
-[Sequence diagrams][13] describe a specific scenario as sequential interactions 
+[Sequence diagrams] describe a specific scenario as sequential interactions 
 between multiple objects or actors, including the messages that are exchanged
 between those actors.
@ -142,11 +117,11 @@ sequenceDiagram
  Bob-->>John: Jolly good!
 ```
-  [13]: https://mermaid-js.github.io/mermaid/#/sequenceDiagram
+  [Sequence diagrams]: https://mermaid-js.github.io/mermaid/#/sequenceDiagram
 ### Using state diagrams
-[State diagrams][14] are a great tool to describe the behavior of a system,
+[State diagrams] are a great tool to describe the behavior of a system,
 decomposing it into a finite number of states, and transitions between those
 states.
@ -194,11 +169,11 @@ stateDiagram-v2
  }
 ```
-  [14]: https://mermaid-js.github.io/mermaid/#/stateDiagram
+  [State diagrams]: https://mermaid-js.github.io/mermaid/#/stateDiagram
 ### Using class diagrams
-[Class diagrams][15] are central to object oriented programing, describing the
+[Class diagrams] are central to object oriented programing, describing the
 structure of a system by modelling entities as classes and relationships between
 them.
@ -266,11 +241,11 @@ classDiagram
  }
 ```
-  [15]: https://mermaid-js.github.io/mermaid/#/classDiagram
+  [Class diagrams]: https://mermaid-js.github.io/mermaid/#/classDiagram
 ### Using entity-relationship diagrams
-An [entity-relationship diagram][16] is composed of entity types and specifies
+An [entity-relationship diagram] is composed of entity types and specifies
 relationships that exist between entities. It describes inter-related things in
 a specific domain of knowledge.
@ -294,4 +269,4 @@ erDiagram
  CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
 ```
-  [16]: https://mermaid-js.github.io/mermaid/#/entityRelationshipDiagram
+  [entity-relationship diagram]: https://mermaid-js.github.io/mermaid/#/entityRelationshipDiagram
--- a/docs/reference/footnotes.md
+++ b/docs/reference/footnotes.md
@ -4,19 +4,15 @@ template: overrides/main.html
 # Footnotes
-Footnotes are a great way to add references to supplemental or additional
+Footnotes are a great way to add supplemental or additional information to a
-information for a specific section of a document without interrupting the
+specific word, phrase or sentence without interrupting the flow of a document.
-document flow. Material for MkDocs provides the ability to insert inline
+Material for MkDocs provides the ability to define, reference and render
-footnotes and render them at the bottom of the page.
+footnotes.
 ## Configuration
-### Footnotes
+This configuration adds the ability to define inline footnotes, which are then
-
+rendered below all Markdown content of a document. Add the following lines to
 [: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`:
 ``` yaml
@ -24,8 +20,11 @@ markdown_extensions:
  - footnotes
 ```
-  [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_footnotes.scss
+See additional configuration options:
-  [2]: https://python-markdown.github.io/extensions/footnotes/
+
 - [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]:
+[^2]:
-      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-      nulla. Curabitur feugiat, tortor non consequat finibus, justo purus
+    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus
-      auctor massa, nec semper lorem quam in massa.
+    auctor massa, nec semper lorem quam in massa.
 [Jump to footnote at the bottom of the page](#fn:2)
--- a/docs/reference/formatting.md
+++ b/docs/reference/formatting.md
@ -6,117 +6,42 @@ 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
+This configuration enables support for keyboard keys, tracking changes in
-
+documents, defining sub- and superscript and highlighting text. Add the 
-[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3]
+following lines to `mkdocs.yml`:
 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`:
 ``` 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/
+See additional configuration options:
  [7]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
  [8]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/
-### SmartSymbols
+- [Critic]
 - [Caret, Mark & Tilde]
 - [Keys]
-The [SmartSymbols][9] extension, which is also part of [Python Markdown 
+  [Critic]: ../setup/extensions/python-markdown-extensions.md#critic
-Extensions][4], __converts special characters into their corresponding
+  [Caret, Mark & Tilde]: ../setup/extensions/python-markdown-extensions.md#caret-mark-tilde
-symbols__, and can be enabled via `mkdocs.yml`:
+  [Keys]: ../setup/extensions/python-markdown-extensions.md#keys
 ``` 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/
 ## Usage
 ### Highlighting changes
-When [Critic][10] is enabled, [Critic Markup][1] can be used, which adds the
+When [Critic] is enabled, [Critic Markup] can be used, which adds the ability to 
-ability to _highlight suggested changes_, as well as add _inline comments_ to a 
+highlight suggested changes, as well as add inline comments to a document.
 document:
  [10]: #critic
 _Example_:
@ -127,7 +52,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.
 ==}
@ -144,7 +69,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>
@ -153,9 +78,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 
+When [Caret, Mark & Tilde] are enabled, text can be highlighted with a simple 
-highlighted with a nicer syntax than using the corresponding `mark`, `ins` and 
+syntax, which is more convenient that directly using the corresponding
-`del` HTML tags:
+[`mark`][mark], [`ins`][ins] and [`del`][del] HTML tags.
 _Example_:
@ -171,13 +96,15 @@ _Result_:
 - ^^This was inserted^^
 - ~~This was deleted~~
-  [11]: #caret-mark-tilde
+  [mark]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark
  [ins]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ins
  [del]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/del
 ### Sub- and superscripts
-When the [Caret & Tilde][11] extensions are enabled, text can be sub- and 
+When [Caret & Tilde][Caret, Mark & Tilde] are enabled, text can be sub- and 
-superscripted with a nicer syntax than using the corresponding `sub` and `sup` 
+superscripted with a simple syntax, which is more convenient that directly
-HTML tags:
+using the corresponding [`sub`][sub] and [`sup`][sup]  HTML tags:
 _Example_:
@ -191,4 +118,23 @@ _Result_:
 - H~2~0
 - A^T^A
-  [11]: #caret-mark-tilde
+  [sub]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sub
  [sup]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sup
 ### 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]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/#extendingmodifying-key-map-index
--- 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
+than 8.000 icons][icon search] and thousands of emojis in your project 
-with practically zero additional effort. Furthermore, custom icons can be added
+documentation with practically zero additional effort. Moreover, custom icons 
-and used in `mkdocs.yml`, documents and templates.
+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
+  **Tip:** Enter some keywords to find icons and emojis and click on the
-  the shortcode to copy it to your clipboard.
+  shortcode to copy it to your clipboard.
 </small>
 ## Configuration
-### Emoji
+This configuration enables the use of icons and emojis by using simple
-
+shortcodes which can be discovered through the [icon search]. Add the following
-[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3]
+lines to `mkdocs.yml`:
 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]:
 ``` yaml
 markdown_extensions:
@ -47,44 +45,28 @@ markdown_extensions:
 The following icon sets are bundled with Material for MkDocs:
- :material-material-design: – [Material Design][6]
+- :material-material-design: – [Material Design]
- :fontawesome-brands-font-awesome-flag: – [FontAwesome][7]
+- :fontawesome-brands-font-awesome: – [FontAwesome]
- :octicons-mark-github-16: – [Octicons][8]
+- :octicons-mark-github-16: – [Octicons]
-You can also add [additional icons][9]. When using emojis, it's recommended to
+See additional configuration options:
 consult the official documentation of [Python Markdown Extensions][3] to learn
 about configuration options.
-  [1]: icons-emojis.md#search
+- [Emoji]
-  [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_emoji.scss
+- [Emoji with custom icons]
  [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
-### Attribute List
+  [Material Design]: https://materialdesignicons.com/
-
+  [FontAwesome]: https://fontawesome.com/icons?d=gallery&m=free
-The [Attribute List][10] extension, which is part of the standard Markdown
+  [Octicons]: https://octicons.github.com/
-library, allows to __add HTML attributes and CSS classes to Markdown elements__,
+  [Emoji]: ../setup/extensions/python-markdown-extensions.md#emoji
-and can be enabled via `mkdocs.yml`
+  [Emoji with custom icons]: ../setup/extensions/python-markdown-extensions.md#custom-icons
 ``` yaml
 markdown_extensions:
  - attr_list
 ```
  [10]: https://python-markdown.github.io/extensions/attr_list/
 ## 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
+between two colons. If you're using [Twemoji] (recommended), you can look up
-the shortcodes at [Emojipedia][12].
+the shortcodes at [Emojipedia].
 _Example_:
@ -96,54 +78,40 @@ _Result_:
 :smile:
-  [11]: https://twemoji.twitter.com/
+  [Twemoji]: https://twemoji.twitter.com/
-  [12]: https://emojipedia.org/twitter/
+  [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 `-`:
+[`.icons`][custom icons] directory, and replacing `/` with `-`:
 _Example_:
 ```
- :material-account-circle: – `.icons/material/account-circle.svg`
+- :material-account-circle: – `material/account-circle.svg`
- :fontawesome-regular-laugh-wink: – `.icons/fontawesome/regular/laugh-wink.svg`
+- :fontawesome-regular-laugh-wink: – `fontawesome/regular/laugh-wink.svg`
- :octicons-repo-push-16: – `.icons/octicons/repo-push-16.svg`
+- :octicons-repo-push-16: – `octicons/repo-push-16.svg`
 ```
 _Result_:
- :material-account-circle: – [`.icons/material/account-circle.svg`][14]
+- :material-account-circle: – [`material/account-circle.svg`][icon Material]
- :fontawesome-regular-laugh-wink: – [`.icons/fontawesome/regular/laugh-wink.svg`][15]
+- :fontawesome-regular-laugh-wink: – [`fontawesome/regular/laugh-wink.svg`][icon FontAwesome]
- :octicons-repo-push-16: – [`.icons/octicons/repo-push-16.svg`][16]
+- :octicons-repo-push-16: – [`octicons/repo-push-16.svg`][icon Octicons]
-  [13]: #emoji
+  [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
-  [14]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/material/account-circle.svg
+  [icon Material]: 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
+  [icon FontAwesome]: 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
+  [icon Octicons]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/octicons/repo-push-16.svg
 #### with colors
-When the [Attribute List][17] extension is enabled, custom CSS classes and
+When [Attribute Lists] is enabled, custom CSS classes can be added to icons by
-attributes can be added to icons by suffixing the icon with a special syntax.
+suffixing the icon with a special syntax. While HTML allows to use
-While HTML and CSS allow to use [inline styles][18], it's always best to add
+[inline styles], it's always recommended to add an [additional style sheet] and
-an [additional stylesheet][19] and put styles into dedicated CSS classes:
+move declarations into dedicated CSS classes.
 ``` css
 .medium {
  color: #00AB6C;
 }
 .twitter {
  color: #1DA1F2;
 }
 .facebook {
  color: #4267B2;
 }
 ```
 Then, simply add the CSS class to the icon.
 <style>
  .medium {
@ -159,11 +127,34 @@ Then, simply add the CSS class to the icon.
 _Example_:
-``` markdown
+=== ":octicons-file-code-16: docs/example.md"
- :fontawesome-brands-medium:{ .medium } – Medium
+
- :fontawesome-brands-twitter:{ .twitter } – Twitter
+    ``` markdown
- :fontawesome-brands-facebook:{ .facebook } – Facebook
+    - :fontawesome-brands-medium:{ .medium } – Medium
-```
+    - :fontawesome-brands-twitter:{ .twitter } – Twitter
    - :fontawesome-brands-facebook:{ .facebook } – Facebook
    ```
 === ":octicons-file-code-16: docs/stylesheets/extra.css"
    ``` css
    .medium {
      color: #00AB6C;
    }
    .twitter {
      color: #1DA1F2;
    }
    .facebook {
      color: #4267B2;
    }
    ```
 === ":octicons-file-code-16: mkdocs.yml"
    ``` yaml
    extra_css:
      - stylesheets/extra.css
    ```
 _Result_:
@ -171,52 +162,61 @@ _Result_:
 - :fontawesome-brands-twitter:{ .twitter } – Twitter
 - :fontawesome-brands-facebook:{ .facebook } – Facebook
-  [17]: #attribute-list
+  [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
-  [18]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style
+  [inline styles]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style
-  [19]: ../customization.md#additional-css
+  [additional style sheet]: ../customization.md#additional-css
 #### with animations
-Similar to adding [colors][20], it's just as easy to add [CSS animations][21] to
+Similar to adding [colors], it's just as easy to add [animations] to icons by
-icons by using an [additional stylesheet][6], defining a `#!css @keyframes` rule
+using an [additional style sheet], defining a `@keyframes` rule and adding a
-and adding the dedicated CSS class to the icon:
+dedicated CSS class to the icon.
 ``` css
@keyframes heart {
  0%, 40%, 80%, 100% {
    transform: scale(1);
  }
  20%, 60% {
    transform: scale(1.15);
  }
 }
 .heart {
  animation: heart 1000ms infinite;
 }
 ```
 Then, simply add the CSS class to the icon.
 _Example_:
-``` markdown
+=== ":octicons-file-code-16: docs/example.md"
-:octicons-heart-fill-24:{ .heart }
+
-```
+    ``` markdown
    :octicons-heart-fill-24:{ .heart }
    ```
 === ":octicons-file-code-16: docs/stylesheets/extra.css"
    ``` css
    @keyframes heart {
      0%, 40%, 80%, 100% {
        transform: scale(1);
      }
      20%, 60% {
        transform: scale(1.15);
      }
    }
    .heart {
      animation: heart 1000ms infinite;
    }
    ```
 === ":octicons-file-code-16: mkdocs.yml"
    ``` yaml
    extra_css:
      - stylesheets/extra.css
    ```
 _Result_:
 :octicons-heart-fill-24:{ .mdx-heart }
-  [20]: #with-colors
+  [colors]: #with-colors
-  [21]: https://developer.mozilla.org/en-US/docs/Web/CSS/animation
+  [animations]: https://developer.mozilla.org/en-US/docs/Web/CSS/animation
 ## Customization
 ### Using icons in templates
-When you're [extending the theme][22] with partials or blocks, you can simply
+When you're [extending the theme] with partials or blocks, you can simply
-reference any icon that's [bundled with the theme][1] with Jinja's
+reference any icon that's [bundled with the theme][icon search] with Jinja's
-[`include`][23] function and wrap it with the `twemoji` class:
+[`include`][include] function and wrap it with the `.twemoji` CSS class:
 ``` html
 <span class="twemoji">
@ -226,5 +226,5 @@ reference any icon that's [bundled with the theme][1] with Jinja's
 This is exactly what Material for MkDocs does in its templates.
-  [22]: ../customization.md#extending-the-theme
+  [extending the theme]: ../customization.md#extending-the-theme
-  [23]: https://jinja.palletsprojects.com/en/2.11.x/templates/#include
+  [include]: https://jinja.palletsprojects.com/en/2.11.x/templates/#include
--- a/docs/reference/images.md
+++ b/docs/reference/images.md
@ -6,32 +6,36 @@ template: overrides/main.html
 While images are first-class citizens of Markdown and part of the core syntax, 
 it can be difficult to work with them. Material for MkDocs makes working with 
-images more comfortable by providing styles for alignment and image captions.
+images more comfortable, providing styles for image alignment and image
-
+captions.
  [1]: https://www.markdownguide.org/basic-syntax/#images-1
 ## Configuration
-### Attribute List
+This configuration adds the ability to align images, add captions to images
-
+(rendering them as figures), and mark large images for lazy-loading. Add the
-The [Attribute List][2] extension, which is part of the standard Markdown
+following lines to `mkdocs.yml`:
 library, allows to __add HTML attributes and CSS classes to Markdown elements__,
 and can be enabled via `mkdocs.yml`
 ``` yaml
 markdown_extensions:
  - attr_list
  - md_in_html
 ```
-  [2]: https://python-markdown.github.io/extensions/attr_list/
+See additional configuration options:
 - [Attribute Lists]
 - [Markdown in HTML]
  [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
  [Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html
 ## Usage
 ### Image alignment
-When the [Attribute List][3] extension is enabled, images can be aligned by
+When [Attribute Lists] is enabled, images can be aligned by adding the
-adding the respective alignment directions via the `align` attribute, i.e.
+respective alignment directions via the `align` attribute, i.e. `align=left` or
-`align=left` or `align=right`
+`align=right`:
 === "Left"
@ -65,48 +69,61 @@ adding the respective alignment directions via the `align` attribute, i.e.
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.
-_If there's insufficient space to render the text next to the image, the image
+If there's insufficient space to render the text next to the image, the image
-will stretch to the full width of the viewport, e.g. on mobile viewports._
+will stretch to the full width of the viewport, e.g. on mobile viewports.
-  [3]: #attribute-list
+??? question "Why is there no centered alignment?"
    The [`align`][align] attribute doesn't allow for centered alignment, which
    is why this option is not supported by Material for MkDocs.[^1] Instead,
    the [image captions] syntax can be used, as captions are optional.
  [^1]:
    You might also realize that the [`align`][align] attribute has been
    deprecated as of HTML5, so why use it anyways? The main reason is
    portability – it's still supported by all browsers and clients, and is very
    unlikely to be completely removed, as many older websites still use it. This
    ensures a consistent appearance when a Markdown file with these attributes
    is viewed outside of a website generated by Material for MkDocs.
  [align]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#deprecated_attributes
  [image captions]: #image-captions
 ### Image captions
 Sadly, the Markdown syntax doesn't provide native support for image captions,
-but it's always possible to resort to HTML. Using `figure` and `figcaption`, captions can be added to images.
+but it's always possible to use HTML. Using `figure` and `figcaption`, captions
 can be added to images.
 _Example_:
 ```html
-<figure>
+<figure markdown> <!-- (1) -->
-  <img src="https://dummyimage.com/600x400/eee/aaa" width="300" />
+  ![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>
+<figure markdown>
-  <img src="https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–" width="300" />
+  ![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
+Modern browsers provide [native support for lazy-loading images][lazy-loading]
-`loading` attribute, which degrades to eager-loading in browsers without
+through the `loading=lazy` directive, which degrades to eager-loading in
-support. As with [image alignment][5], if the [Attribute List][3] extension is
+browsers without support:
 enabled, images can be lazy-loaded by adding `loading=lazy`.
 _Example_:
 ``` markdown
 ![Placeholder](https://dummyimage.com/600x400/eee/aaa){ loading=lazy }
 ```
-_Result_:
+  [lazy-loading]: https://caniuse.com/#feat=loading-lazy-attr
 ![Placeholder](https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–){ loading=lazy width=300 }
  [4]: https://caniuse.com/#feat=loading-lazy-attr
  [5]: #image-alignment
--- a/docs/reference/lists.md
+++ b/docs/reference/lists.md
@ -11,64 +11,31 @@ are supported through extensions.
 ## Configuration
-### Definition List
+This configuration enables the use of definition lists and tasks lists, which
-
+are both not part of the standard Markdown syntax. Add the following lines to
-[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
+`mkdocs.yml`:
 The [Definition List][2] extension, which is part of the standard Markdown
 library, adds the ability to add definitions lists to a document and can be 
 enabled via `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - def_list
  - pymdownx.tasklist:
      custom_checkbox: true
 ```
-  [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_typeset.scss
+See additional configuration options:
  [2]: https://python-markdown.github.io/extensions/definition_lists/
-### Tasklist
+- [Definition Lists]
 - [Tasklist]
-[:octicons-file-code-24: Source][3] · [:octicons-workflow-24: Extension][4]
+  [Definition Lists]: ../setup/extensions/python-markdown.md#definition-lists
-
+  [Tasklist]: ../setup/extensions/python-markdown-extensions.md#tasklist
 The [Tasklist][4] extension, which is part of [Python Markdown Extensions][5], 
 adds support for lists with styled checkboxes, and provides several options for 
 configuring the style:
 `custom_checkbox`{ #custom-checkbox }
 :   :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_:
    ``` yaml
    markdown_extensions:
      - pymdownx.tasklist:
          custom_checkbox: true
    ```
 `clickable_checkbox`{ #clickable-checkbox }
 :   :octicons-milestone-24: Default: `false` · This option toggles whether
    checkboxes are clickable. As the state is not persisted, the use of this 
    option is _rather discouraged_ from a user experience perspective:
    ``` yaml
    markdown_extensions:
      - pymdownx.tasklist:
          clickable_checkbox: true
    ```
  [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_tasklist.scss
  [4]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/
  [5]: https://facelessuser.github.io/pymdown-extensions/
 ## Usage
 ### Using unordered lists
-An unordered list can be written by prefixing a line with a `-`, `*` or `+`
+Unordered lists can be written by prefixing a line with a `-`, `*` or `+` list
-list marker, all of which can be used interchangeably. Furthermore, all flavors
+marker, all of which can be used interchangeably. Furthermore, all flavors
 of lists can be nested inside each other.
 _Example_:
@ -95,60 +62,61 @@ _Result_:
 ### Using ordered lists
-An ordered list must start with a number immediately followed by a dot. The 
+Ordered lists must start with a number immediately followed by a dot. The 
 numbers do not need to be consecutive and can be all set to `1.`, as they will
 be re-numbered when rendered.
 _Example_:
 ``` markdown
-1. Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis
+1.  Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis
-  sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis
+    sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis
-  nulla. Vivamus a pharetra leo.
+    nulla. Vivamus a pharetra leo.
-    1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet
+    1.  Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet
-      quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a
+        quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a
-      ultricies libero efficitur sed.
+        ultricies libero efficitur sed.
-    2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet
+    2.  Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet
-      rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a.
+        rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a.
-        1. Mauris dictum mi lacus
+        1.  Mauris dictum mi lacus
-        2. Ut sit amet placerat ante
+        2.  Ut sit amet placerat ante
-        3. Suspendisse ac eros arcu
+        3.  Suspendisse ac eros arcu
 ```
 _Result_:
-1. Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis
+1.  Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis
-  sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis
+    sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis
-  nulla. Vivamus a pharetra leo.
+    nulla. Vivamus a pharetra leo.
-    1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet
+    1.  Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet
-      quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a
+        quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a
-      ultricies libero efficitur sed.
+        ultricies libero efficitur sed.
-    2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet
+    2.  Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet
-      rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a.
+        rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a.
-        1. Mauris dictum mi lacus
+        1.  Mauris dictum mi lacus
-        2. Ut sit amet placerat ante
+        2.  Ut sit amet placerat ante
-        3. Suspendisse ac eros arcu
+        3.  Suspendisse ac eros arcu
 ### Using definition lists
-[Definition lists][6] are a ideal for describing arbitrary key-value pairs, e.g. 
+When [Definition Lists] is enabled, lists of arbitrary key-value pairs, e.g. the
-the parameters of functions or modules, as used within this documentation to 
+parameters of functions or modules, can be enumerated with a simple syntax.
 describe extension or plugin parameters.
 _Example_:
 ``` markdown
 `Lorem ipsum dolor sit amet`
 :   Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
    tellus non sem sollicitudin, quis rutrum leo facilisis.
 `Cras arcu libero`
 :   Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
    ut eros sed sapien ullamcorper consequat. Nunc ligula ante.
@ -160,10 +128,12 @@ _Example_:
 _Result_:
 `Lorem ipsum dolor sit amet`
 :   Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
    tellus non sem sollicitudin, quis rutrum leo facilisis.
 `Cras arcu libero`
 :   Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
    ut eros sed sapien ullamcorper consequat. Nunc ligula ante.
@ -171,13 +141,11 @@ _Result_:
    Nam vulputate tincidunt fringilla.
    Nullam dignissim ultrices urna non auctor.
-  [6]: #definition-list
+### Using task lists
-### Using tasklists
+When [Tasklist] is enabled, unordered list items can be prefixed with `[ ]` to
-
+render an unchecked checkbox or `[x]` to render a checked checkbox, allowing
-When the [Tasklist][7] extension is enabled, unordered list items can be
+for the definition of task lists.
 prefixed with `[ ]` to render an unchecked or `[x]` to render a checked
 checkbox.
 _Example_:
@ -198,5 +166,3 @@ _Result_:
    * [x] In scelerisque nibh non dolor mollis congue sed et metus
    * [ ] Praesent sed risus massa
 - [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
  [7]: #tasklist
--- a/docs/reference/mathjax.md
+++ b/docs/reference/mathjax.md
@ -4,37 +4,23 @@ template: overrides/main.html
 # MathJax
-[MathJax][1] is a beautiful and accessible way to display _mathematical content_
+[MathJax] is a beautiful and accessible way to display mathematical content
-in the browser, allows for writing formulas in different notations, including 
+in the browser, adds support for mathematical typesetting in different notations
-[LaTeX][2], [MathML][3] and [AsciiMath][4], and can be easily integrated with 
+(e.g. [LaTeX], [MathML], [AsciiMath]), and can be easily integrated with
 Material for MkDocs.
-  [1]: https://www.mathjax.org/
+  [MathJax]: https://www.mathjax.org/
-  [2]: https://en.wikibooks.org/wiki/LaTeX/Mathematics
+  [LaTeX]: https://en.wikibooks.org/wiki/LaTeX/Mathematics
-  [3]: https://en.wikipedia.org/wiki/MathML
+  [MathML]: https://en.wikipedia.org/wiki/MathML
-  [4]: http://asciimath.org/
+  [AsciiMath]: http://asciimath.org/
 ## Configuration
-### Arithmatex
+This configuration enables support for rendering block and inline block
 equations through [MathJax]. Create a configuration file and add the following
 lines to `mkdocs.yml`:
-[:octicons-file-code-24: Source][5] · [:octicons-workflow-24: Extension][6]
+=== ":octicons-file-code-16: docs/javascripts/mathjax.js"
 The [Arithmatex][6] extension, which is part of of [Python Markdown
 Extensions][7], allows the rendering of block and inline block equations, and
 can be enabled via `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - pymdownx.arithmatex:
      generic: true
 ```
 Besides enabling the extension in `mkdocs.yml`, a MathJax configuration and 
 the JavaScript runtime need to be included, which can be done with [additional 
 JavaScript][8]:
 === "docs/javascripts/config.js"
    ``` js
    window.MathJax = {
@ -50,31 +36,32 @@ JavaScript][8]:
      }
    };
-    document$.subscribe(() => {
+    document$.subscribe(() => { // (1)
      MathJax.typesetPromise()
    })
    ```
-=== "mkdocs.yml"
+    1. This integrates MathJax with [instant loading].
 === ":octicons-file-code-16: mkdocs.yml"
    ``` yaml
    markdown_extensions:
      - pymdownx.arithmatex:
          generic: true
    extra_javascript:
-      - javascripts/config.js
+      - javascripts/mathjax.js
      - https://polyfill.io/v3/polyfill.min.js?features=es6
      - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
    ```
-_MathJax can be configured in many different ways, for which Material for MkDocs 
+See additional configuration options:
 might not provide native support. See the [official documentation][6] for more 
 information._
-!!! tip "Using MathJax with [instant loading][9]"
+- [Arithmatex]
-    There's no additional effort necessary to integrate _MathJax 3_ with
+  [Arithmatex]: ../setup/extensions/python-markdown-extensions.md#arithmatex
-    [instant loading][9] – it's expected to work straight away. However, a
+  [instant loading]: ../setup/setting-up-navigation.md#instant-loading
    previous version of this document explained how to integrate Material for
    MkDocs with _MathJax 2_, which doesn't exhibit this behavior. It's therefore
    highly recommended to switch to _MathJax 3_.
 <script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
 <script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
@ -93,12 +80,6 @@ information._
  };
 </script>
  [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_arithmatex.scss
  [6]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
  [7]: https://facelessuser.github.io/pymdown-extensions/extensions/
  [8]: ../customization.md#additional-javascript
  [9]: ../setup/setting-up-navigation.md#instant-loading
 ## Usage
 ### Using block syntax
--- a/docs/reference/meta-tags.md
+++ b/docs/reference/meta-tags.md
@ -6,57 +6,59 @@ template: overrides/main.html
 In HTML, `meta` tags allow to provide additional metadata for a document, e.g.
 page titles and descriptions, additional assets to be loaded, and [Open Graph]
-[1] data. While arbitrary metadata can always be added via [customization][2],
+metadata. While arbitrary `meta` tags can always be added via [customization],
 some common `meta` tags can be configured.
-  [1]: https://ogp.me/
+  [Open Graph]: https://ogp.me/
-  [2]: #customization
+  [customization]: #customization
 ## Configuration
-### Metadata
+This configuration adds support for setting custom page titles and descriptions
-
+in [front matter], as well as for using custom metadata in templates. Add the
-The [Metadata][3] extension, which is part of the standard Markdown library,
+following lines to `mkdocs.yml`:
 adds the ability to add [front matter][4] to a document and can be enabled via
 `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - meta
 ```
-Front matter is written as a series of key-value pairs at the beginning of the
+See additional configuration options:
 Markdown document, delimited by a blank line which ends the YAML context.
-  [3]: https://python-markdown.github.io/extensions/meta_data/
+- [Metadata]
-  [4]: https://jekyllrb.com/docs/front-matter/
+
  [front matter]: https://jekyllrb.com/docs/front-matter/
  [Metadata]: ../setup/extensions/python-markdown.md#metadata
 ## Usage
 ### Setting the page title
-If the [Metadata][5] extension is enabled, the page title can be overridden on
+When [Metadata] is enabled, the page title can be overridden for a document with
-a per-document basis with custom front matter:
+some custom front matter. Add the following lines at the top of a Markdown file:
 ``` bash
 ---
-title: Lorem ipsum dolor sit amet
+title: Lorem ipsum dolor sit amet # (1)
 ---
 # Document title
 ...
 ```
-This will set the `title` tag inside the document `head` for the current page
+1.  This will set the [`title`][title] inside the HTML document's [`head`][head]
-to the provided value. Note that the site title is appended using a dash as a
+    for the generated page to this value. Note that the site title, which is set
-separator, which is the default behavior.
+    via [`site_name`][site_name], is appended with a dash.
-  [5]: #metadata
+  [title]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title
  [head]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head
  [site_name]: https://www.mkdocs.org/user-guide/configuration/#site_name
 ### Setting the page description
-If the [Metadata][5] extension is enabled, the page description can also be
+When [Metadata] is enabled, the page description can be overridden for a
-overridden on a per-document basis with custom front matter:
+document with custom front matter. Add the following lines at the top of a
 Markdown file:
 ``` bash
 ---
@ -70,47 +72,41 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
 This will set the `meta` tag containing the site description inside the
 document `head` for the current page to the provided value.
 <div class="mdx-deprecated" markdown>
 ### Adding a web app manifest
-A [web app manifest][6] is a simple JSON file that specifies how your web
+[:octicons-tag-24: 3.1.0][manifest support] ·
 :octicons-archive-24: Deprecated ·
 :octicons-trash-24: 8.0.0
 A [web app manifest] is a simple JSON file that specifies how your web
 application should behave when installed on the user's mobile device or desktop,
 which can be set via `mkdocs.yml`:
 ``` yaml
 extra:
-  manifest: manifest.webmanifest
+  manifest: manifest.webmanifest # (1)
 ```
-  [6]: https://developers.google.com/web/fundamentals/web-app-manifest/
+1.  This option was deprecated, as it's not widely used and the same behavior
    can be achieved with [theme extension].
  [web app manifest]: https://web.dev/add-manifest/
  [manifest support]: https://github.com/squidfunk/mkdocs-material/releases/tag/3.1.0
  [theme extension]: ../customization.md#extending-the-theme
 </div>
 ## Customization
-### Displaying the metadata
+### Using metadata in templates
 Sometimes it's useful to be able to display the medatada in the page body, e.g.
 print the name of the page author at the bottom of the page. To achieve that,
 you can [extend the theme][7] by adding the following contents to `main.html`:
 ``` html
 {% extends "base.html" %}
 {% block content %}
  {{ super() }}
  {% if page and page.meta and page.meta.author %}
    <p><small>Author: {{ page.meta.author }}</small></p>
  {% endif %}
 {% endblock %}
 ```
  [7]: ../customization.md#extending-the-theme
 ### Custom meta tags
 #### on all pages
 In order to add custom `meta` tags to your document, you can [extend the theme
-][7] and simply [override the `extrahead` block][8], e.g. to add indexing
+][theme extension] and [override the `extrahead` block][overriding blocks],
-policies for search engines:
+e.g. to add indexing policies for search engines via the `robots` property:
 ``` html
 {% extends "base.html" %}
@ -120,7 +116,7 @@ policies for search engines:
 {% endblock %}
 ```
-  [8]: ../customization.md#overriding-blocks-recommended
+  [overriding blocks]: ../customization.md#overriding-blocks
 #### on a single page
@ -140,63 +136,9 @@ template override, e.g.:
 {% endblock %}
 ```
-You can now use `robots` exactly like [`title`][9] and [`description`][10] to
+You can now use `robots` exactly like [`title`][title] and
-set values. Note that in this case, the template defines an `else` branch, which
+[`description`][description] to set values. Note that in this case, the
-would set a default if none was given.
+template defines an `else` branch, which would set a default if none was given.
-  [9]: #setting-the-page-title
+  [title]: #setting-the-page-title
-  [10]: #setting-the-page-description
+  [description]: #setting-the-page-description
 ### Social meta tags
 Some further examples, including [Open Graph][1] and [Twitter Cards][11]:
 === "Open Graph"
    ``` html
    {% block extrahead %}
      {% set title = config.site_name %}
      {% 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 %}
      {% endif %}
      <meta property="og:type" content="website" />
      <meta property="og:title" content="{{ title }}" />
      <meta property="og:description" content="{{ config.site_description }}" />
      <meta property="og:url" content="{{ page.canonical_url }}" />
      <meta property="og:image" content="<url>" />
      <meta property="og:image:type" content="image/png" />
      <meta property="og:image:width" content="1200" />
      <meta property="og:image:height" content="630" />
    {% endblock %}
    ```
 === "Twitter Cards"
    ``` html
    {% block extrahead %}
      {% set title = config.site_name %}
      {% 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 %}
      {% 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>" />
    {% endblock %}
    ```
 !!! tip "Automatically generated social cards"
    If you don't want to bother with meta tags and social cards yourself, you
    can let the [built-in social cards plugin][12] do the work for you, which
    generates beautiful image previews for social media automatically during
    the build.
  [11]: https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards
  [12]: ../setup/setting-up-social-cards.md
--- a/docs/reference/variables.md
+++ b/docs/reference/variables.md
@ -1,152 +0,0 @@
 ---
 template: overrides/main.html
 ---
 # Variables
 Macros and variables are powerful tools to parametrize Markdown files, as they 
 allow to perform Jinja templating directly from Markdown. This is especially 
 useful to include technical data from other files and add central variables via 
 `mkdocs.yml`.
 ## Configuration
 ### Macros
 The [macros][1] plugin adds support to reference variables and call macros and 
 supports Jinja templating directly from Markdown. It can be installed with
 `pip`:
 ```
 pip install mkdocs-macros-plugin
 ```
 Then, add the following to `mkdocs.yml`:
 ``` yaml
 plugins:
  - macros
 ```
  [1]: https://github.com/fralau/mkdocs_macros_plugin
 ## Usage
 ### Using predefined variables
 A set of predefined variables is enabled by default and can be used from 
 Markdown, including data from `mkdocs.yml`. More specifically, predefined 
 variables fall into the following categories:
 - `config.*`: configuration parameters from `mkdocs.yml`
 - `page.*`: metadata and content of current page
 - `navigation.*`: list of all pages and sections
 - `environment.*`: underlying operating system
 - `git.*`: git-related information, if available
 _Example_:
 ``` markdown
 Welcome to {{ config.site_name }}!
 ```
 _Result_:
 ``` markdown
 Welcome to Material for MkDocs!
 ```
 A list of all predefined variables can be printed with:
 ```
 {{ macros_info() }}
 ```
 ### Using custom variables
 All data defined under `extra` in `mkdocs.yml` is automatically exposed as a
 variable and can be used from the template. This enables centralized parameter
 storage and management.
 _Example_:
 === "`docs/page.md`"
    ```` markdown
    The unit price is {{ unit.price }}
    ````
 === "`mkdocs.yml`"
    ``` yaml
    extra:
      unit:
        price: 12.50
    ```
 _Result_:
 The unit price is 12.50.
 ### Using variables in snippets
 The [macros][2] plugin can be used to allow variables in snippets, which is not
 possible with the [Snippets][3] extension alone. Add the snippets location to
 the plugin configuration in `mkdocs.yml`:
 ``` yaml
 plugins:
  - search
  - macros:
      include_dir: snippets
 ```
 In your Markdown file, include snippets with Jinja's [`include`][4] function:
 ``` markdown
 {% include "definitions.md" %}
 ```
 _Example_:
 === "`snippets/definitions.md`"
    ``` markdown
    The unit price is {{ page.meta.unit.price }}
    ```
 === "`docs/page-1.md`"
    ``` markdown
    ---
    unit:
      price: 12.50
    ---
    {% include "definitions.md" %}
    ```
 === "`docs/page-2.md`"
    ``` markdown
    ---
    unit:
      price: 25.00
    ---
    {% include "definitions.md" %}
    ```
  [2]: #macros
  [3]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
  [4]: https://jinja.palletsprojects.com/en/2.11.x/templates/#include
 ## Customization
 ### Custom macros
 The [macros][1] plugin allows to define custom macros, which can then be used
 from Markdown files. See the [official documentation][5] for more information
 how to define custom macros.
  [5]: https://mkdocs-macros-plugin.readthedocs.io/en/latest/python/
--- a/docs/setup/adding-a-comment-system.md
+++ b/docs/setup/adding-a-comment-system.md
@ -4,47 +4,43 @@ template: overrides/main.html
 # Adding a comment system
-Material for MkDocs is natively integrated with [Disqus][1], a comment system
+Material for MkDocs is natively integrated with [Disqus], a comment system that
-that provides a wide range of features like social integrations, user profiles,
+provides a wide range of features like social integrations, user profiles, as
-as well as spam and moderation tools. Of course, other comment systems can be 
+well as spam and moderation tools. Of course, other comment systems can be
 integrated, too.
-  [1]: https://disqus.com/
+  [Disqus]: https://disqus.com/
 ## Configuration
 ### Disqus
-[:octicons-file-code-24: Source][2] ·
+[:octicons-tag-24: 1.1.0][Disqus support] ·
 :octicons-milestone-24: Default: _none_
-First, ensure you've set [`site_url`][3] in `mkdocs.yml`. Then, to integrate
+First, ensure you've set [`site_url`][site_url] in `mkdocs.yml`. Then, to
-Material for MkDocs with [Disqus][1], create an account and a site giving you a
+integrate Material for MkDocs with [Disqus], create an account and a site
-[shortname][4], and add it to `mkdocs.yml`:
+giving you a [shortname], and add it to `mkdocs.yml`:
 ``` yaml
 extra:
  disqus: <shortname>
 ```
-This will insert a comment system on _every page, except the index page_.
+This will insert a comment system on every page, except the index page.
-  [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/integrations/disqus.html
+  [Disqus support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0
-  [3]: https://www.mkdocs.org/user-guide/configuration/#site_url
+  [site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
-  [4]: https://help.disqus.com/en/articles/1717111-what-s-a-shortname
+  [shortname]: https://help.disqus.com/en/articles/1717111-what-s-a-shortname
 ## Customization
 ### Selective integration
-[:octicons-file-code-24: Source][2] ·
+When [Metadata] is enabled, Disqus can be enabled or disabled for a document
-:octicons-note-24: Metadata ·
+with custom front matter. Add the following lines at the top of a Markdown file:
 :octicons-mortar-board-24: Difficulty: _easy_
-If the [Metadata][5] extension is enabled, you can disable or enable Disqus for
+=== ":octicons-check-circle-fill-16: Enabled"
 specific pages by adding the following to the front matter of a page:
 === "Enable Disqus"
    ``` bash
    ---
@ -55,7 +51,7 @@ specific pages by adding the following to the front matter of a page:
    ...
    ```
-=== "Disable Disqus"
+=== ":octicons-skip-16: Disabled"
    ``` bash
    ---
@ -66,15 +62,13 @@ specific pages by adding the following to the front matter of a page:
    ...
    ```
-  [5]: ../../reference/meta-tags/#metadata
+  [Metadata]: extensions/python-markdown.md#metadata
 ### Other comment systems
 [:octicons-file-code-24: Source][6] ·
 :octicons-mortar-board-24: Difficulty: _easy_
 In order to integrate another JavaScript-based comment system provider, you can
-[extend the theme][7] and [override the `disqus` block][8]:
+[extend the theme], create a new `main.html` in `overrides` and [override the
 `disqus` block][overriding blocks]:
 ``` html
 {% extends "base.html" %}
@ -84,6 +78,5 @@ In order to integrate another JavaScript-based comment system provider, you can
 {% endblock %}
 ```
-  [6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
+  [extend the theme]: ../customization.md#extending-the-theme
-  [7]: ../customization.md#extending-the-theme
+  [overriding blocks]: ../customization.md#overriding-blocks
  [8]: ../customization.md#overriding-blocks-recommended
--- a/docs/setup/adding-a-git-repository.md
+++ b/docs/setup/adding-a-git-repository.md
@ -11,9 +11,14 @@ documents can be linked to specific source files.
 ## Configuration
 ### Repository
 [:octicons-tag-24: 0.1.0][repo_url support] ·
 :octicons-milestone-24: Default: _none_
 In order to display a link to the repository of your project as part of your
-documentation, set [`repo_url`][1] in `mkdocs.yml` to the public URL of your
+documentation, set [`repo_url`][repo_url] in `mkdocs.yml` to the public URL of
-repository, e.g.:
+your repository, e.g.:
 ``` yaml
 repo_url: https://github.com/squidfunk/mkdocs-material
@ -21,35 +26,38 @@ repo_url: https://github.com/squidfunk/mkdocs-material
 The link to the repository will be rendered next to the search bar on big
 screens and as part of the main navigation drawer on smaller screen sizes.
-Additionally, for GitHub and GitLab, the number of stars and forks is
+Additionally, for public repositories hosted on [GitHub] or [GitLab], the
-automatically requested and rendered for _public repositories_.
+number of stars and forks is automatically requested and rendered.
-  [1]: https://www.mkdocs.org/user-guide/configuration/#repo_url
+  [repo_url support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
  [repo_url]: https://www.mkdocs.org/user-guide/configuration/#repo_url
 ### Repository name
-[:octicons-file-code-24: Source][2] · :octicons-milestone-24: Default:
+[:octicons-tag-24: 0.1.0][repo_name support] ·
-_automatically set to_ `GitHub`, `GitLab` _or_ `Bitbucket`
+:octicons-milestone-24: Default: _automatically set to_ `GitHub`, `GitLab` _or_
 `Bitbucket`
 MkDocs will infer the source provider by examining the URL and try to set the
 _repository name_ automatically. If you wish to customize the name, set
-[`repo_name`][3] in `mkdocs.yml`:
+[`repo_name`][repo_name] in `mkdocs.yml`:
 ``` yaml
 repo_name: squidfunk/mkdocs-material
 ```
-  [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/source.html
+  [repo_name support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
-  [3]: https://www.mkdocs.org/user-guide/configuration/#repo_name
+  [repo_name]: https://www.mkdocs.org/user-guide/configuration/#repo_name
 ### Repository icon
-[:octicons-file-code-24: Source][2] · :octicons-milestone-24: Default:
+[:octicons-tag-24: 5.0.0][icon.repo support] ·
-`fontawesome/brands/git-alt`
+:octicons-milestone-24: Default:
 [`fontawesome/brands/git-alt`][icon.repo default]
-While the default _repository icon_ is a generic git icon, it can be set to
+While the default repository icon is a generic git icon, it can be set to
-[any icon bundled with the theme][4] by referencing a valid icon path in
+[any icon bundled with the theme][custom icons] by referencing a valid icon
-`mkdocs.yml`:
+path in `mkdocs.yml`:
 ``` yaml
 theme:
@ -70,16 +78,18 @@ Some popular choices:
 - :fontawesome-brands-bitbucket: – `fontawesome/brands/bitbucket`
 - :fontawesome-solid-trash: – `fontawesome/solid/trash`
-  [4]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
+  [icon.repo support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
  [icon.repo default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/.icons/fontawesome/brands/git-alt.svg
  [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
 ### Edit button
-[:octicons-file-code-24: Source][5] · :octicons-milestone-24: Default:
+[:octicons-tag-24: 0.1.0][edit_uri support] ·
-_automatically set_
+:octicons-milestone-24: Default: _automatically set_
-If the repository URL points to a [GitHub][6], [GitLab][7] or [Bitbucket][8]
+If the repository URL points to a [GitHub], [GitLab] or [Bitbucket] repository,
-repository, an _edit button_ is displayed at the top of each document. This
+an edit button is displayed at the top of each document. This behavior can be
-behavior can be changed by setting [`edit_uri`][9] in `mkdocs.yml`:
+changed by setting [`edit_uri`][edit_uri] in `mkdocs.yml`:
 === "Customize edit path"
@ -93,39 +103,39 @@ behavior can be changed by setting [`edit_uri`][9] in `mkdocs.yml`:
    edit_uri: ""
    ```
-  [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
+  [edit_uri support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
-  [6]: https://github.com/
+  [edit_uri]: https://www.mkdocs.org/user-guide/configuration/#edit_uri
-  [7]: https://about.gitlab.com/
+  [GitHub]: https://github.com/
-  [8]: https://bitbucket.org/
+  [GitLab]: https://about.gitlab.com/
-  [9]: https://www.mkdocs.org/user-guide/configuration/#edit_uri
+  [Bitbucket]: https://bitbucket.org/
 ### Revision date
-[:octicons-file-code-24: Source][10] ·
+[:octicons-tag-24: 4.6.0][git-revision-date support] ·
-[:octicons-cpu-24: Plugin][11]
+[:octicons-cpu-24: Plugin][git-revision-date]
-The [git-revision-date][10] plugin adds support for displaying the date a
+The [git-revision-date] plugin adds support for displaying the date a
-document was _last updated_ at the bottom of each page. It can be installed
+document was last updated at the bottom of each page. It can be installed
 with `pip`:
 ```
 pip install mkdocs-git-revision-date-plugin
 ```
-Then, add the following to `mkdocs.yml`:
+Then, add the following lines to `mkdocs.yml`:
 ``` yaml
 plugins:
  - git-revision-date
 ```
-The following options are supported:
+The following configuration options are supported:
-`enabled_if_env`{ #enabled_if_env }
+`enabled_if_env`{ #enabled-if-env }
-:   :octicons-milestone-24: Default: _none_ – When specified the data will only be extracted from git
+:   :octicons-milestone-24: Default: _none_ – When specified, the plugin will
-    if the environment variable exists. This makes it possible to disable
+    only be invoked if the environment variable exists. This makes it easy to
-    extraction for cases when the repository is not available:
+    disable extraction for cases when the repository is not available:
    ``` yaml
    plugins:
@ -133,21 +143,21 @@ The following options are supported:
          enabled_if_env: CI
    ```
-_Material for MkDocs doesn't provide official support for the other options of
+The other configuration options of this extension are not officially supported
-this plugin, so they may be supported but might yield unexpected results.
+by Material for MkDocs, which is why they may yield unexpected results. Use
-Use them at your own risk._
+them at your own risk.
-  [10]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/source-date.html
+  [git-revision-date support]: https://github.com/squidfunk/mkdocs-material/releases/tag/4.6.0
-  [11]: https://github.com/zhaoterryy/mkdocs-git-revision-date-plugin
+  [git-revision-date]: https://github.com/zhaoterryy/mkdocs-git-revision-date-plugin
 ### Revision date, localized
-[:octicons-file-code-24: Source][10] ·
+[:octicons-tag-24: 4.6.0][git-revision-date-localized support] ·
-[:octicons-cpu-24: Plugin][12]
+[:octicons-cpu-24: Plugin][git-revision-date-localized]
-Similarly, the [git-revision-date-localized][12] plugin adds support for adding
+Similarly, the [git-revision-date-localized] plugin adds support for adding
-a localized _updated at_ and _created at_ date at the bottom of each page. It
+a localized update and creation date at the bottom of each page. It can be
-can be installed with `pip`:
+installed with `pip`:
 ```
 pip install mkdocs-git-revision-date-localized-plugin
@ -160,7 +170,7 @@ plugins:
  - git-revision-date-localized
 ```
-The following options are supported:
+The following configuration options are supported:
 `type`{ #type }
@ -174,11 +184,11 @@ The following options are supported:
          type: date
    ```
-`fallback_to_build_date`{ #fallback_to_build_date }
+`fallback_to_build_date`{ #fallback-to-build-date }
 :   :octicons-milestone-24: Default: `false` – Enables falling back to
    the time when `mkdocs build` was executed. Can be used as a fallback when
-    the build is performed outside of the git repository:
+    the build is performed outside of a git repository:
    ``` yaml
    plugins:
@ -186,11 +196,11 @@ The following options are supported:
          fallback_to_build_date: true
    ```
-`enable_creation_date`{ #enable_creation_date }
+`enable_creation_date`{ #enable-creation-date }
 :   :octicons-milestone-24: Default: `false` – Enables the display of the
-    _created at_ date of the file associated with the page next to the
+    creation date of the file associated with the page next to the last updated
-    _updated at_ date at the bottom of the page:
+    date at the bottom of the page:
    ``` yaml
    plugins:
@ -199,8 +209,9 @@ The following options are supported:
    ```
-_Material for MkDocs doesn't provide official support for the other options of
+The other configuration options of this extension are not officially supported
-this plugin, so they may be supported but might yield unexpected results.
+by Material for MkDocs, which is why they may yield unexpected results. Use
-Use them at your own risk._
+them at your own risk.
-  [12]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
+  [git-revision-date-localized support]: https://github.com/squidfunk/mkdocs-material/releases/tag/4.6.0
  [git-revision-date-localized]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
--- a/docs/setup/changing-the-colors.md
+++ b/docs/setup/changing-the-colors.md
@ -5,12 +5,12 @@ template: overrides/main.html
 # Changing the colors
 As any proper Material Design implementation, Material for MkDocs supports
-Google's original [color palette][1], which can be easily configured through 
+Google's original [color palette], which can be easily configured through 
 `mkdocs.yml`. Furthermore, colors can be customized with a few lines of CSS to
-fit your brand's identity by using [CSS variables][2].
+fit your brand's identity by using [CSS variables][custom colors].
-  [1]: http://www.materialui.co/colors
+  [color palette]: http://www.materialui.co/colors
-  [2]: #custom-colors
+  [custom colors]: #custom-colors
 ## Configuration
@ -18,9 +18,10 @@ fit your brand's identity by using [CSS variables][2].
 #### Color scheme
-[:octicons-file-code-24: Source][3] · :octicons-milestone-24: Default: `default`
+[:octicons-tag-24: 5.2.0][palette.scheme support] ·
 :octicons-milestone-24: Default: `default`
-Material for MkDocs supports two _color schemes_: a light mode, which is just
+Material for MkDocs supports two color schemes: a light mode, which is just
 called `default`, and a dark mode, which is called `slate`. The color scheme
 can be set via `mkdocs.yml`:
@ -30,7 +31,7 @@ theme:
    scheme: default
 ```
-_Click on a tile to change the color scheme_:
+Click on a tile to change the color scheme:
 <div class="mdx-switch">
  <button data-md-color-scheme="default"><code>default</code></button>
@ -49,13 +50,14 @@ _Click on a tile to change the color scheme_:
  })
 </script>
-  [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_scheme.scss
+  [palette.scheme support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.0
 #### Primary color
-[:octicons-file-code-24: Source][4] · :octicons-milestone-24: Default: `indigo`
+[:octicons-tag-24: 0.2.0][palette.primary support] ·
 :octicons-milestone-24: Default: `indigo`
-The _primary color_ is used for the header, the sidebar, text links and several
+The primary color is used for the header, the sidebar, text links and several
 other components. In order to change the primary color, set the following value
 in `mkdocs.yml` to a valid color name:
@ -65,7 +67,7 @@ theme:
    primary: indigo
 ```
-_Click on a tile to change the primary color_:
+Click on a tile to change the primary color:
 <div class="mdx-switch">
  <button data-md-color-primary="red"><code>red</code></button>
@ -103,13 +105,14 @@ _Click on a tile to change the primary color_:
  })
 </script>
-  [4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_primary.scss
+  [palette.primary support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0
 #### Accent color
-[:octicons-file-code-24: Source][5] · :octicons-milestone-24: Default: `indigo`
+[:octicons-tag-24: 0.2.0][palette.accent support] ·
 :octicons-milestone-24: Default: `indigo`
-The _accent color_ is used to denote elements that can be interacted with, e.g.
+The accent color is used to denote elements that can be interacted with, e.g.
 hovered links, buttons and scrollbars. It can be changed in `mkdocs.yml` by
 choosing a valid color name:
@ -119,7 +122,7 @@ theme:
    accent: indigo
 ```
-_Click on a tile to change the accent color_:
+Click on a tile to change the accent color:
 <style>
  .md-typeset button[data-md-color-accent] > code {
@ -159,36 +162,45 @@ _Click on a tile to change the accent color_:
  })
 </script>
-  [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_accent.scss
+  [palette.accent support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0
 ### Color palette toggle
-[:octicons-file-code-24: Source][6] · :octicons-milestone-24: Default: _none_
+[:octicons-tag-24: 7.1.0][palette.toggle support] ·
 :octicons-milestone-24: Default: _none_
 It's also possible to offer a list of color palettes to the user, each of which
-can include a [`scheme`][7], [`primary`][8] and [`accent`][9] color each. The
+can include a [`scheme`][palette.scheme], [`primary`][palette.primary] and
-user can toggle between those color palettes:
+[`accent`][palette.accent] color each. The user can toggle between those color
 palettes:
-``` yaml hl_lines="4-6 8-10"
+``` yaml
 theme:
-  palette:
+  palette: # (1)
    - scheme: default
      toggle:
        icon: material/toggle-switch-off-outline
        name: Switch to dark mode
-    - scheme: slate
+    - scheme: slate # (2)
      toggle:
        icon: material/toggle-switch
        name: Switch to light mode
 ```
-The following fields must be set for each toggle:
+1.  Note that the `theme.palette` setting is now defined as a list.
 2.  With __2__ (color schemes) __x 21__ (primary colors) __x 17__ (accent color)
    = __714__ combinations, it's impossible to ensure that all configurations
    provide a good user experience (e.g. _yellow on light background_). Make
    sure that the color combination of your choosing provides enough contrast
    and tweak CSS variables where necessary.
-`icon`{ #icon }
+The following properties must be set for each toggle:
 `icon`{ #toggle-icon }
 :   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
    This field must point to a valid icon path referencing [any icon bundled
-    with the theme][10], or the build will not succeed. Some popular
+    with the theme][custom icons], or the build will not succeed. Some popular
    combinations:
    * :material-toggle-switch-off-outline: + :material-toggle-switch: – `material/toggle-switch-off-outline` + `material/toggle-switch`
@ -196,102 +208,116 @@ The following fields must be set for each toggle:
    * :material-eye-outline: + :material-eye: – `material/eye-outline` + `material/eye`
    * :material-lightbulb-outline: + :material-lightbulb: – `material/lightbulb-outline` + `material/lightbulb`
-`name`{ #name }
+`name`{ #toggle-name }
 :   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
    This field is used as the toggle's `title` attribute and should be set to a
-    discernable name to improve accessibility.
+    discernable name to improve accessibility. It will appear on mouse hover.
-  [6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/header.html
+  [palette.toggle support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
-  [7]: #color-scheme
+  [palette.scheme]: #color-scheme
-  [8]: #primary-color
+  [palette.primary]: #primary-color
-  [9]: #accent-color
+  [palette.accent]: #accent-color
-  [10]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
+  [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
 ### System preference
-[:octicons-file-code-24: Source][6] · :octicons-milestone-24: Default: _none_
+[:octicons-tag-24: 7.1.0][palette.media support] ·
 :octicons-milestone-24: Default: _none_
 In order to automatically set the color palette to the user's system preference,
 a media query can be set as part of the `media` field next to the toggle
 definition in `mkdocs.yml`:
-``` yaml hl_lines="3 8"
+``` yaml
 theme:
  palette:
-    - media: "(prefers-color-scheme: light)"
+    - media: "(prefers-color-scheme: light)" # (1)
      scheme: default
      toggle:
        icon: material/toggle-switch-off-outline
        name: Switch to dark mode
-    - media: "(prefers-color-scheme: dark)"
+    - media: "(prefers-color-scheme: dark)" # (2)
      scheme: slate
      toggle:
        icon: material/toggle-switch
        name: Switch to light mode
 ```
 1.  This media query is __checked first__. It's also the __fallback__ when no
    media query matches.
 2.  This media query is __checked second__. If it doesn't match, the first one
    is automatically used.
 When the user first visits your site, the media queries are evaluated in the
 order of their definition. The first media query that matches selects the
 default color palette.
-!!! warning "Accessibility – not all color combinations work well"
+  [palette.media support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
    With __2__ (color schemes) __x 21__ (primary colors) __x 17__ (accent color)
    = __714__ combinations, it's impossible to ensure that all configurations
    provide a good user experience (e.g. _yellow on light background_). Make
    sure that the color combination of your choosing provides enough contrast
    and tweak CSS variables where necessary.
 ## Customization
 ### Custom colors
-[:octicons-file-code-24: Source][11] ·
+Material for MkDocs implements colors using [CSS variables] (custom
 :octicons-mortar-board-24: Difficulty: _easy_
 Material for MkDocs implements colors using [CSS variables][12] (custom
 properties). If you want to customize the colors beyond the palette (e.g. to
-use your brand-specific colors), you can add an [additional stylesheet][13] and
+use your brand-specific colors), you can add an [additional style sheet] and
 tweak the values of the CSS variables.
 Let's say you're :fontawesome-brands-youtube:{ style="color: #EE0F0F" }
 __YouTube__, and want to set the primary color to your brand's palette. Just
 add:
-``` css
+=== ":octicons-file-code-16: docs/stylesheets/extra.css"
 :root {
  --md-primary-fg-color:        #EE0F0F;
  --md-primary-fg-color--light: #ECB7B7;
  --md-primary-fg-color--dark:  #90030C;
 }
 ```
-See the file containing the [color definitions][11] for a list of all CSS
+    ``` css
-variables.
+    :root {
      --md-primary-fg-color:        #EE0F0F;
      --md-primary-fg-color--light: #ECB7B7;
      --md-primary-fg-color--dark:  #90030C;
    }
    ```
-  [11]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
+=== ":octicons-file-code-16: mkdocs.yml"
-  [12]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
+
-  [13]: ../customization.md#additional-css
+    ``` yaml
    extra_css:
      - stylesheets/extra.css
    ```
 See the file containing the [color definitions] for a list of all CSS variables.
  [CSS variables]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
  [color definitions]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
  [additional style sheet]: ../customization.md#additional-css
 ### Custom color schemes
 [:octicons-file-code-24: Source][11] ·
 :octicons-mortar-board-24: Difficulty: _easy_
 Besides overriding specific colors, you can create your own, named color scheme
-by wrapping the definitions in the `#!css [data-md-color-scheme="..."]`
+by wrapping the definitions in a `[data-md-color-scheme="..."]`
-[attribute selector][14], which you can then set via `mkdocs.yml` as described
+[attribute selector], which you can then set via `mkdocs.yml` as described
-in the [color schemes][7] section:
+in the [color schemes][palette.scheme] section:
-``` css
+=== ":octicons-file-code-16: docs/stylesheets/extra.css"
-[data-md-color-scheme="youtube"] {
+
-  --md-primary-fg-color:        #EE0F0F;
+    ``` css
-  --md-primary-fg-color--light: #ECB7B7;
+    [data-md-color-scheme="youtube"] {
-  --md-primary-fg-color--dark:  #90030C;
+      --md-primary-fg-color:        #EE0F0F;
-}
+      --md-primary-fg-color--light: #ECB7B7;
-```
+      --md-primary-fg-color--dark:  #90030C;
    }
    ```
 === ":octicons-file-code-16: mkdocs.yml"
    ``` yaml
    theme:
      palette:
        scheme: youtube
    extra_css:
      - stylesheets/extra.css
    ```
 Additionally, the `slate` color scheme defines all of it's colors via `hsla`
 color functions and deduces its colors from the `--md-hue` CSS variable. You
@ -299,8 +325,10 @@ can tune the `slate` theme with:
 ``` css
 [data-md-color-scheme="slate"] {
-  --md-hue: 210; /* [0, 360] */
+  --md-hue: 210; /* (1) */
 }
 ```
-  [14]: https://www.w3.org/TR/selectors-4/#attribute-selectors
+1.  The `hue` value must be in the range of `[0, 360]`
  [attribute selector]: https://www.w3.org/TR/selectors-4/#attribute-selectors
--- a/docs/setup/changing-the-fonts.md
+++ b/docs/setup/changing-the-fonts.md
@ -5,22 +5,22 @@ template: overrides/main.html
 # Changing the fonts
 Material for MkDocs makes it easy to change the typeface of your project
-documentation, as it directly integrates with [Google Fonts][1]. Alternatively,
+documentation, as it directly integrates with [Google Fonts]. Alternatively,
 fonts can be custom-loaded if self-hosting is preferred for data privacy reasons
 or another destination should be used.
-  [1]: https://fonts.google.com
+  [Google Fonts]: https://fonts.google.com
 ## Configuration
 ### Regular font
-[:octicons-file-code-24: Source][2] ·
+[:octicons-tag-24: 0.1.2][font support] ·
-:octicons-milestone-24: Default: [`Roboto`][3]
+:octicons-milestone-24: Default: [`Roboto`][Roboto]
-The _regular font_ is used for all body copy, headlines, and essentially
+The regular font is used for all body copy, headlines, and essentially
 everything that does not need to be monospaced. It can be set to any
-valid [Google Font][1] with:
+valid [Google Font][Google Fonts] via `mkdocs.yml`:
 ``` yaml
 theme:
@ -30,17 +30,17 @@ theme:
 The typeface will be loaded in 300, 400, _400i_ and __700__.
-  [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
+  [Roboto]: https://fonts.google.com/specimen/Roboto
-  [3]: https://fonts.google.com/specimen/Roboto
+  [font support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.2
 ### Monospaced font
-[:octicons-file-code-24: Source][2] ·
+[:octicons-tag-24: 0.1.2][font support] ·
-:octicons-milestone-24: Default: [`Roboto Mono`][4]
+:octicons-milestone-24: Default: [`Roboto Mono`][Roboto Mono]
 The _monospaced font_ is used for code blocks and can be configured separately.
-Just like the regular font, it can be set to any valid [Google Font][1] via
+Just like the regular font, it can be set to any valid [Google Font]
-`mkdocs.yml` with:
+[Google Fonts] via `mkdocs.yml`:
 ``` yaml
 theme:
@ -50,55 +50,63 @@ theme:
 The typeface will be loaded in 400.
-  [4]: https://fonts.google.com/specimen/Roboto+Mono
+  [Roboto Mono]: https://fonts.google.com/specimen/Roboto+Mono
-## Customization
+### Autoloading
-If you want to load fonts from other destinations or don't want to use Google
+[:octicons-tag-24: 1.0.0][font=false support] ·
-Fonts for [data privacy][5] reasons, e.g. _due to GDPR_, you may customize
+:octicons-milestone-24: Default: _none_
 font loading as described below.
-### Disabling font loading
+If you want to prevent typefaces from being loaded from [Google Fonts], e.g.
-
+to adhere to [data privacy] regulations, and fall back to system fonts, add the
-[:octicons-file-code-24: Source][2] ·
+following lines to `mkdocs.yml`:
 :octicons-mortar-board-24: Difficulty: _easy_
 If you want to prevent typefaces from being loaded from Google Fonts and fall
 back to system fonts, add the following lines to `mkdocs.yml`:
 ``` yaml
 theme:
  font: false
 ```
  [data privacy]: https://developers.google.com/fonts/faq#what_does_using_the_google_fonts_api_mean_for_the_privacy_of_my_users
  [font=false support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
 ## Customization
 ### Additional fonts
-[:octicons-file-code-24: Source][2] ·
+If you want to load an (additional) font from another destination or override
-:octicons-mortar-board-24: Difficulty: _easy_
+the system font, you can use an [additional style sheet] to add the
 If you want to load an (additional) font from another  or override
 the fallback font, you can use an [additional stylesheet][8] to add the
 corresponding `@font-face` definition:
-``` css
+=== ":octicons-file-code-16: docs/stylesheets/extra.css"
-@font-face {
+
-  font-family: "<font>";
+    ``` css
-  src: "...";
+    @font-face {
-}
+      font-family: "<font>";
-```
+      src: "...";
    }
    ```
 === ":octicons-file-code-16: mkdocs.yml"
    ``` yaml
    extra_css:
      - stylesheets/extra.css
    ```
 The font can then be applied to specific elements, e.g. only headlines, or 
-globally to be used as the site-wide regular or monospaced font (with fallback
+globally to be used as the site-wide regular or monospaced font:
 fonts being added automatically):
 === "Regular font"
    ``` css
    :root {
-      --md-text-font-family: "<font>";
+      --md-text-font-family: "<font>"; /* (1) */
    }
    ```
    1.  Always define fonts through CSS variables and not `font-family`, as
        this would disable the system font fallback.
 === "Monospaced font"
    ``` css
@ -107,7 +115,4 @@ fonts being added automatically):
    }
    ```
-  [5]: ../data-privacy.md
+  [additional style sheet]: ../customization.md#additional-css
  [6]: ../customization.md#extending-the-theme
  [7]: ../customization.md#overriding-blocks-recommended
  [8]: ../customization.md#additional-stylesheets
--- a/docs/setup/changing-the-language.md
+++ b/docs/setup/changing-the-language.md
@ -6,16 +6,17 @@ template: overrides/main.html
 Material for MkDocs supports internationalization (i18n) and provides
 translations for template variables and labels in 40+ languages. Additionally,
-the site search can be configured to use a language-specific stemmer (if
+the site search can be configured to use a language-specific stemmer, if
-available).
+available.
 ## Configuration
 ### Site language
-[:octicons-file-code-24: Source][1] · :octicons-milestone-24: Default: `en`
+[:octicons-tag-24: 1.12.0][language support] ·
 :octicons-milestone-24: Default: `en`
-You can set the _site language_ in `mkdocs.yml` with:
+You can set the site language in `mkdocs.yml` with:
 ``` yaml
 theme:
@ -24,7 +25,7 @@ theme:
 The following languages are supported:
-<div class="mdx-columns" markdown="1">
+<div class="mdx-columns" markdown>
 - `af` – Afrikaans
 - `ar` – Arabic
@ -79,70 +80,72 @@ The following languages are supported:
 </div>
-_Note that some languages will produce unreadable anchor links, due to the way
+Note that some languages will produce unreadable anchor links due to the way
-the default slug function works. Consider using a Unicode-aware slug function,
+the default slug function works. Consider using a [Unicode-aware slug function].
 as [documented here][2]._
-  [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/languages/en.html
+  [language support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.12.0
-  [2]: setting-up-navigation.md#slugify
+  [Unicode-aware slug function]: setting-up-navigation.md#slugify
 ### Site language selector
-[:octicons-file-code-24: Source][3] ·
+[:octicons-tag-24: 7.0.0][alternate support] ·
 :octicons-milestone-24: Default: _none_ ·
 :octicons-beaker-24: Experimental
-If your documentation is available in multiple languages, a _language selector_
+If your documentation is available in multiple languages, a language selector
-can be added to the header next to the search bar. Alternate languages can be
+pointing to those languages can be added to the header. Alternate languages
-defined via `mkdocs.yml`:
+can be defined via `mkdocs.yml`.
 ``` yaml
 extra:
  alternate:
    # Switch to English
    - name: English
-      link: <your-site>/en/
+      link: /en/ # (1)
      lang: en
    # Switch to German
    - name: Deutsch
-      link: <your-site>/de/
+      link: /de/
      lang: de
    # Switch to Japanese
    - name: 日本語
      link: <your-site>/ja/
      lang: ja
 ```
-This will render a language selector in the header next to the search bar:
+1.  Note that this must be an absolute link. If it includes a domain part, it's
    used as defined. Otherwise the domain part of the [`site_url`][site_url] as
    set in `mkdocs.yml` is prepended to the link.
-[![Language selection][4]][4]
+The following properties must be set for each alternate language:
-  [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/header.html
+`name`{ #language-name }
  [4]: ../assets/screenshots/language-selection.png
-### Site search language
+:   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
    This field is used inside the language selector as the name of the language
    and must be set to a non-empty string.
-[:octicons-file-code-24: Source][5] ·
+`link`{ #language-link }
 :octicons-milestone-24: Default: _automatically set_
-Some languages, like Arabic or Japanese, need dedicated stemmers for search to
+:   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
-work properly. Material for MkDocs relies on [lunr-languages][6] to provide this
+    This field must be set to an absolute link, which might also point to
-functionality. See the guide detailing how to [set up site search][7] for
+    another domain or subdomain not necessarily generated with MkDocs.
 more information.
-  [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/main/index.ts
+`lang`{ #language-lang }
-  [6]: https://github.com/MihaiValentin/lunr-languages
+
-  [7]: setting-up-site-search.md
+:   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
    This field must contain a valid [ISO 639-1 language code] and is used for
    the `hreflang` attribute of the link, improving discoverability via search
    engines.
 [![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 preview]: ../assets/screenshots/language-selection.png
 ### Directionality
-[:octicons-file-code-24: Source][8] ·
+[:octicons-tag-24: 2.5.0][direction support] ·
 :octicons-milestone-24: Default: _automatically set_
 While many languages are read `ltr` (left-to-right), Material for MkDocs also
-supports `rtl` (right-to-left) _directionality_ which is inferred from the
+supports `rtl` (right-to-left) directionality which is deduced from the
 selected language, but can also be set with:
 ``` yaml
@ -163,44 +166,54 @@ Click on a tile to change the directionality:
    button.addEventListener("click", function() {
      var attr = this.getAttribute("data-md-dir")
      document.body.dir = attr
-      var name = document.querySelector("#__code_1 code span:nth-child(5)")
+      var name = document.querySelector("#__code_3 code span:nth-child(5)")
      name.textContent = attr
    })
  })
 </script>
-  [8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
+  [direction support]: https://github.com/squidfunk/mkdocs-material/releases/tag/2.5.0
 ## Customization
 ### Custom translations
 [:octicons-file-code-24: Source][1] ·
 :octicons-mortar-board-24: Difficulty: _easy_
 If you want to customize some of the translations for a language, just follow
-the guide on [theme extension][9] and create a new partial in
+the guide on [theme extension] and create a new partial in the `overrides`
-`partials/languages`, e.g. `en-custom.html`. Next, look up the translation you
+folder. Then, import the [translations] of the language as a fallback and only
-want to change in the [base translation][1] and add it to the partial.
+adjust the ones you want to override:
-Let's say you want to change "__Table of contents__" to "__On this page__":
+=== ":octicons-file-code-16: partials/languages/custom.html"
-``` html
+    ``` html
-<!-- Use en language as fallback -->
+    <!-- Import translations for language and fallback -->
-{% import "partials/languages/en.html" as fallback %}
+    {% import "partials/languages/de.html" as language %}
-{% macro override(key) %}{{ {
+    {% import "partials/languages/en.html" as fallback %} <!-- (1) -->
  "toc.title": "On this page"
 }[key] }}{% endmacro %}
-<!-- Re-export the translation macro for mkbuild-material to use -->
+    <!-- Define custom translations -->
-{% macro t(key) %}{{ override(key) or fallback.t(key) }}{% endmacro %}
+    {% macro override(key) %}{{ {
-```
+      "toc.title": "Auf dieser Seite" <!-- (2) -->
    }[key] }}{% endmacro %}
-Then, add the following lines to `mkdocs.yml`:
+    <!-- Re-export translations -->
    {% macro t(key) %}{{
      override(key) or language(key) or fallback.t(key)
    }}{% endmacro %}
    ```
-``` yaml
+    1.  Note that `en` must always be used as a fallback language, as it's the
-theme:
+        default theme language.
  language: en-custom
 ```
-  [9]: ../customization.md#extending-the-theme
+    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"
    ``` yaml
    theme:
      language: custom
    ```
  [theme extension]: ../customization.md#extending-the-theme
  [translations]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/languages/
  [list of available languages]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/languages/
--- a/docs/setup/changing-the-logo-and-icons.md
+++ b/docs/setup/changing-the-logo-and-icons.md
@ -4,32 +4,32 @@ template: overrides/main.html
 # Changing the logo and icons
-When installing Material for MkDocs, you immediately get access to _over 7.000 
+When installing Material for MkDocs, you immediately get access to _over 8.000 
 icons_ ready to be used for customization of specific parts of the theme and/or 
-when writing your documentation in Markdown. Not enough? You can also [add
+when writing your documentation in Markdown. Not enough? You can also add
-additional icons][1] with minimal effort.
+[additional icons] with minimal effort.
-  [1]: #additional-icons
+  [additional icons]: #additional-icons
 ## Configuration
 ### Logo
-[:octicons-file-code-24: Source][2] ·
+[:octicons-tag-24: 0.1.0][logo support] ·
-:octicons-milestone-24: Default: [`material/library`][3]
+:octicons-milestone-24: Default: [`material/library`][logo default]
-The _logo_ can be changed to a user-provided image (any type, incl. `*.png` and
+The logo can be changed to a user-provided image (any type, incl. `*.png` and
 `*.svg`) located in the `docs` folder, or to any icon bundled with the theme.
 Add the following lines to `mkdocs.yml`:
-=== "Image"
+=== ":octicons-image-16: Image"
    ``` yaml
    theme:
      logo: assets/logo.png
    ```
-=== "Icon, bundled"
+=== ":octicons-package-16: Icon, bundled"
    ``` yaml
    theme:
@ -37,9 +37,8 @@ Add the following lines to `mkdocs.yml`:
        logo: material/library
    ```
-  [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/logo.html
+  [logo support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
-  [3]: https://github.com/squidfunk/mkdocs-material/blob/master/material/.icons/material/library.svg
+  [logo default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/.icons/material/library.svg
  [4]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
 Normally, the logo in the header and sidebar links to the homepage of the
 documentation, which is the same as `site_url`. This behavior can be changed
@ -52,60 +51,28 @@ extra:
 ### Favicon
-[:octicons-file-code-24: Source][5] ·
+[:octicons-tag-24: 0.1.0][favicon support] ·
-:octicons-milestone-24: Default: `assets/images/favicon.png`
+:octicons-milestone-24: Default: [`assets/images/favicon.png`][favicon default]
-The _favicon_ can be changed to a path pointing to a user-provided image, which 
+The favicon can be changed to a path pointing to a user-provided image, which 
-must be located in the `docs` folder. It can be set via `mkdocs.yml`:
+must be located in the `docs` folder. Add the following lines to `mkdocs.yml`:
 ``` yaml
 theme:
  favicon: images/favicon.png
 ```
-  [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
+  [favicon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
-
+  [favicon default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/assets/images/favicon.png
 ### Icons
 [:octicons-file-code-24: Source][4] · [:octicons-workflow-24: Extension][6]
 The [Emoji][6] extension, which is part of [Python Markdown Extensions][7],
 adds the ability to __integrate icons__ in the `*.svg` file format, which are
 inlined when [building your site][8]:
 ``` yaml
 markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
 ```
 The following icon sets are bundled with Material for MkDocs:
 - :material-material-design: – [Material Design][9]
 - :fontawesome-brands-font-awesome-flag: – [FontAwesome][10]
 - :octicons-mark-github-16: – [Octicons][11]
 If you want to add [additional icons][1], read on.
  [6]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
  [7]: https://facelessuser.github.io/pymdown-extensions/
  [8]: ../creating-your-site.md#building-your-site
  [9]: https://materialdesignicons.com/
  [10]: https://fontawesome.com/icons?d=gallery&m=free
  [11]: https://octicons.github.com/
 ## Customization
 ### Additional icons
-[:octicons-file-code-24: Source][4] · 
+In order to use custom icons, [extend the theme] and create a new folder named
-:octicons-mortar-board-24: Difficulty: _easy_
+`.icons` in the [`custom_dir`][custom_dir] you want to use for overrides.
-
+Next, add your `*.svg` icons into a subfolder of the `.icons` folder. Let's say
-In order to add additional icons, [extend the theme][12], and create a folder
+you  downloaded and unpacked the [Bootstrap] icon set, and want to add it to
 named `.icons` in the [`custom_dir`][13] you want to use for overrides. Next,
 add your `*.svg` icons into a subfolder of the `.icons` folder. Let's say you 
 downloaded and unpacked the [Bootstrap][14] icon set, and want to add it to
 your project documentation. The structure of your project should look like this:
 ``` sh
@ -129,9 +96,8 @@ markdown_extensions:
          - overrides/.icons
 ```
-You should now be able to use the :fontawesome-brands-bootstrap: Bootstrap
+You can now use all :fontawesome-brands-bootstrap: Bootstrap icons.
 icons.
-  [12]: ../customization.md#extending-the-theme
+  [extend the theme]: ../customization.md#extending-the-theme
-  [13]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
+  [custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
-  [14]: https://icons.getbootstrap.com/
+  [Bootstrap]: https://icons.getbootstrap.com/
--- a/docs/setup/extensions/index.md
+++ b/docs/setup/extensions/index.md
@ -0,0 +1,142 @@
 ---
 template: overrides/main.html
 title: Extensions
 ---
 # Extensions
 Markdown is a very small language with a kind-of reference implementation called
 [John Gruber's Markdown]. [Python Markdown] and [Python Markdown Extensions]
 are two packages that enhance the Markdown writing experience, adding useful
 syntax extensions for technical writing.
  [John Gruber's Markdown]: https://daringfireball.net/projects/markdown/
  [Python Markdown]: python-markdown.md
  [Python Markdown Extensions]: python-markdown-extensions.md
 ## 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
 configuration:
 <div class="mdx-columns" markdown>
 - [Abbreviations]
 - [Admonition]
 - [Arithmatex]
 - [Attribute Lists]
 - [BetterEm]
 - [Caret, Mark & Tilde]
 - [Critic]
 - [Definition Lists]
 - [Details]
 - [Emoji]
 - [Footnotes]
 - [Highlight]
 - [Keys]
 - [Metadata]
 - [Markdown in HTML]
 - [SmartSymbols]
 - [Snippets]
 - [SuperFences]
 - [Tabbed]
 - [Table of Contents]
 - [Tables]
 - [Tasklist]
 </div>
  [Abbreviations]: python-markdown.md#abbreviations
  [Admonition]: python-markdown.md#admonition
  [Arithmatex]: python-markdown-extensions.md#arithmatex
  [Attribute Lists]: python-markdown.md#attribute-lists
  [BetterEm]: python-markdown-extensions.md#betterem
  [Caret, Mark & Tilde]: python-markdown-extensions.md#caret-mark-tilde
  [Critic]: python-markdown-extensions.md#critic
  [Definition Lists]: python-markdown.md#definition-lists
  [Details]: python-markdown-extensions.md#details
  [Emoji]: python-markdown-extensions.md#emoji
  [Footnotes]: python-markdown.md#footnotes
  [Highlight]: python-markdown-extensions.md#highlight
  [Keys]: python-markdown-extensions.md#keys
  [Metadata]: python-markdown.md#metadata
  [Markdown in HTML]: python-markdown.md#markdown-in-html
  [SmartSymbols]: python-markdown-extensions.md#smartsymbols
  [Snippets]: python-markdown-extensions.md#snippets
  [SuperFences]: python-markdown-extensions.md#superfences
  [Tabbed]: python-markdown-extensions.md#tabbed
  [Table of Contents]: python-markdown.md#table-of-contents
  [Tables]: python-markdown.md#tables
  [Tasklist]: python-markdown-extensions.md#tasklist
 ## Configuration
 Extensions are configured as part of `mkdocs.yml` – the MkDocs configuration
 file. The following sections contain two example configurations to bootstrap
 your documentation project.
  [overview]: #advanced-configuration
 ### Minimal configuration
 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:
  # Python Markdown
  - meta
  - toc:
      permalink: true
  # Python Markdown Extensions
  - pymdownx.highlight
  - pymdownx.superfences
 ```
  [reference]: ../../reference/abbreviations.md
 ### Recommended configuration
 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:
  # Python Markdown
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - meta
  - md_in_html
  - toc:
      permalink: true
  # Python Markdown Extensions
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
  - pymdownx.highlight
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde
 ```
--- a/docs/setup/extensions/python-markdown-extensions.md
+++ b/docs/setup/extensions/python-markdown-extensions.md
@ -0,0 +1,691 @@
 ---
 template: overrides/main.html
 ---
 # Python Markdown Extensions
 The [Python Markdown Extensions] package is an excellent collection of
 additional extensions perfectly suited for advanced technical writing. Material
 for MkDocs lists this package as an explicit dependency, so it's automatically
 installed with a supported version.
  [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
 ## Supported extensions
 ### Arithmatex
 [:octicons-tag-24: 1.0.0][Arithmatex support] ·
 [:octicons-workflow-24: Extension][Arithmatex]
 The [Arithmatex] extension allows for rendering of block and inline block
 equations and integrates seamlessly with [MathJax][^1] – a library for
 mathematical typesetting. Enable it via `mkdocs.yml`:
  [^1]:
    Other libraries like [KaTeX] are also supported and can be integrated with
    some additional effort. See the [Arithmatex documentation on KaTeX] for
    further guidance, as this is beyond the scope of Material for MkDocs.
 ``` yaml
 markdown_extensions:
  - pymdownx.arithmatex:
      generic: true
 ```
 Besides enabling the extension in `mkdocs.yml`, a MathJax configuration and 
 the JavaScript runtime need to be included, which can be done with a few lines
 of [additional JavaScript]:
 === ":octicons-file-code-16: docs/javascripts/mathjax.js"
    ``` js
    window.MathJax = {
      tex: {
        inlineMath: [["\\(", "\\)"]],
        displayMath: [["\\[", "\\]"]],
        processEscapes: true,
        processEnvironments: true
      },
      options: {
        ignoreHtmlClass: ".*|",
        processHtmlClass: "arithmatex"
      }
    };
    document$.subscribe(() => {
      MathJax.typesetPromise()
    })
    ```
 === ":octicons-file-code-16: mkdocs.yml"
    ``` yaml
    extra_javascript:
      - javascripts/mathjax.js
      - https://polyfill.io/v3/polyfill.min.js?features=es6
      - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
    ```
 The other configuration options of this extension are not officially supported
 by Material for MkDocs, which is why they may yield unexpected results. Use
 them at your own risk.
 See reference for usage:
 - [Using block syntax]
 - [Using inline block syntax]
  [Arithmatex]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
  [Arithmatex support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
  [Arithmatex documentation on KaTeX]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/#loading-katex
  [MathJax]: https://www.mathjax.org/
  [KaTeX]: https://github.com/Khan/KaTeX
  [additional JavaScript]: ../../customization.md#additional-javascript
  [Using block syntax]: ../../reference/mathjax.md#using-block-syntax
  [Using inline block syntax]: ../../reference/mathjax.md#using-inline-block-syntax
 ### BetterEm
 [:octicons-tag-24: 0.1.0][BetterEm support] ·
 [:octicons-workflow-24: Extension][BetterEm]
 The [BetterEm] extension improves the detection of Markup to emphasize text
 in Markdown using special characters, i.e. for `**bold**` and `_italic_`
 formatting. Enable it via `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - pymdownx.betterem
 ```
 The configuration options of this extension are not specific to Material for
 MkDocs, as they only impact the Markdown parsing stage. See the [BetterEm 
 documentation][BetterEm] for more information.
  [BetterEm]: https://facelessuser.github.io/pymdown-extensions/extensions/betterem/
  [BetterEm support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
 ### Caret, Mark & Tilde
 [:octicons-tag-24: 1.0.0][Caret support] ·
 [:octicons-workflow-24: Extension][Caret]
 The [Caret], [Mark] and [Tilde] extensions add the ability to highlight text
 and define sub- and superscript using a simple syntax. Enable them together
 via `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - pymdownx.caret
  - pymdownx.mark
  - pymdownx.tilde
 ```
 The configuration options of this extension are not specific to Material for
 MkDocs, as they only impact the Markdown parsing stage. See the [Caret], [Mark]
 and [Tilde documentation][Tilde] for guidance.
 See reference for usage:
 - [Highlighting text]
 - [Sub- and superscripts]
  [Caret]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/
  [Caret support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
  [Mark]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
  [Tilde]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/
  [Highlighting text]: ../../reference/formatting.md#highlighting-text
  [Sub- and superscripts]: ../../reference/formatting.md#sub-and-superscripts
 ### Critic
 [:octicons-tag-24: 1.0.0][Critic support] ·
 [:octicons-workflow-24: Extension][Critic]
 The [Critic] extension allows for the usage of [Critic Markup] to highlight
 added, deleted or updated sections in a document, i.e. for tracking changes in
 Markdown syntax. Enable it via `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - pymdownx.critic
 ```
 The following configuration options are supported:
 `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
    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
        ```
 See reference for usage:
 - [Highlighting changes]
  [Critic]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/
  [Critic support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
  [Critic Markup]: https://github.com/CriticMarkup/CriticMarkup-toolkit
  [Highlighting changes]: ../../reference/formatting.md#highlighting-changes
 ### Details
 [:octicons-tag-24: 1.9.0][Details support] ·
 [:octicons-workflow-24: Extension][Details]
 The [Details] extension supercharges the [Admonition] extension, making the
 resulting _call-outs_ collapsible, allowing them to be opened and closed by the
 user. Enable it via `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - pymdownx.details
 ```
 No configuration options are available. See reference for usage:
 - [Collapsible blocks]
  [Details]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
  [Details support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.9.0
  [Admonition]: python-markdown.md#admonition
  [Collapsible blocks]: ../../reference/admonitions.md#collapsible-blocks
 ### Emoji
 [:octicons-tag-24: 1.0.0][Emoji support] ·
 [:octicons-workflow-24: Extension][Emoji]
 The [Emoji] extension automatically inlines bundled and custom icons and emojis
 in `*.svg` file format into the resulting HTML page. Enable it via `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji # (1)
      emoji_generator: !!python/name:materialx.emoji.to_svg
 ```
 1.  [Python Markdown Extensions] uses the `pymdownx` namespace, but in order to
    support the inlining of icons, the `materialx` namespace must be used, as it
    extends the functionality of `pymdownx`.
 The following configuration options are supported:
 `emoji_index`{ #emoji-index }
 :   :octicons-milestone-24: Default: `emojione` – This option defines which set
    of emojis is used for rendering. Note that the use of `emojione` is not
    recommended due to [restrictions in licensing][Emoji index]:
    ``` yaml
    markdown_extensions:
      - pymdownx.emoji:
          emoji_index: !!python/name:materialx.emoji.twemoji
    ```
 `emoji_generator`{ #emoji-generator }
 :   :octicons-milestone-24: Default: `to_png` – This option defines how the
    resolved emoji or icon shortcode is render. Note that icons can only be
    used together with the `to_svg` configuration:
    ``` yaml
    markdown_extensions:
      - pymdownx.emoji:
          emoji_generator: !!python/name:materialx.emoji.to_svg
    ```
 `options.custom_icons`{ #custom-icons }
 :   :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]:
    ``` yaml
    markdown_extensions:
      - pymdownx.emoji:
          emoji_index: !!python/name:materialx.emoji.twemoji
          emoji_generator: !!python/name:materialx.emoji.to_svg
          options:
            custom_icons:
              - overrides/.icons
    ```
 The other configuration options of this extension are not officially supported
 by Material for MkDocs, which is why they may yield unexpected results. Use
 them at your own risk.
 See reference for usage:
 - [Using emojis]
 - [Using icons]
 - [Using icons in templates]
  [Emoji]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
  [Emoji support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
  [Emoji index]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#default-emoji-indexes
  [icon customization guide]: ../changing-the-logo-and-icons.md#additional-icons
  [Using emojis]: ../../reference/icons-emojis.md#using-emojis
  [Using icons]: ../../reference/icons-emojis.md#using-icons
  [Using icons in templates]: ../../reference/icons-emojis.md#using-icons-in-templates
 ### Highlight
 [:octicons-tag-24: 5.0.0][Highlight support] ·
 [:octicons-workflow-24: Extension][Highlight] ·
 :octicons-zap-24: Supersedes [CodeHilite]
 The [Highlight] extension adds support for syntax highlighting of code blocks
 (with the help of [SuperFences][pymdownx.superfences]) and inline code blocks
 (with the help of [InlineHilite][pymdownx.inlinehilite]). Enable it via
 `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - pymdownx.highlight
  - pymdownx.superfences # (1)
 ```
 1.  [Highlight] is used by the [SuperFences][pymdownx.superfences] extension to
    perform syntax highlighting on code blocks, not the other way round, which
    is why this extension also needs to be enabled.
 The following configuration options are supported:
 `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
    [Pygments] or in the browser with a JavaScript syntax highlighter:
    === "Pygments"
        ``` yaml
        markdown_extensions:
          - pymdownx.highlight:
              use_pygments: true
          - pymdownx.superfences
        ```
    === "JavaScript"
        ``` yaml
        markdown_extensions:
          - pymdownx.highlight:
              use_pygments: false
        ```
        As an example, [Highlight.js], a JavaScript syntax highlighter, can be 
        integrated with some [additional JavaScript] and [CSS][additional CSS]
        in `mkdocs.yml`:
        === ":octicons-file-code-16: docs/javascripts/highlight.js"
            ``` js
            document$.subscribe(() => {
              hljs.highlightAll()
            })
            ```
        === ":octicons-file-code-16: mkdocs.yml"
            ``` yaml
            extra_javascript:
              - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/highlight.min.js
              - javascripts/highlight.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`{ #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
    code blocks, consult the section on [adding line numbers][Adding line
    numbers] in the code block reference, which also contains some tips on
    working with line numbers:
    ``` yaml
    markdown_extensions:
      - pymdownx.highlight:
          linenums: true
    ```
 `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
    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 either `table`
    or `pymdownx-inline` is recommended.
 The other configuration options of this extension are not officially supported
 by Material for MkDocs, which is why they may yield unexpected results. Use
 them at your own risk.
 See reference for usage:
 - [Specifying the language]
 - [Adding line numbers]
 - [Highlighting specific lines]
 - [Custom syntax theme]
  [Highlight]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
  [Highlight support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
  [CodeHilite]: python-markdown.md#codehilite
  [pymdownx.superfences]: #superfences
  [pymdownx.inlinehilite]: #inlinehilite
  [Pygments]: https://pygments.org
  [additional CSS]: ../../customization.md#additional-css
  [Highlight.js]: https://highlightjs.org/
  [Adding line numbers]: ../../reference/code-blocks.md#adding-line-numbers
  [Specifying the language]: ../../reference/code-blocks.md#specifying-the-language
  [Highlighting specific lines]: ../../reference/code-blocks.md#highlighting-specific-lines
  [Custom syntax theme]: ../../reference/code-blocks.md#custom-syntax-theme
 ### InlineHilite
 [:octicons-tag-24: 5.0.0][InlineHilite support] ·
 [:octicons-workflow-24: Extension][InlineHilite]
 The [InlineHilite] extension add support for syntax highlighting of inline code 
 blocks. It's built on top of the [Highlight][pymdownx.highlight] extension, from
 which it sources its configuration. Enable it via `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - pymdownx.highlight
  - pymdownx.inlinehilite
 ```
 The configuration options of this extension are not specific to Material for
 MkDocs, as they only impact the Markdown parsing stage. The only exception is
 the [`css_class`][InlineHilite options] option, which must not be changed. See the 
 [InlineHilite documentation][InlineHilite] for guidance.
 See reference for usage:
 - [Highlighting inline code blocks]
  [InlineHilite]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
  [InlineHilite support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
  [InlineHilite options]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/#options
  [pymdownx.highlight]: #highlight
  [Highlighting inline code blocks]: ../../reference/code-blocks.md#highlighting-inline-code-blocks
 ### Keys
 [:octicons-tag-24: 1.0.0][Keys support] ·
 [:octicons-workflow-24: Extension][Keys]
 The [Keys] extension adds a simple syntax to allow for the rendering of keyboard 
 keys and combinations, e.g. ++ctrl+alt+del++. Enable it via `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - pymdownx.keys
 ```
 The configuration options of this extension are not specific to Material for
 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
 [:octicons-tag-24: 0.1.0][SmartSymbols support] ·
 [:octicons-workflow-24: Extension][SmartSymbols]
 The [SmartSymbols] extension converts some sequences of characters into their 
 corresponding symbols, e.h. copyright symbols or fractions. Enable it via
 `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - pymdownx.smartsymbols
 ```
 The configuration options of this extension are not specific to Material for
 MkDocs, as they only impact the Markdown parsing stage. See the [SmartSymbols 
 documentation][SmartSymbols] for guidance.
  [SmartSymbols]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
  [SmartSymbols support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
 ### Snippets
 [:octicons-tag-24: 0.1.0][Snippets support] ·
 [:octicons-workflow-24: Extension][Snippets]
 The [Snippets] extension adds the ability to embed content from arbitrary files
 into a document, including other documents or source files, by using a simple
 syntax. Enable it via `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - pymdownx.snippets
 ```
 The configuration options of this extension are not specific to Material for
 MkDocs, as they only impact the Markdown parsing stage. See the [Snippets 
 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
 [:octicons-tag-24: 0.1.0][SuperFences support] ·
 [:octicons-workflow-24: Extension][SuperFences] ·
 :octicons-zap-24: Supersedes [Fenced Code Blocks]
 The [SuperFences] extension allows for arbitrary nesting of code and content
 blocks inside each other, including admonitions, tabs, lists and all other
 elements. Enable it via `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - pymdownx.superfences
 ```
 The following configuration options are supported:
 `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]
    diagrams to be interpreted in the browser:
    ``` yaml
    markdown_extensions:
      - pymdownx.superfences:
          custom_fences:
            - name: mermaid
              class: mermaid
              format: !!python/name:pymdownx.superfences.fence_code_format
    ```
    Note that this will primarily prevent syntax highlighting from being
    applied. See the reference on [diagrams] to learn how Mermaid.js is
    integrated with Material for MkDocs.
 The other configuration options of this extension are not officially supported
 by Material for MkDocs, which is why they may yield unexpected results. Use
 them at your own risk.
 See reference for usage:
 - [Using flowcharts]
 - [Using sequence diagrams]
 - [Using state diagrams]
 - [Using class diagrams]
 - [Using entity-relationship diagrams]
  [SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
  [SuperFences support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
  [Fenced Code Blocks]: python-markdown.md#fenced-code-blocks
  [Mermaid.js]: https://mermaid-js.github.io/mermaid/
  [diagrams]: ../../reference/diagrams.md
  [Using flowcharts]: ../../reference/diagrams.md#using-flowcharts
  [Using sequence diagrams]: ../../reference/diagrams.md#using-sequence-diagrams
  [Using state diagrams]: ../../reference/diagrams.md#using-state-diagrams
  [Using class diagrams]: ../../reference/diagrams.md#using-class-diagrams
  [Using entity-relationship diagrams]: ../../reference/diagrams.md#using-entity-relationship-diagrams
 ### Tabbed
 [:octicons-tag-24: 5.0.0][Tabbed support] ·
 [:octicons-workflow-24: Extension][Tabbed]
 The [Tabbed] extension allows the usage of content tabs, a simple way to group
 related content and code blocks under accessible tabs. Enable it via
 `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - pymdownx.tabbed:
      alternate_style: true 
 ```
 The following configuration options are supported:
 `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
    content tabs, which has [better behavior on mobile viewports], and thus
    is strongly recommended:
    ``` yaml
    markdown_extensions:
      - pymdownx.tabbed:
          alternate_style: true 
    ```
 The other configuration options of this extension are not officially supported
 by Material for MkDocs, which is why they may yield unexpected results. Use
 them at your own risk.
 See reference for usage:
 - [Grouping code blocks]
 - [Grouping other content]
 - [Embedded content]
  [Tabbed]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
  [Tabbed support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
  [Tabbed alternate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.1
  [alternate style]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#alternate-style
  [better behavior on mobile viewports]: https://twitter.com/squidfunk/status/1424740370596958214
  [Grouping code blocks]: ../../reference/content-tabs.md#grouping-code-blocks
  [Grouping other content]: ../../reference/content-tabs.md#grouping-other-content
  [Embedded content]: ../../reference/content-tabs.md#embedded-content
 ### Tasklist
 [:octicons-tag-24: 1.0.0][Tasklist support] ·
 [:octicons-workflow-24: Extension][Tasklist]
 The [Tasklist] extension allows for the usage of [GitHub Flavored Markdown]
 inspired [task lists][Tasklist specification], following the same syntactical
 conventions. Enable it via `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - pymdownx.tasklist:
      custom_checkbox: true
 ```
 The following configuration options are supported:
 `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, 
    and is therefore recommended:
    ``` yaml
    markdown_extensions:
      - pymdownx.tasklist:
          custom_checkbox: true
    ```
 `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 
    option is _rather discouraged_ from a user experience perspective:
    ``` yaml
    markdown_extensions:
      - pymdownx.tasklist:
          clickable_checkbox: true
    ```
 The other configuration options of this extension are not officially supported
 by Material for MkDocs, which is why they may yield unexpected results. Use
 them at your own risk.
 See reference for usage:
 - [Using task lists]
  [Tasklist]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/
  [Tasklist support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
  [GitHub Flavored Markdown]: https://github.github.com/gfm/
  [Tasklist specification]: https://github.github.com/gfm/#task-list-items-extension-
  [Using task lists]: ../../reference/lists.md#using-task-lists
--- a/docs/setup/extensions/python-markdown.md
+++ b/docs/setup/extensions/python-markdown.md
@ -0,0 +1,348 @@
 ---
 template: overrides/main.html
 ---
 # Python Markdown
 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 which features they need to be enabled.
  [Python Markdown]: https://python-markdown.github.io/
 ## Supported extensions
 ### Abbreviations
 [:octicons-tag-24: 1.0.0][Abbreviations support] ·
 [:octicons-workflow-24: Extension][Abbreviations]
 The [Abbreviations] extension adds the ability to add a small tooltip to an
 element, by wrapping it with an `abbr` tag. Only plain text (no markup) is
 supported. Enable it via `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - abbr
 ```
 No configuration options are available. See reference for usage:
 - [Adding abbreviations]
 - [Adding a glossary]
  [Abbreviations]: https://python-markdown.github.io/extensions/abbreviations/
  [Abbreviations support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
  [Adding abbreviations]: ../../reference/abbreviations.md#adding-abbreviations
  [Adding a glossary]: ../../reference/abbreviations.md#adding-a-glossary
 ### Admonition
 [:octicons-tag-24: 0.1.0][Admonition support] ·
 [:octicons-workflow-24: Extension][Admonition]
 The [Admonition] extension adds support for admonitions, more commonly known as 
 _call-outs_, which can be defined in Markdown by using a simple syntax. Enable
 it via `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - admonition
 ```
 No configuration options are available. See reference for usage:
 - [Adding admonitions]
 - [Changing the title]
 - [Removing the title]
 - [Supported types]
  [Admonition]: https://python-markdown.github.io/extensions/admonition/
  [Admonition support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
  [Adding admonitions]: ../../reference/admonitions.md#usage
  [Changing the title]: ../../reference/admonitions.md#changing-the-title
  [Removing the title]: ../../reference/admonitions.md#removing-the-title
  [Supported types]: ../../reference/admonitions.md#supported-types
 ### Attribute Lists
 [:octicons-tag-24: 0.1.0][Attribute Lists support] ·
 [:octicons-workflow-24: Extension][Attribute Lists]
 The [Attribute Lists] extension allows to add HTML attributes and CSS classes
 to [almost every][Attribute Lists limitations] Markdown inline- and block-level
 element with a special syntax. Enable it via `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - attr_list
 ```
 No configuration options are available. See reference for usage:
 - [Adding buttons]
 - [Adding icons with colors]
 - [Image alignment]
 - [Image lazy-loading]
  [Attribute Lists]: https://python-markdown.github.io/extensions/attr_list/
  [Attribute Lists support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
  [Attribute Lists limitations]: https://python-markdown.github.io/extensions/attr_list/#limitations
  [Adding buttons]: ../../reference/buttons.md#adding-buttons
  [Adding icons with colors]: ../../reference/buttons.md#with-colors
  [Image alignment]: ../../reference/images.md#image-alignment
  [Image lazy-loading]: ../../reference/images.md#image-lazy-loading
 ### Definition Lists
 [:octicons-tag-24: 1.1.0][Definition Lists support] ·
 [:octicons-workflow-24: Extension][Definition Lists]
 The [Definition Lists] extension adds the ability to add definition lists (more
 commonly known as [description lists] – `dl` in HTML) via Markdown to a
 document. Enable it via `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - def_list
 ```
 No configuration options are available. See reference for usage:
 - [Using definition lists]
  [Definition Lists]: https://python-markdown.github.io/extensions/definition_lists/
  [Definition Lists support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0
  [description lists]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl
  [Using definition lists]: ../../reference/lists.md#using-definition-lists
 ### Footnotes
 [:octicons-tag-24: 1.0.0][Footnotes support] ·
 [:octicons-workflow-24: Extension][Footnotes]
 The [Footnotes] extension allows to define inline footnotes, which are then
 rendered below all Markdown content of a document. Enable it via `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - footnotes
 ```
 No configuration options are supported. See reference for usage:
 - [Adding footnote references]
 - [Adding footnote content]
  [Footnotes]: https://python-markdown.github.io/extensions/footnotes/
  [Footnotes support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
  [Adding footnote references]: ../../reference/footnotes.md#adding-footnote-references
  [Adding footnote content]: ../../reference/footnotes.md#adding-footnote-content
 ### Metadata
 [:octicons-tag-24: 1.0.0][Metadata support] ·
 [:octicons-workflow-24: Extension][Metadata]
 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.
 Enable it via `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - meta
 ```
 No configuration options are available. See reference for usage:
 - [Setting the page title]
 - [Setting the page description]
 - [Hiding the sidebars]
 - [Adding tags]
  [Metadata]: https://python-markdown.github.io/extensions/meta_data/
  [Metadata support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
  [Setting the page title]: ../../reference/meta-tags.md#setting-the-page-title
  [Setting the page description]: ../../reference/meta-tags.md#setting-the-page-description
  [Hiding the sidebars]: ../../setup/setting-up-navigation.md#hiding-the-sidebars
  [Adding tags]: ../../setup/setting-up-tags.md#adding-tags
 ### Markdown in HTML
 [:octicons-tag-24: 0.1.0][Markdown in HTML support] ·
 [:octicons-workflow-24: Extension][Markdown in HTML]
 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:
  - md_in_html
 ```
 > 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
 > the output, while all other attributes will be preserved.
 No configuration options are available. See reference for usage:
 - [Image captions]
  [Markdown in HTML]: https://python-markdown.github.io/extensions/md_in_html/
  [Markdown in HTML support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
  [Image captions]: ../../reference/images.md#image-captions
 ### Table of Contents
 [:octicons-tag-24: 0.1.0][Table of Contents support] ·
 [:octicons-workflow-24: Extension][Table of Contents]
 The [Table of Contents] extension automatically generates a table of contents
 from a document, which Material for MkDocs will render as part of the resulting 
 page. Enable it via `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
  - toc:
      permalink: true
 ```
 The following configuration options are supported:
 `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
    each headline, exactly like on the page you're currently viewing, which
    Material for MkDocs will make appear on hover:
    === "¶"
        ``` yaml
        markdown_extensions:
          - toc:
              permalink: true
        ```
    === "⚓︎"
        ``` yaml
        markdown_extensions:
          - toc:
              permalink: ⚓︎
        ```
 `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
    produce good and readable identifiers – consider using another slug function
    like for example those from [Python Markdown Extensions][Slugs]:
    === "Unicode"
        ``` yaml
        markdown_extensions:
          - toc:
              slugify: !!python/name:pymdownx.slugs.uslugify
        ```
    === "Unicode, case-sensitive"
        ``` yaml
        markdown_extensions:
          - toc:
              slugify: !!python/name:pymdownx.slugs.uslugify_cased
        ```
 `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
    documentation with deeply structured headings to decrease the length of the
    table of contents, or to remove the table of contents altogether:
    === "Hide levels 4-6"
        ``` yaml
        markdown_extensions:
          - toc:
              toc_depth: 3
        ```
    === "Hide table of contents"
        ``` yaml
        markdown_extensions:
          - toc:
              toc_depth: 0
        ```
 The other configuration options of this extension are not officially supported
 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/
  [Table of Contents support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
  [Slugs]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
 ### Tables
 [:octicons-tag-24: 0.1.0][Tables support] ·
 [:octicons-workflow-24: Extension][Tables]
 The [Tables] extension adds the ability to create tables in Markdown by using a 
 simple syntax. Enable it via `mkdocs.yml` (albeit it should be enabled by
 default):
 ``` yaml
 markdown_extensions:
  - tables
 ```
 No configuration options are available. See reference for usage:
 - [Using data tables]
 - [Column alignment]
  [Tables]: https://python-markdown.github.io/extensions/tables/
  [Tables support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
  [Using data tables]: ../../reference/data-tables.md#using-data-tables
  [Column alignment]: ../../reference/data-tables.md#column-alignment
 ## Superseded extensions
 The following [Python Markdown] extensions are not (or might not be) supported 
 anymore, and are therefore not recommended for use. Instead, the alternatives
 should be considered.
 ### Fenced Code Blocks
 [:octicons-tag-24: 0.1.0][Fenced Code Blocks support] ·
 [:octicons-workflow-24: Extension][Fenced Code Blocks]
 Superseded by [SuperFences]. This extension might still work, but the
 [SuperFences] extension is superior in many ways, as it allows for arbitrary 
 nesting, and is therefore recommended.
  [Fenced Code Blocks]: https://python-markdown.github.io/extensions/fenced_code_blocks/
  [Fenced Code Blocks support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
  [SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
 ### CodeHilite
 [:octicons-tag-24: 0.1.0 ... 5.5.14][CodeHilite support] ·
 [:octicons-workflow-24: Extension][CodeHilite]
 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
  [Highlight]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
  [InlineHilite]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
--- a/docs/setup/setting-up-navigation.md
+++ b/docs/setup/setting-up-navigation.md
@ -6,22 +6,23 @@ template: overrides/main.html
 A clear and concise navigation structure is an important aspect of good project 
 documentation. Material for MkDocs provides a multitude of options to configure
-the behavior of navigational elements, including [tabs][1] and [sections][2],
+the behavior of navigational elements, including [tabs][navigation.tabs] and
-and its flag-ship feature: [instant loading][3].
+[sections][navigation.sections], and its flag-ship feature: [instant loading]
 [navigation.instant].
-  [1]: #navigation-tabs
+  [navigation.tabs]: #navigation-tabs
-  [2]: #navigation-sections
+  [navigation.sections]: #navigation-sections
-  [3]: #instant-loading
+  [navigation.instant]: #instant-loading
 ## Configuration
 ### Instant loading
-[:octicons-file-code-24: Source][4] ·
+[:octicons-tag-24: 5.0.0][navigation.instant support] ·
 :octicons-unlock-24: Feature flag
-When _instant loading_ is enabled, clicks on all internal links will be
+When instant loading is enabled, clicks on all internal links will be
-intercepted and dispatched via [XHR][5] without fully reloading the page. Add
+intercepted and dispatched via [XHR] without fully reloading the page. Add
 the following lines to `mkdocs.yml`:
 ``` yaml
@ -31,23 +32,21 @@ theme:
 ```
 The resulting page is parsed and injected and all event handlers and components
-are rebound automatically. This means that __Material for MkDocs behaves like a
+are rebound automatically, i.e., __Material for MkDocs now behaves like a Single
-Single Page Application__, which is especially useful for large documentation
+Page Application__. Now, the search index survives navigation, which is
-sites that come with a massive search index, as the search index will now
+especially useful for large documentation sites.
 remain intact in-between document switches.
-_Material for MkDocs is the only MkDocs theme offering this feature._
+  [navigation.instant support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.0
-
+  [XHR]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
  [4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/instant/index.ts
  [5]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
 ### Anchor tracking
-[:octicons-file-code-24: Source][6] ·
+[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
 [:octicons-tag-24: insiders-2.1.0][Insiders] ·
 :octicons-unlock-24: Feature flag ·
-[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][6]{ .mdx-insiders }
+:octicons-beaker-24: Experimental
-When _anchor tracking_ is enabled, the URL in the address bar is automatically
+When anchor tracking is enabled, the URL in the address bar is automatically
 updated with the active anchor as highlighted in the table of contents. Add the
 following lines to `mkdocs.yml`:
@ -57,24 +56,25 @@ theme:
    - navigation.tracking
 ```
-  [6]: ../insiders/index.md
+  [Insiders]: ../insiders/index.md
 ### Navigation tabs
-[:octicons-file-code-24: Source][7] · :octicons-unlock-24: Feature flag
+[:octicons-tag-24: 1.1.0][navigation.tabs support] ·
 :octicons-unlock-24: Feature flag
-When _tabs_ are enabled, top-level sections are rendered in a menu layer below
+When tabs are enabled, top-level sections are rendered in a menu layer below
 the header for viewports above `1220px`, but remain as-is on mobile.[^1] Add
 the following lines to `mkdocs.yml`:
  [^1]:
-    Prior to version 6.2, navigation tabs had a slightly different behavior.
+    Prior to :octicons-tag-24: 6.2.0, navigation tabs had a slightly different
-    All top-level pages (i.e. all top-level entries that directly refer to an
+    behavior. All top-level pages (i.e. all top-level entries directly
-    `*.md` file) defined inside the `nav` entry of `mkdocs.yml` were grouped
+    refefring to a `*.md` file) defined inside the `nav` entry of `mkdocs.yml`
-    under the first tab which received the title of the first page. This made
+    were grouped under the first tab which received the title of the first page.
-    it impossible to include a top-level page (or external link) as a tab item,
+    This made it impossible to include a top-level page (or external link) as a
-    as was reported in #1884 and #2072. From version 6.2 on, navigation tabs
+    tab item, as was reported in #1884 and #2072. From :octicons-tag-24: 6.2.0
-    include all top-level pages and sections.
+    on, navigation tabs include all top-level pages and sections.
 ``` yaml
 theme:
@ -82,25 +82,25 @@ theme:
    - navigation.tabs
 ```
-=== "With tabs"
+=== ":octicons-check-circle-fill-16: Enabled"
-    [![With tabs][8]][8]
+    [![navigation.tabs enabled]][navigation.tabs enabled]
-=== "Without tabs"
+=== ":octicons-skip-16: Disabled"
-    [![Without tabs][9]][9]
+    [![navigation.tabs disabled]][navigation.tabs disabled]
-  [7]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/tabs.html
+  [navigation.tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0
-  [8]: ../assets/screenshots/navigation-tabs.png
+  [navigation.tabs enabled]: ../assets/screenshots/navigation-tabs.png
-  [9]: ../assets/screenshots/navigation.png
+  [navigation.tabs disabled]: ../assets/screenshots/navigation.png
 #### Sticky navigation tabs
-[:octicons-file-code-24: Source][10] ·
+[:octicons-tag-24: 7.3.0][navigation.tabs.sticky support] ·
 :octicons-unlock-24: Feature flag ·
 :octicons-beaker-24: Experimental
-When _sticky tabs_ are enabled, navigation tabs will lock below the header and
+When sticky tabs are enabled, navigation tabs will lock below the header and
 always remain visible when scrolling down. Just add the following two feature
 flags to `mkdocs.yml`:
@ -111,24 +111,24 @@ theme:
    - navigation.tabs.sticky
 ```
-=== "With sticky tabs"
+=== ":octicons-check-circle-fill-16: Enabled"
-    [![With sticky tabs][11]][11]
+    [![navigation.tabs.sticky enabled]][navigation.tabs.sticky enabled]
-=== "Without sticky tabs"
+=== ":octicons-skip-16: Disabled"
-    [![Without sticky tabs][12]][12]
+    [![navigation.tabs.sticky disabled]][navigation.tabs.sticky disabled]
-  [10]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/header.html
+  [navigation.tabs.sticky support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
-  [11]: ../assets/screenshots/navigation-tabs-sticky.png
+  [navigation.tabs.sticky enabled]: ../assets/screenshots/navigation-tabs.png
-  [12]: ../assets/screenshots/navigation-tabs-collapsed.png
+  [navigation.tabs.sticky disabled]: ../assets/screenshots/navigation.png
 ### Navigation sections
-[:octicons-file-code-24: Source][13] ·
+[:octicons-tag-24: 6.2.0][navigation.sections support] ·
 :octicons-unlock-24: Feature flag
-When _sections_ are enabled, top-level sections are rendered as groups in the
+When sections are enabled, top-level sections are rendered as groups in the
 sidebar for viewports above `1220px`, but remain as-is on mobile. Add the
 following lines to `mkdocs.yml`:
@ -138,27 +138,29 @@ theme:
    - navigation.sections
 ```
-=== "With sections"
+=== ":octicons-check-circle-fill-16: Enabled"
-    [![With sections][14]][14]
+    [![navigation.sections enabled]][navigation.sections enabled]
-=== "Without sections"
+=== ":octicons-skip-16: Disabled"
-    [![Without sections][9]][9]
+    [![navigation.sections disabled]][navigation.sections disabled]
-  [13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/nav-item.html
+  [navigation.sections support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
-  [14]: ../assets/screenshots/navigation-sections.png
+  [navigation.sections enabled]: ../assets/screenshots/navigation-sections.png
  [navigation.sections disabled]: ../assets/screenshots/navigation.png
-Both feature flags, _tabs_ and _sections_, can be combined with each other. If
+Both feature flags, [`navigation.tabs`][navigation.tabs] and
-both feature flags are enabled, sections are rendered for level 2 navigation
+[`navigation.sections`][navigation.sections], can be combined with each other.
 If both feature flags are enabled, sections are rendered for level 2 navigation
 items.
 ### Navigation expansion
-[:octicons-file-code-24: Source][13] ·
+[:octicons-tag-24: 6.2.0][navigation.expand support] ·
 :octicons-unlock-24: Feature flag
-When _expansion_ is enabled, the left sidebar will expand all collapsible
+When expansion is enabled, the left sidebar will expand all collapsible
 subsections by default, so the user doesn't have to open subsections manually.
 Add the following lines to `mkdocs.yml`:
@ -168,23 +170,25 @@ theme:
    - navigation.expand
 ```
-=== "With expansion"
+=== ":octicons-check-circle-fill-16: Enabled"
-    [![With expansion][15]][15]
+    [![navigation.expand enabled]][navigation.expand enabled]
-=== "Without expansion"
+=== ":octicons-skip-16: Disabled"
-    [![Without expansion][9]][9]
+    [![navigation.expand disabled]][navigation.expand disabled]
-  [15]: ../assets/screenshots/navigation-expand.png
+  [navigation.expand support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
  [navigation.expand enabled]: ../assets/screenshots/navigation-expand.png
  [navigation.expand disabled]: ../assets/screenshots/navigation.png
 ### Section index pages
-[:octicons-file-code-24: Source][16] ·
+[:octicons-tag-24: 7.3.0][navigation.indexes support] ·
 :octicons-unlock-24: Feature flag ·
 :octicons-beaker-24: Experimental
-When _section index pages_ are enabled, documents can be directly attached to
+When section index pages are enabled, documents can be directly attached to
 sections, which is particularly useful for providing overview pages. Add the
 following lines to `mkdocs.yml`:
@ -194,13 +198,13 @@ theme:
    - navigation.indexes
 ```
-=== "With section index pages"
+=== ":octicons-check-circle-fill-16: Enabled"
-    [![With expansion][17]][17]
+    [![navigation.indexes enabled]][navigation.indexes enabled]
-=== "Without section index pages"
+=== ":octicons-skip-16: Disabled"
-    [![Without expansion][18]][18]
+    [![navigation.indexes disabled]][navigation.indexes disabled]
 In order to link a page to a section, create a new document with the name
 `index.md` in the respective folder, and add it to the beginning of your
@ -215,20 +219,50 @@ nav:
    - Page n: section/page-n.md
 ```
-_This feature flag can be combined with all other feature flags, e.g. [tabs][1]
+This feature flag is not compatible with [`toc.integrate`][toc.integrate].
 and [sections][2], except for table of contents [navigation integration][19]._
-  [16]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/nav-item.html
+  [navigation.indexes support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
-  [17]: ../assets/screenshots/navigation-index-on.png
+  [navigation.indexes enabled]: ../assets/screenshots/navigation-index-on.png
-  [18]: ../assets/screenshots/navigation-index-off.png
+  [navigation.indexes disabled]: ../assets/screenshots/navigation-index-off.png
-  [19]: #navigation-integration
+  [toc.integrate]: #integrated-table-of-contents
 ### Integrated table of contents
 [:octicons-tag-24: 6.2.0][toc.integrate support] ·
 :octicons-unlock-24: Feature flag
 When navigation integration for the table of contents is enabled, it is always
 rendered as part of the navigation sidebar on the left. Add the following lines
 to `mkdocs.yml`:
 ``` yaml
 theme:
  features:
    - toc.integrate
 ```
 === ":octicons-check-circle-fill-16: Enabled"
    [![toc.integrate enabled]][toc.integrate enabled]
 === ":octicons-skip-16: Disabled"
    [![toc.integrate disabled]][toc.integrate disabled]
 This feature flag is not compatible with [`navigation.indexes`]
 [navigation.indexes].
  [toc.integrate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
  [toc.integrate enabled]: ../assets/screenshots/toc-integrate.png
  [toc.integrate disabled]: ../assets/screenshots/navigation-tabs.png
  [navigation.indexes]: #section-index-pages
 ### Back-to-top button
-[:octicons-file-code-24: Source][20] ·
+[:octicons-tag-24: 7.1.0][navigation.top support] ·
 :octicons-unlock-24: Feature flag
-A _back-to-top button_ can be shown when the user, after scrolling down, starts
+A back-to-top button can be shown when the user, after scrolling down, starts
 to scroll up again. It's rendered centered and just below the header. Add the
 following lines to `mkdocs.yml`:
@ -238,137 +272,15 @@ theme:
    - navigation.top
 ```
-[![back-to-top button][21]][21]
+  [navigation.top support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
  [20]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_top.scss
  [21]: ../assets/screenshots/back-to-top.png
 ### Table of contents
 [:octicons-file-code-24: Source][22] · [:octicons-workflow-24: Extension][23]
 The [Table of contents][24] extension, which is part of the standard Markdown
 library, provides some options that are supported by Material for MkDocs to
 customize its appearance:
 `permalink`{ #permalink }
 :   :octicons-milestone-24: Default: `false` – This option adds an anchor link
    containing the paragraph symbol `¶` or another custom symbol at the end of
    each headline, exactly like on the page you're currently viewing, which
    Material for MkDocs will make appear on hover:
    === "¶"
        ``` yaml
        markdown_extensions:
          - toc:
              permalink: true
        ```
    === "⚓︎"
        ``` yaml
        markdown_extensions:
          - toc:
              permalink: ⚓︎
        ```
 `slugify`{ #slugify }
 :   :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][25]:
    === "Unicode"
        ``` yaml
        markdown_extensions:
          - toc:
              slugify: !!python/name:pymdownx.slugs.uslugify
        ```
    === "Unicode, case-sensitive"
        ``` yaml
        markdown_extensions:
          - toc:
              slugify: !!python/name:pymdownx.slugs.uslugify_cased
        ```
 `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
    documentation with deeply structured headings to decrease the length of the
    table of contents, or to remove the table of contents altogether:
    === "Hide levels 4-6"
        ``` yaml
        markdown_extensions:
          - toc:
              toc_depth: 3
        ```
    === "Hide table of contents"
        ``` yaml
        markdown_extensions:
          - toc:
              toc_depth: 0
        ```
 _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._
  [22]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
  [23]: https://python-markdown.github.io/extensions/toc/
  [24]: https://python-markdown.github.io/extensions/toc/#usage
  [25]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
 #### Navigation integration
 [:octicons-file-code-24: Source][26] ·
 :octicons-unlock-24: Feature flag
 When _integration_ is enabled, the table of contents is rendered as part of
 the navigation for viewports above `1220px`, but remains as-is on mobile. Add
 the following lines to `mkdocs.yml`:
 ``` yaml
 theme:
  features:
    - toc.integrate
 ```
 === "Integrate table of contents"
    [![Integrate table of contents][27]][27]
 === "Separate table of contents"
    [![Separate table of contents][8]][8]
  [26]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_nav.scss
  [27]: ../assets/screenshots/toc-integrate.png
 The content section will now always stretch to the right side, resulting in
 more space for your content. This feature flag can be combined with all other
 feature flags, e.g. [tabs][1] and [sections][2]. 
 ## Usage
 ### Hiding the sidebars
-[:octicons-file-code-24: Source][28] ·
+When [Metadata] is enabled, the navigation and/or table of contents sidebars
-:octicons-note-24: Metadata
+can be hidden for a document with custom front matter. Add the following lines
-
+at the top of a Markdown file:
 Sometimes it's desirable to hide the navigation and/or table of contents
 sidebar, especially when there's a single navigation item. This can be done for
 any page using the [Metadata][29] extension:
 ``` bash
 ---
@ -383,33 +295,29 @@ hide:
 === "Hide navigation"
-    [![Hide navigation][30]][30]
+    [![hide.navigation enabled]][hide.navigation enabled]
 === "Hide table of contents"
-    [![Hide table of contents][31]][31]
+    [![hide.toc enabled]][hide.toc enabled]
 === "Hide both"
-    [![Hide navigation and table of contents][32]][32]
+    [![hide.* enabled]][hide.* enabled]
-  [28]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
+  [Metadata]: extensions/python-markdown.md#metadata
-  [29]: ../../reference/meta-tags/#metadata
+  [hide.navigation enabled]: ../assets/screenshots/hide-navigation.png
-  [30]: ../assets/screenshots/hide-navigation.png
+  [hide.toc enabled]: ../assets/screenshots/hide-toc.png
-  [31]: ../assets/screenshots/hide-toc.png
+  [hide.* enabled]: ../assets/screenshots/hide-navigation-toc.png
  [32]: ../assets/screenshots/hide-navigation-toc.png
 ## Customization
 ### Keyboard shortcuts
 [:octicons-file-code-24: Source][33] ·
 :octicons-mortar-board-24: Difficulty: _easy_
 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:
@ -418,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
@ -429,54 +337,66 @@ to navigate your project documentation via keyboard. There're two modes:
    * ++n++ , ++period++ : go to next page
 Let's say you want to bind some action to the ++x++ key. By using [additional
-JavaScript][34], you can subscribe to the `keyboard$` observable and attach
+JavaScript], you can subscribe to the `keyboard$` observable and attach
 your custom event listener:
-``` js
+=== ":octicons-file-code-16: docs/javascripts/shortcuts.js"
 keyboard$.subscribe(function(key) {
  if (key.mode === "global" && key.type === "x") {
    /* Add custom keyboard handler here */
    key.claim()
  }
 })
 ```
-The call to `#!js key.claim()` will essentially execute `#!js preventDefault()`
+    ``` js
-on the underlying event, so the keypress will not propagate further and touch
+    keyboard$.subscribe(function(key) {
-other event listeners.
+      if (key.mode === "global" && key.type === "x") {
        /* Add custom keyboard handler here */
        key.claim() // (1)
      }
    })
    ```
-  [33]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts
+    1.  The call to `key.claim()` will execute `preventDefault()` on the
-  [34]: ../customization.md#additional-javascript
+        underlying event, so the keypress will not propagate further and
        touch other event listeners.
 === ":octicons-file-code-16: mkdocs.yml"
    ``` yaml
    extra_javascript:
      - javascripts/shortcuts.js
    ```
  [additional JavaScript]: ../customization.md#additional-javascript
 ### Content area width
 [:octicons-file-code-24: Source][35] ·
 :octicons-mortar-board-24: Difficulty: _easy_
 The width of the content area is set so the length of each line doesn't exceed
 80-100 characters, depending on the width of the characters. While this
 is a reasonable default, as longer lines tend to be harder to read, it may be
 desirable to increase the overall width of the content area, or even make it
 stretch to the entire available space.
-This can easily be achieved with an [additional stylesheet][36] and a few lines
+This can easily be achieved with an [additional style sheet] and a few lines
 of CSS:
-=== "Increase width"
+=== ":octicons-file-code-16: docs/stylesheets/extra.css"
    ``` css
    .md-grid {
-      max-width: 1440px;
+      max-width: 1440px; /* (1) */
    }
    ```
-=== "Stretch to fit"
+    1.  If you want the content area to always stretch to the available screen
        space, reset `max-width` with the following CSS:
-    ``` css
+        ``` css
-    .md-grid {
+        .md-grid {
-      max-width: initial;
+          max-width: initial;
-    }
+        }
        ```
 === ":octicons-file-code-16: mkdocs.yml"
    ``` yaml
    extra_css:
      - stylesheets/extra.css
    ```
-  [35]: https://github.com/squidfunk/mkdocs-material/blob/aeaa00a625abf952f355164de02c539b061e6127/src/assets/stylesheets/main/layout/_base.scss
+  [additional style sheet]: ../customization.md#additional-css
  [36]: ../customization.md#additional-css
--- a/docs/setup/setting-up-site-analytics.md
+++ b/docs/setup/setting-up-site-analytics.md
@ -6,23 +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-file-code-24: Source][3] · :octicons-milestone-24: Default: _none_
+[:octicons-tag-24: 7.1.8][Google Analytics support] ·
 :octicons-milestone-24: Default: _none_
 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. Depending on the given 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:
@ -31,7 +32,7 @@ the following to `mkdocs.yml`:
        property: G-XXXXXXXXXX
    ```
-=== "Universal Analytics"
+=== ":material-google-analytics: Universal Analytics"
    ``` yaml
    extra:
@ -40,34 +41,34 @@ the following to `mkdocs.yml`:
        property: UA-XXXXXXXX-X
    ```
-  [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/integrations/analytics.html
+  [Google Analytics support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.8
 #### 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:
-1. Go to your Google Analytics __admin settings__
+1.  Go to your Google Analytics __admin settings__
-2. Select the property for the respective tracking code
+2.  Select the property for the respective tracking code
-3. Go to the __view settings__ tab.
+3.  Go to the __view settings__ tab.
-4. Scroll down and enable __site search settings__
+4.  Scroll down and enable __site search settings__
-5. Set the __query parameter__ to `q`.
+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-file-code-24: Source][5] ·
+[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
-:octicons-milestone-24: Default: _none_ ·
+[:octicons-tag-24: insiders-2.10.0][Insiders] ·
-[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][5]{ .mdx-insiders }
+:octicons-milestone-24: Default: _none_
-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
@ -81,15 +82,15 @@ extra:
      make our documentation better.
 ```
-1. You can add arbitrary HTML tags in the `description`, e.g. to link to your
+1.  You can add arbitrary HTML tags in the `description`, e.g. to link to your
-   terms of service or other parts of the site.
+    terms of service or other parts of the site.
 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:
@ -100,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:
@ -115,78 +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 }
 ```
-  [5]: ../insiders/index.md
+  [Insiders]: ../insiders/index.md
-  [6]: #custom-cookies
+  [custom cookies]: #custom-cookies
-  [7]: ../assets/screenshots/consent.png
+  [extra.consent enabled]: ../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
--- a/docs/setup/setting-up-site-search.md
+++ b/docs/setup/setting-up-site-search.md
@ -37,7 +37,7 @@ plugins:
 The following options are supported:
-`lang`{ #lang }
+`lang`{ #search-lang }
 :   :octicons-milestone-24: Default: _automatically set_ – This option allows
    to include the language-specific stemmers provided by [lunr-languages][5].
@ -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
@ -98,7 +98,7 @@ 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: _automatically set_ – The separator for
    indexing and query tokenization can be customized, making it possible to
@ -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
@ -146,11 +146,11 @@ Use them at your own risk._
 ### Search suggestions
 [:octicons-file-code-24: Source][8] ·
 :octicons-unlock-24: Feature flag ·
-:octicons-beaker-24: Experimental
+:octicons-beaker-24: Experimental ·
 [:octicons-tag-24: 7.2.0][Search suggestions support]
-When _search suggestions_ are enabled, the search will display the likeliest
+When search suggestions are enabled, the search will display the likeliest
 completion for the last word, saving the user many key strokes by accepting the
 suggestion with the ++arrow-right++ key.
@ -166,17 +166,18 @@ Searching for [:octicons-search-24: search su][9] yields ^^search suggestions^^
 [![Search suggestions][10]][10]
  [Search suggestions support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
  [8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/components/search/suggest/index.ts
  [9]: ?q=search+su
  [10]: ../assets/screenshots/search-suggestions.png
 ### Search highlighting
 [:octicons-file-code-24: Source][11] ·
 :octicons-unlock-24: Feature flag ·
-:octicons-beaker-24: Experimental
+:octicons-beaker-24: Experimental ·
 [:octicons-tag-24: 7.2.0][Search highlighting support]
-When _search highlighting_ is enabled and a user clicks on a search result,
+When search highlighting is enabled and a user clicks on a search result,
 Material for MkDocs will highlight all occurrences after following the link.
 Add the following lines to `mkdocs.yml`:
@ -190,17 +191,18 @@ Searching for [:octicons-search-24: code blocks][12] yields:
 [![Search highlighting][13]][13]
  [Search highlighting support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
  [11]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/components/search/highlight/index.ts
  [12]: ../reference/code-blocks.md?h=code+blocks
  [13]: ../assets/screenshots/search-highlighting.png
 ### Search sharing
 [:octicons-file-code-24: Source][14] ·
 :octicons-unlock-24: Feature flag ·
-:octicons-beaker-24: Experimental
+:octicons-beaker-24: Experimental ·
 [:octicons-tag-24: 7.2.0][Search highlighting support]
-When _search sharing_ is activated, a :material-share-variant: share button is
+When search sharing is activated, a :material-share-variant: share button is
 rendered next to the reset button, which allows to deep link to the current
 search query and result. Add the following lines to `mkdocs.yml`:
@ -215,6 +217,7 @@ clipboard.
 [![Search sharing][15]][15]
  [Search sharing support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
  [14]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/components/search/share/index.ts
  [15]: ../assets/screenshots/search-share.png
@ -245,9 +248,9 @@ For setup instructions, refer to the [official documentation][19].
 ### Search boosting
-[:octicons-file-code-24: Source][20] ·
+[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
 :octicons-note-24: Metadata ·
-[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][20]{ .mdx-insiders }
+[:octicons-tag-24: insiders-2.8.0][Insiders]
 In order to give specific pages a higher relevance in search, [lunr][4] supports
 page-specific boosts, which can be defined for each page by leveraging the
@ -263,14 +266,16 @@ search:
 ...
 ```
  [Insiders]: ../insiders/index.md
  [20]: ../insiders/index.md
  [21]: ../reference/meta-tags.md#metadata
 ### Search exclusion
-[:octicons-file-code-24: Source][20] ·
+[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
 :octicons-note-24: Metadata ·
 :octicons-beaker-24: Experimental ·
-[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][20]{ .mdx-insiders }
+[:octicons-tag-24: insiders-3.1.0][Insiders]
 #### Excluding pages
@ -395,19 +400,19 @@ export function defaultTransform(query: string): string {
 }
 ```
-1. Search for terms in quotation marks and prepend a `+` modifier to denote
+1.  Search for terms in quotation marks and prepend a `+` modifier to denote
-   that the resulting document must contain all terms, converting the query
+    that the resulting document must contain all terms, converting the query
-   to an `AND` query (as opposed to the default `OR` behavior). While users
+    to an `AND` query (as opposed to the default `OR` behavior). While users
-   may expect terms enclosed in quotation marks to map to span queries, i.e.
+    may expect terms enclosed in quotation marks to map to span queries, i.e.
-   for which order is important, `lunr` doesn't support them, so the best
+    for which order is important, `lunr` doesn't support them, so the best
-   we can do is to convert the terms to an `AND` query.
+    we can do is to convert the terms to an `AND` query.
-2. Replace control characters which are not located at the beginning of the
+2.  Replace control characters which are not located at the beginning of the
-   query or preceded by white space, or are not followed by a non-whitespace
+    query or preceded by white space, or are not followed by a non-whitespace
-   character or are at the end of the query string. Furthermore, filter
+    character or are at the end of the query string. Furthermore, filter
-   unmatched quotation marks.
+    unmatched quotation marks.
-3. Trim excess whitespace from left and right.
+3.  Trim excess whitespace from left and right.
 If you want to switch to the default behavior of the `mkdocs` and `readthedocs`
 themes, both of which don't transform the query prior to submission, or
@ -434,7 +439,7 @@ and must return the processed query string to be submitted to the search index.
  [23]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts
  [24]: ../customization.md#extending-the-theme
-  [25]: ../customization.md#overriding-blocks-recommended
+  [25]: ../customization.md#overriding-blocks
 ### Custom search
--- a/docs/setup/setting-up-social-cards.md
+++ b/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,71 @@ 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-file-code-24: Source][4] ·
+[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
-[:octicons-cpu-24: Plugin][4] ·
+[:octicons-tag-24: insiders-2.12.0][Insiders] ·
-:octicons-beaker-24: Experimental ·
+:octicons-cpu-24: Plugin ·
-[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][4]{ .mdx-insiders }
+:octicons-beaker-24: Experimental
-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`:
+First, ensure you've set [`site_url`][site_url] in `mkdocs.yml`.[^2] Then, add
 the following lines to `mkdocs.yml` to enable the plugin:
  [^2]:
    When using this plugin, the [`site_url`][site_url] setting is mandatory, as
    social preview images don't work with relative URLs.
 ``` 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="1">
+<figure markdown>
-[![Social Cards][6]][6]
+[![Social cards preview]][Social cards preview]
-  <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.
+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: _automatically set based on [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 }
+`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:
@ -85,24 +87,26 @@ are available:
          cards_directory: assets/images/social
    ```
-  [4]: ../insiders/index.md
+  [Insiders]: ../insiders/index.md
-  [5]: setting-up-site-analytics.md
+  [site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
-  [6]: ../assets/screenshots/social-cards.png
+  [setting up site analytics]: setting-up-site-analytics.md
-  [7]: https://cards-dev.twitter.com/validator
+  [Social cards preview]: ../assets/screenshots/social-cards.png
-  [8]: changing-the-colors.md#primary-color
+  [Twitter's Card validator]: https://cards-dev.twitter.com/validator
  [meta tags]: #meta-tags
  [CSS color keywords]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords
-#### Caching
+#### Caching <small>recommended</small> { #caching 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`.
+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
+2.  When building your site for publishing, use a build cache to save the
-   `.cache` directory in between builds. Taking the example from 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
@ -127,18 +131,64 @@ 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]: #built-in-social-cards
-  [10]: ../publishing-your-site.md#with-github-actions
+  [publishing guide]: ../publishing-your-site.md#with-github-actions
 #### Meta tags
 The [built-in social cards] plugin automatically sets all necessary `meta` tags,
 equivalent to the following two customizations, which you can set manually when
 you don't want to use it:
 === ":material-graph: Open Graph"
    ``` html
    {% block extrahead %}
      {% set title = config.site_name %}
      {% 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 %}
      {% endif %}
      <meta property="og:type" content="website" />
      <meta property="og:title" content="{{ title }}" />
      <meta property="og:description" content="{{ config.site_description }}" />
      <meta property="og:url" content="{{ page.canonical_url }}" />
      <meta property="og:image" content="<url>" />
      <meta property="og:image:type" content="image/png" />
      <meta property="og:image:width" content="1200" />
      <meta property="og:image:height" content="630" />
    {% endblock %}
    ```
 === ":fontawesome-brands-twitter: Twitter Cards"
    ``` html
    {% block extrahead %}
      {% set title = config.site_name %}
      {% 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 %}
      {% endif %}
      <meta name="twitter:card" content="summary_large_image" />
      <meta name="twitter:title" content="{{ title }}" />
      <meta name="twitter:description" content="{{ config.site_description }}" />
      <meta name="twitter:image" content="<url>" />
    {% endblock %}
    ```
  [Twitter Cards]: https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards
 ## Usage
 If you want to adjust the title or set a custom description for the social card,
-you can use the [Metadata][11] extension, which takes precedence over the
+you can use the [Metadata] extension, which takes precedence over the
 default values.
- [Changing the title][12]
+- [Changing the title]
- [Changing the description][13]
+- [Changing the description]
-  [11]: ../reference/meta-tags.md#metadata
+  [Metadata]: extensions/python-markdown.md#metadata
-  [12]: ../reference/meta-tags.md#setting-the-page-title
+  [Changing the title]: ../reference/meta-tags.md#setting-the-page-title
-  [13]: ../reference/meta-tags.md#setting-the-page-description
+  [Changing the description]: ../reference/meta-tags.md#setting-the-page-description
--- a/docs/setup/setting-up-tags.md
+++ b/docs/setup/setting-up-tags.md
@ -13,12 +13,12 @@ can help to discover relevant information faster.
 ### Built-in tags
-[:octicons-file-code-24: Source][1] ·
+[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
-[:octicons-cpu-24: Plugin][1] ·
+[:octicons-tag-24: insiders-2.7.0][Insiders] ·
-:octicons-beaker-24: Experimental ·
+:octicons-cpu-24: Plugin ·
-[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][1]{ .mdx-insiders }
+:octicons-beaker-24: Experimental
-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 }
+`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,31 +47,18 @@ The following options are available:
    option is not specified, tags are still rendered and searchable,
    but without a tags index.
-  [^1]:
+  [Insiders]: ../insiders/index.md
-    The built-in tags plugin has no affiliation with [mkdocs-plugin-tags][2],
+  [adding a tags index]: #adding-a-tags-index
    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.
  [1]: ../insiders/index.md
  [2]: https://github.com/jldiaz/mkdocs-plugin-tags
  [3]: #adding-a-tags-index
 ## Usage
 ### Adding tags
-[:octicons-file-code-24: Source][1] ·
+When both, the [built-in tags] plugin and [Metadata] extension are enabled,
-:octicons-note-24: Metadata
+tags can be added for a document with custom front matter. Add the following
 lines at the top of a Markdown file:
-If both, the [built-in tags plugin][4] and [Metadata][5] extension are enabled,
+``` bash
 tags can be added for any page as part of the front matter, e.g. to add the tags
 `insiders` and `brand new` to this page, add:
 ``` yaml
 ---
 tags:
  - insiders
@ -89,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]: #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
@ -120,17 +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
 [:octicons-file-code-24: Source][1] ·
 :octicons-note-24: Metadata
 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
 ---
@ -141,5 +123,3 @@ hide:
 # Document title
 ...
 ```
  [10]: ../../reference/meta-tags/#metadata
--- a/docs/setup/setting-up-the-footer.md
+++ b/docs/setup/setting-up-the-footer.md
@ -15,10 +15,10 @@ configured via `mkdocs.yml`.
 ### Social links
-[:octicons-file-code-24: Source][1] ·
+[:octicons-tag-24: 1.0.0][Social links support] ·
 :octicons-milestone-24: Default: _none_
-All _social links_ are rendered next to the copyright information as part of the 
+Social links are rendered next to the copyright notice as part of the 
 footer of your project documentation. Add a list of social links in `mkdocs.yml` 
 with:
@ -29,13 +29,14 @@ extra:
      link: https://twitter.com/squidfunk
 ```
-For each entry, the following fields are available:
+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
-    with the theme][2], or the build will not succeed. Some popular choices:
+    with the theme][custom icons], or the build will not succeed. Some popular
    choices:
    * :fontawesome-brands-behance: – `fontawesome/brands/behance`
    * :fontawesome-brands-docker: – `fontawesome/brands/docker`
@ -48,16 +49,16 @@ For each entry, the following fields are available:
    * :fontawesome-brands-slack: – `fontawesome/brands/slack`
    * :fontawesome-brands-twitter: – `fontawesome/brands/twitter`
-  [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/social.html
+  [Social links support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
-  [2]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
+  [custom icons]: 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 
    scheme. All URI schemes are supported, including `mailto` and `bitcoin`:
-    === "Twitter"
+    === ":fontawesome-brands-twitter: Twitter"
        ``` yaml
        extra:
@ -66,7 +67,7 @@ For each entry, the following fields are available:
              link: https://twitter.com/squidfunk
        ```
-    === "Email address"
+    === ":octicons-mail-16: Email"
        ``` yaml
        extra:
@ -75,7 +76,7 @@ For each entry, the following fields 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 
@ -91,21 +92,23 @@ For each entry, the following fields are available:
 ### Copyright notice
-[:octicons-file-code-24: Source][3] · 
+[:octicons-tag-24: 0.1.0][Copyright notice support] ·
 :octicons-milestone-24: Default: _none_
-A custom _copyright banner_ can be rendered as part of the footer, which is
+A custom copyright banner can be rendered as part of the footer, which is
 displayed next to the social links. It can be defined as part of `mkdocs.yml`:
 ``` yaml
 copyright: Copyright &copy; 2016 - 2020 Martin Donath
 ```
  [Copyright notice support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
  [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/footer.html
-### Remove generator
+### Generator notice
-[:octicons-file-code-24: Source][3]
+[:octicons-tag-24: 7.3.0][Generator notice support] ·
 :octicons-milestone-24: Default: `true`
 The footer displays a _Made with Material for MkDocs_ notice to denote how
 the site was generated. The notice can be removed with the following setting
@ -121,25 +124,24 @@ extra:
    The subtle __Made with Material for MkDocs__ hint in the footer is one of
    the reasons why this project is so popular, as it tells the user how the
    site is generated, helping new users to discover this project. Before
-    removing it, please consider that you're enjoying the benefits of
+    removing please consider that you're enjoying the benefits of @squidfunk's
-    @squidfunk's work for free, as this project is Open Source and has a
+    work for free, as this project is Open Source and has a permissive license.
-    permissive license. Thousands of hours went into this project, most of them
+    Thousands of hours went into this project, most of them
-    without any financial return. Thus, if you remove this notice, please
+    without any financial return.
    consider [sponsoring][4] the project. __Thank you__
    :octicons-heart-fill-24:{ .mdx-heart .mdx-insiders }
-  [4]: ../insiders/index.md
+    Thus, if you remove this notice, please consider [sponsoring][Insiders] the
    project. __Thank you__ :octicons-heart-fill-24:{ .mdx-heart .mdx-insiders }
  [Generator notice support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
  [Insiders]: ../insiders/index.md
 ## Customization
 ### Custom icons
-[:octicons-file-code-24: Source][2] ·
+The social links feature uses the standard [icon integration] of Material for
 :octicons-mortar-board-24: Difficulty: _easy_
 The social links feature uses the standard [icon integration][5] of Material for
 MkDocs. If you want to use custom icons, follow the guide explaining how to
-add [additional icons][6].
+add [additional icons].
-  [5]: changing-the-logo-and-icons.md#icons
+  [icon integration]: extensions/python-markdown-extensions.md#emoji
-  [6]: changing-the-logo-and-icons.md#additional-icons
+  [additional icons]: changing-the-logo-and-icons.md#additional-icons
--- a/docs/setup/setting-up-the-header.md
+++ b/docs/setup/setting-up-the-header.md
@ -6,20 +6,20 @@ template: overrides/main.html
 Material for MkDocs' header can be customized to show an announcement bar that 
 disappears upon scrolling, and provides some options for further configuration.
-It also includes the [search bar][1] and a place to display your project's
+It also includes the [search bar] and a place to display your project's
-[git repository][2], as explained in those dedicated guides.
+[git repository], as explained in those dedicated guides.
-  [1]: setting-up-site-search.md
+  [search bar]: setting-up-site-search.md
-  [2]: adding-a-git-repository.md
+  [git repository]: adding-a-git-repository.md
 ## Configuration
 ### Automatic hiding
-[:octicons-file-code-24: Source][3] · 
+[:octicons-tag-24: 6.2.0][Automatic hiding support] ·
 :octicons-unlock-24: Feature flag
-When _autohiding_ is enabled, the header is automatically hidden when the
+When autohiding is enabled, the header is automatically hidden when the
 user scrolls past a certain threshold, leaving more space for content. Add the
 following lines to `mkdocs.yml`:
@ -29,25 +29,27 @@ theme:
    - header.autohide
 ```
-  [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_header.scss
+  [Automatic hiding support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
 ## Customization
 ### Announcement bar
 [:octicons-tag-24: 5.0.0][Announcement bar support] ·
 :octicons-file-symlink-file-24: Customization
 Material for MkDocs includes an announcement bar, which is the perfect place to
 display project news or other important information to the user. When the user
 scrolls past the header, the bar will automatically disappear. In order to add
-an announcement bar, [extend the theme][4] and [override the `announce`
+an announcement bar, [extend the theme] and [override the `announce`
-block][5], which is empty by default:
+block][overriding blocks], which is empty by default:
 ``` html
 {% extends "base.html" %}
 {% block announce %}
-  <!-- Add your announcement here, including arbitrary HTML -->
+  <!-- Add announcement here, including arbitrary HTML -->
 {% endblock %}
 ```
-  [4]: ../customization.md#extending-the-theme
+  [Announcement bar support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
-  [5]: ../customization.md#overriding-blocks-recommended
+  [extend the theme]: ../customization.md#extending-the-theme
  [overriding blocks]: ../customization.md#overriding-blocks
--- a/docs/setup/setting-up-versioning.md
+++ b/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="1">
+<figure markdown>
-[![Version selection][3]][3]
+[![Version selector preview]][Version selector preview]
-  <figcaption markdown="1">
+  <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,24 +55,20 @@ 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
-[:octicons-file-code-24: Source][7] ·
+[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
-[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][7]{ .mdx-insiders }
+[:octicons-tag-24: insiders-2.5.0][Insiders] ·
 :octicons-file-symlink-file-24: Customization
 If you're using versioning, you might want to display a warning when the user
-visits any other version than the latest version. Using [theme extension][8],
+visits any other version than the latest version. Using [theme extension],
-you can [define the `outdated` block][9]:
+you can [override the `outdated` block][overriding blocks]:
 ``` html
 {% extends "base.html" %}
@ -86,19 +81,19 @@ you can [define the `outdated` block][9]:
 {% endblock %}
 ```
-1. Given this value for the `href` attribute, the link will always redirect to 
+1.  Given this value for the `href` attribute, the link will always redirect to 
-   the root of your site, which will then redirect to the latest version. This
+    the root of your site, which will then redirect to the latest version. This
-   ensures that older versions of your site do not depend on a specific alias,
+    ensures that older versions of your site do not depend on a specific alias,
-   e.g. `latest`, to allow for changing the alias later on without breaking
+    e.g. `latest`, to allow for changing the alias later on without breaking
-   earlier versions.
+    earlier versions.
 This will render a version warning above the header:
-[![Version warning][10]][10]
+[![Version warning preview]][Version warning preview]
-By default, the default version is identified by the `latest` alias. If you
+The default version is identified by the `latest` alias. If you wish to set
-wish to set another alias as the latest version, e.g. `stable`, add the
+another alias as the latest version, e.g. `stable`, add the following lines
-following to `mkdocs.yml`:
+to `mkdocs.yml`:
 ``` yaml
 extra:
@ -106,18 +101,18 @@ extra:
    default: stable
 ```
-Make sure that this matches the [default version][11].
+Make sure that this matches the [default version].
-  [7]: ../insiders/index.md
+  [Insiders]: ../insiders/index.md
-  [8]: ../customization.md#extending-the-theme
+  [theme extension]: ../customization.md#extending-the-theme
-  [9]: ../customization.md#overriding-blocks-recommended
+  [overriding blocks]: ../customization.md#overriding-blocks
-  [10]: ../assets/screenshots/version-warning.png
+  [Version warning preview]: ../assets/screenshots/version-warning.png
-  [11]: #setting-a-default-version
+  [default version]: #setting-a-default-version
 ### Stay on page
-[:octicons-file-code-24: Source][7] ·
+[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
-[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][7]{ .mdx-insiders }
+[:octicons-tag-24: insiders-2.6.0][Insiders]
 Insiders improves the user experience when switching between versions: if
 version A and B contain a page with the same path name, the user will stay on
@ -139,21 +134,11 @@ the current page:
    docs.example.com/0.1/bar/ -> docs.example.com/0.2/
    ```
 <figure markdown="1">
  <figcaption markdown="1">
 A demo is worth a thousand words — check it out at
 [squidfunk.github.io/mkdocs-material-example-versioning][4]
  </figcaption>
 </figure>
 ## Usage
 While this section outlines the basic workflow for publishing new versions, 
-it's best to check out the [official documentation][6] to make yourself familar
+it's best to check out [mike's documentation][mike] to make yourself familar
-with [mike][1].
+with its mechanics.
 ### Publishing a new version
@ -173,15 +158,15 @@ e.g.:
 ### Setting a default version
-When starting with [mike][1], a good idea is to set an alias as a default
+When starting with [mike], a good idea is to set an alias as a default version,
-version, e.g. `latest`, and when publishing a new version, always update the
+e.g. `latest`, and when publishing a new version, always update the alias to
-alias to point to the latest version:
+point to the latest version:
 ```
 mike set-default --push latest
 ```
-When publishing a new version, [mike][1] will create a redirect in the root of
+When publishing a new version, [mike] will create a redirect in the root of
 your project documentation to the version associated with the alias:
 _docs.example.com_ :octicons-arrow-right-24: _docs.example.com/0.1_
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@ -1,117 +0,0 @@
 ---
 template: overrides/main.html
 ---
 # Troubleshooting
 ## Theme not recognized
 Operating systems:
 :fontawesome-brands-apple:
 :fontawesome-brands-windows:
 :fontawesome-brands-linux:
 !!! error "Error: Unrecognized theme"
    ``` sh
    mkdocs serve
    # => INFO    -  Building documentation...
    # => ERROR   -  Config value: 'theme'. Error: Unrecognised theme 'material'.
    # => ...
    # => ConfigurationError: Aborted with 1 Configuration Errors!
    ```
 If you run into this error, the most common reason is that you installed MkDocs
 through some package manager (e.g. `brew` or `apt-get`) and Material for MkDocs
 through `pip`, so both packages end up in different locations. MkDocs only
 checks its install location for themes.
 ## Inadequate permissions
 Operating systems: :fontawesome-brands-apple:
 !!! error "Error: Permission denied"
    ``` sh
    pip install mkdocs-material
    # => Could not install packages due to an EnvironmentError: [Errno 13] Permission denied: '...'
    # => Consider using the --user option or check the permissions.
    ```
 When you're running the pre-installed version of Python on macOS, `pip` tries
 to install packages in a folder for which your user might not have the adequate
 permissions. There are three possible solutions for this, the recommended one
 of which is to use virtual environments:
 === "Virtual environments"
    If you're installing Material for MkDocs with `pip`, the easiest way to make
    sure that you end up with the correct versions and without any
    incompatibility problems between packages it to use a [virtual
    environment][1]. First, ensure that you have a Python version of 3 or
    higher installed:
    ```
    python --version
    ```
    If you're good to go, create and activate a virtual environment with:
    ```
    python -m venv venv
    source ./venv/bin/activate
    ```
    Note that the second `venv` is the name of the folder where to create the
    virtual environment – you may choose it as you like. Your terminal should
    now print `(venv)` before the prompt and the `python` executable should be
    located inside the folder you just created.
    Next, [install Material for MkDocs][2] with `pip`, which will download and
    install all packages in the `venv` folder you just created, including MkDocs
    and its dependencies:
    ```
    pip install mkdocs-material
    ```
    Verify that MkDocs and Material for MkDocs were both installed correctly:
    ```
    mkdocs --version
    mkdocs serve --help
    ```
    MkDocs should list `material` as an option under the `--theme` flag. When
    you're finished working with MkDocs, you can exit the virtual environment
    with:
    ```
    deactivate
    ```
 === "User space"
    Provide the `--user` flag to the install command and `pip` will install the
    package in a user-site location. While this is not a global installation,
    it's still not isolated and may lead to problems when you use different
    versions of Material for MkDocs in other projects:
    ```
    pip install --user mkdocs-material
    ```
 === "Upgrade Python"
    Upgrade your Python installation by installing Python with [Homebrew][3].
    This should eliminate a lot of problems you will run into with `pip`. Yet,
    it's still not an isolated installation which may also lead to the same
    problems as installing in user space:
    ```
    brew upgrade python
    ```
  [1]: https://docs.python.org/3/tutorial/venv.html
  [2]: getting-started.md#with-pip-recommended
  [3]: https://brew.sh/
--- a/docs/upgrading.md
+++ b/docs/upgrading.md
@ -2,7 +2,7 @@
 template: overrides/main.html
 ---
-# Upgrading
+# How to upgrade
 Upgrade to the latest version with:
@ -10,7 +10,7 @@ Upgrade to the latest version with:
 pip install --upgrade mkdocs-material
 ```
-Inspect the currently installed version with:
+Show the currently installed version with:
 ```
 pip show mkdocs-material
--- a/material/assets/stylesheets/main.24c991ad.min.css
+++ b/material/assets/stylesheets/main.24c991ad.min.css
--- a/material/assets/stylesheets/main.24c991ad.min.css.map
+++ b/material/assets/stylesheets/main.24c991ad.min.css.map
--- a/material/assets/stylesheets/main.2ec5b002.min.css
+++ b/material/assets/stylesheets/main.2ec5b002.min.css
--- a/material/assets/stylesheets/main.2ec5b002.min.css.map
+++ b/material/assets/stylesheets/main.2ec5b002.min.css.map
--- a/material/base.html
+++ b/material/base.html
@ -39,7 +39,7 @@
      {% endif %}
    {% endblock %}
    {% block styles %}
-      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.24c991ad.min.css' | url }}">
+      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.2ec5b002.min.css' | url }}">
      {% if config.theme.palette %}
        {% set palette = config.theme.palette %}
        <link rel="stylesheet" href="{{ 'assets/stylesheets/palette.3f5d1f46.min.css' | url }}">
--- a/material/overrides/assets/stylesheets/main.5136944a.min.css
+++ b/material/overrides/assets/stylesheets/main.5136944a.min.css
--- a/material/overrides/assets/stylesheets/main.5136944a.min.css.map
+++ b/material/overrides/assets/stylesheets/main.5136944a.min.css.map
--- a/material/overrides/assets/stylesheets/main.9307850e.min.css
+++ b/material/overrides/assets/stylesheets/main.9307850e.min.css
--- a/material/overrides/assets/stylesheets/main.9307850e.min.css.map
+++ b/material/overrides/assets/stylesheets/main.9307850e.min.css.map
--- a/material/overrides/main.html
+++ b/material/overrides/main.html
@ -3,7 +3,7 @@
 -#}
 {% extends "base.html" %}
 {% block extrahead %}
-  <link rel="stylesheet" href="{{ 'overrides/assets/stylesheets/main.9307850e.min.css' | url }}">
+  <link rel="stylesheet" href="{{ 'overrides/assets/stylesheets/main.5136944a.min.css' | url }}">
 {% endblock %}
 {% block announce %}
  <a href="https://twitter.com/squidfunk">
--- a/mkdocs.yml
+++ b/mkdocs.yml
@ -51,7 +51,7 @@ theme:
  language: en
  features:
    - content.code.annotate
-    - content.tabs.link
+    # - content.tabs.link
    # - header.autohide
    # - navigation.expand
    - navigation.indexes
@ -91,18 +91,7 @@ plugins:
  - redirects:
      redirect_maps:
        changelog/insiders.md: insiders/changelog.md
-        extensions/admonition.md: reference/admonitions.md
+        upgrading.md: upgrade.md
        extensions/codehilite.md: reference/code-blocks.md
        extensions/footnotes.md: reference/footnotes.md
        extensions/metadata.md: reference/meta-tags.md
        extensions/permalinks.md: setup/setting-up-navigation.md #permalink
        extensions/pymdown.md: reference/admonitions.md
        plugins/revision-date.md: setup/adding-a-git-repository.md #revision-date
        plugins/search.md: setup/setting-up-site-search.md
        releases/4.md: upgrading.md #upgrading-from-4x-to-5x
        releases/5.md: upgrading.md #upgrading-from-3x-to-4x
        releases/changelog.md: changelog.md
        setup/adding-social-links.md: setup/setting-up-the-footer.md
        sponsorship.md: insiders/index.md
  - minify:
      minify_html: true
@ -174,13 +163,10 @@ nav:
    - Creating your site: creating-your-site.md
    - Publishing your site: publishing-your-site.md
    - Customization: customization.md
    - Troubleshooting: troubleshooting.md
    - Data privacy: data-privacy.md
    - License: license.md
-    - Releases:
+    - Changelog:
-      - Changelog: changelog.md
+      - changelog/index.md
-      - Upgrade guide: upgrading.md
+      - How to upgrade: upgrade.md
      - Deprecations: deprecations.md
  - Setup:
    - Changing the colors: setup/changing-the-colors.md
    - Changing the fonts: setup/changing-the-fonts.md
@ -196,6 +182,10 @@ nav:
    - Setting up the footer: setup/setting-up-the-footer.md
    - Adding a git repository: setup/adding-a-git-repository.md
    - Adding a comment system: setup/adding-a-comment-system.md
    - Extensions:
      - setup/extensions/index.md
      - Python Markdown: setup/extensions/python-markdown.md
      - Python Markdown Extensions: setup/extensions/python-markdown-extensions.md
  - Reference:
    - Abbreviations: reference/abbreviations.md
    - Admonitions: reference/admonitions.md
@ -211,7 +201,6 @@ nav:
    - Lists: reference/lists.md
    - MathJax: reference/mathjax.md
    - Meta tags: reference/meta-tags.md
    - Variables: reference/variables.md
  - Insiders:
    - insiders/index.md
    - Getting started:
--- 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;
    }
  }
 }
--- a/src/assets/stylesheets/main/layout/_content.scss
+++ b/src/assets/stylesheets/main/layout/_content.scss
@ -50,7 +50,6 @@
        // Adjust for right-to-left languages
        [dir="rtl"] & {
          margin-right: px2rem(24px);
          margin-left: px2rem(16px);
        }
      }
@ -60,7 +59,6 @@
        // Adjust for right-to-left languages
        [dir="rtl"] & {
          margin-right: px2rem(16px);
          margin-left: px2rem(24px);
        }
      }
--- a/src/base.html
+++ b/src/base.html
@ -78,7 +78,7 @@
      {% endif %}
    {% endblock %}
-    <!-- Theme-related stylesheets -->
+    <!-- Theme-related style sheets -->
    {% block styles %}
      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.css' | url }}" />
@ -136,7 +136,7 @@
      />
    {% endif %}
-    <!-- Custom stylesheets -->
+    <!-- Custom style sheets -->
    {% for path in config["extra_css"] %}
      <link rel="stylesheet" href="{{ path | url }}" />
    {% endfor %}
--- a/src/overrides/assets/stylesheets/main/_typeset.scss
+++ b/src/overrides/assets/stylesheets/main/_typeset.scss
@ -104,6 +104,18 @@
    }
  }
  // Deprecation
  .mdx-deprecated {
    opacity: 0.5;
    transition: opacity 250ms;
    // Deprecation on focus/hover
    &:focus-within,
    &:hover {
      opacity: 1;
    }
  }
  // Two-column layout
  .mdx-columns {
--- a/src/overrides/main.html
+++ b/src/overrides/main.html
@ -25,7 +25,7 @@
 <!-- Custom front matter -->
 {% block extrahead %}
-  <!-- Extra stylesheets (can't be set in mkdocs.yml due to content hash) -->
+  <!-- Extra style sheets (can't be set in mkdocs.yml due to content hash) -->
  <link
    rel="stylesheet"
    href="{{ 'overrides/assets/stylesheets/main.css' | url }}"