Updated documentation

CHANGELOG

@@ -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

docs/data-privacy.md

@@ -19,7 +19,7 @@ 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
+  [3]: setup/changing-the-fonts.md#autoloading
 
 ### Google Analytics and Disqus
 

docs/reference/admonitions.md

@@ -35,10 +35,11 @@ See additional configuration options:
 ### Admonition icons
 
 [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-2.4.0 ... present][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. Add the following lines to `mkdocs.yml`:
+to any icon bundled with the theme, or even a [custom icon]. Add the following
+lines to `mkdocs.yml`:
 
 ``` yaml
 theme:
@@ -106,6 +107,7 @@ theme:
         [![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
@@ -234,8 +236,8 @@ _Result_:
 
 ### Inline blocks
 
-:octicons-beaker-24: Experimental ·
+[:octicons-tag-24: 7.0.0][Inline support] ·
-[:octicons-tag-24: 7.0.0 ... present][Inline support]
+:octicons-beaker-24: Experimental
 
 Admonitions can also be rendered as inline blocks (i.e. for sidebars), placing
 them to the right using the `inline` + `end` modifiers, or to the left using
@@ -441,7 +443,7 @@ _Example_:
         purus auctor massa, nec semper lorem quam in massa.
     ```
 
-=== ":octicons-file-code-16: docs/stylesheets/admonitions.css"
+=== ":octicons-file-code-16: docs/stylesheets/extra.css"
 
     ``` css
     :root {
@@ -468,7 +470,7 @@ _Example_:
 
     ``` yaml
     extra_css:
-      - stylesheets/admonitions.css
+      - stylesheets/extra.css
     ```
 
 _Result_:

docs/reference/code-blocks.md

@@ -40,9 +40,9 @@ See additional configuration options:
 ### 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 ·
+:octicons-beaker-24: Experimental
-[:octicons-tag-24: insiders-2.2.0 ... present][Insiders]
 
 Code annotations offer a comfortable and friendly way to attach arbitrary
 content to specific sections of code blocks by adding numeric markers in block
@@ -297,7 +297,7 @@ Let's say you want to change the color of `#!js "strings"`. While there are
 several [types of string tokens], they use the same color. You can assign
 a new color by using an [additional style sheet]:
 
-=== ":octicons-file-code-16: docs/stylesheets/colors.css"
+=== ":octicons-file-code-16: docs/stylesheets/extra.css"
 
     ``` css
     :root > * {
@@ -309,14 +309,14 @@ a new color by using an [additional style sheet]:
 
     ``` yaml
     extra_css:
-      - stylesheets/colors.css
+      - stylesheets/extra.css
     ```
 
 If you want to tweak a specific type of string, e.g. ``#!js `backticks` ``, you
 can lookup the specific CSS class name in the [syntax theme definition], and
 override it as part of your [additional style sheet]:
 
-=== ":octicons-file-code-16: docs/stylesheets/colors.css"
+=== ":octicons-file-code-16: docs/stylesheets/extra.css"
 
     ``` css
     .highlight .sb {
@@ -328,7 +328,7 @@ override it as part of your [additional style sheet]:
 
     ``` yaml
     extra_css:
-      - stylesheets/colors.css
+      - stylesheets/extra.css
     ```
 
   [colors]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss

docs/reference/content-tabs.md

@@ -33,9 +33,9 @@ See additional configuration options:
 ### 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 ·
+:octicons-beaker-24: Experimental
-[:octicons-tag-24: insiders-2.9.0 ... present][Insiders]
 
 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 
@@ -54,16 +54,16 @@ integrated with [instant loading] and persisted across page loads.
 
 === ":octicons-check-circle-fill-16: Enabled"
 
-    [![linking enabled]][linking enabled]
+    [![content.tabs.link enabled]][content.tabs.link enabled]
 
 === ":octicons-skip-16: Disabled"
 
-    [![linking disabled]][linking disabled]
+    [![content.tabs.link disabled]][content.tabs.link disabled]
 
   [Insiders]: ../insiders/index.md
   [instant loading]: ../setup/setting-up-navigation.md#instant-loading
-  [linking enabled]: ../assets/screenshots/content-tabs-link.png
+  [content.tabs.link enabled]: ../assets/screenshots/content-tabs-link.png
-  [linking disabled]: ../assets/screenshots/content-tabs.png
+  [content.tabs.link disabled]: ../assets/screenshots/content-tabs.png
 
 ## Usage
 

docs/reference/diagrams.md

@@ -14,8 +14,8 @@ popular and flexible solution for drawing diagrams.
 ## Configuration
 
 [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
-:octicons-beaker-24: Experimental ·
+[:octicons-tag-24: insiders-1.15.0][Insiders] ·
-[:octicons-tag-24: insiders-1.15.0 ... present][Insiders]
+:octicons-beaker-24: Experimental
 
 This configuration enables native support for [Mermaid.js] diagrams. Material
 for MkDocs will automatically initialize the JavaScript runtime when a page 

docs/reference/icons-emojis.md

@@ -57,7 +57,6 @@ See additional configuration options:
   [Material Design]: https://materialdesignicons.com/
   [FontAwesome]: https://fontawesome.com/icons?d=gallery&m=free
   [Octicons]: https://octicons.github.com/
-  [additional icons]: ../setup/changing-the-logo-and-icons.md#additional-icons
   [Emoji]: ../setup/extensions/python-markdown-extensions.md#emoji
   [Emoji with custom icons]: ../setup/extensions/python-markdown-extensions.md#custom-icons
 
@@ -136,7 +135,7 @@ _Example_:
     - :fontawesome-brands-facebook:{ .facebook } – Facebook
     ```
 
-=== ":octicons-file-code-16: docs/stylesheets/icons.css"
+=== ":octicons-file-code-16: docs/stylesheets/extra.css"
 
     ``` css
     .medium {
@@ -154,7 +153,7 @@ _Example_:
 
     ``` yaml
     extra_css:
-      - stylesheets/icons.css
+      - stylesheets/extra.css
     ```
 
 _Result_:
@@ -181,7 +180,7 @@ _Example_:
     :octicons-heart-fill-24:{ .heart }
     ```
 
-=== ":octicons-file-code-16: docs/stylesheets/icons.css"
+=== ":octicons-file-code-16: docs/stylesheets/extra.css"
 
     ``` css
     @keyframes heart {
@@ -201,7 +200,7 @@ _Example_:
 
     ``` yaml
     extra_css:
-      - stylesheets/icons.css
+      - stylesheets/extra.css
     ```
 
 _Result_:

docs/reference/meta-tags.md

@@ -34,9 +34,8 @@ See additional configuration options:
 
 ### Setting the page title
 
-When [Metadata] is enabled, the page title can be overridden on a per-document
+When [Metadata] is enabled, the page title can be overridden for a document with
-basis with custom front matter. Add the following lines at the top of a Markdown
+some custom front matter. Add the following lines at the top of a Markdown file:
-file:
 
 ``` bash
 ---
@@ -57,9 +56,9 @@ title: Lorem ipsum dolor sit amet # (1)
 
 ### Setting the page description
 
-When [Metadata] is enabled, the page description can also be overridden on a
+When [Metadata] is enabled, the page description can be overridden for a
-per-document basis with custom front matter. Add the following lines at the top
+document with custom front matter. Add the following lines at the top of a
-of a Markdown file:
+Markdown file:
 
 ``` bash
 ---
@@ -77,8 +76,8 @@ document `head` for the current page to the provided value.
 
 ### Adding a web app manifest
 
+[:octicons-tag-24: 3.1.0][manifest support] ·
 :octicons-archive-24: Deprecated ·
-[:octicons-tag-24: 3.1.0 ... present][web app manifest support] ·
 :octicons-trash-24: 8.0.0
 
 A [web app manifest] is a simple JSON file that specifies how your web
@@ -94,7 +93,7 @@ extra:
     can be achieved with [theme extension].
 
   [web app manifest]: https://developers.google.com/web/fundamentals/web-app-manifest/
-  [web app manifest support]: https://github.com/squidfunk/mkdocs-material/releases/tag/3.1.0
+  [manifest support]: https://github.com/squidfunk/mkdocs-material/releases/tag/3.1.0
   [theme extension]: ../customization.md#extending-the-theme
 
 </div>

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,113 @@ 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 style sheet][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
+    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 +322,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

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]: ../data-privacy.md
+  [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 style sheet][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

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:
@@ -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]][Language selector]
+
+  [alternate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.0.0
+  [site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
+  [ISO 639-1 language code]: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
+  [Language selector]: ../assets/screenshots/language-selection.png
 
 ### 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,46 @@ 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 your 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 your language as fallback -->
-{% import "partials/languages/en.html" as fallback %}
+    {% import "partials/languages/" ~ config.theme.language ~ ".html" as fallback %}
-{% macro override(key) %}{{ {
+    {% macro override(key) %}{{ {
-  "toc.title": "On this page"
+      "toc.title": "On this page" <!-- (1) -->
-}[key] }}{% endmacro %}
+    }[key] }}{% endmacro %}
 
-<!-- Re-export the translation macro for mkbuild-material to use -->
+    <!-- Re-export translations -->
-{% macro t(key) %}{{ override(key) or fallback.t(key) }}{% endmacro %}
+    {% macro t(key) %}{{ override(key) or fallback.t(key) }}{% endmacro %}
-```
+    ```
 
-Then, add the following lines to `mkdocs.yml`:
+    1.  Check the [list of available languages], pick the translation you want
+        to override for your language and add them here.
 
-``` yaml
+=== ":octicons-file-code-16: mkdocs.yml"
-theme:
-  language: en-custom
-```
 
-  [9]: ../customization.md#extending-the-theme
+    ``` 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/

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/

docs/setup/extensions/index.md

@@ -11,8 +11,8 @@ 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]: python-markdown.md
-  [Python Markdown Extensions]: #python-markdown-extensions.md
+  [Python Markdown Extensions]: python-markdown-extensions.md
 
 ## Supported extensions
 

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

@@ -15,8 +15,8 @@ installed with a supported version.
 
 ### Arithmatex
 
-[:octicons-workflow-24: Extension][Arithmatex] ·
+[:octicons-tag-24: 1.0.0][Arithmatex support] ·
-[:octicons-tag-24: 1.0.0 ... present][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
@@ -87,8 +87,8 @@ See reference for usage:
 
 ### BetterEm
 
-[:octicons-workflow-24: Extension][BetterEm] ·
+[:octicons-tag-24: 0.1.0][BetterEm support] ·
-[:octicons-tag-24: 0.1.0 ... present][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_`
@@ -108,8 +108,8 @@ documentation][BetterEm] for more information.
 
 ### Caret, Mark & Tilde
 
-[:octicons-workflow-24: Extension][Caret] ·
+[:octicons-tag-24: 1.0.0][Caret support] ·
-[:octicons-tag-24: 1.0.0 ... present][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
@@ -140,8 +140,8 @@ See reference for usage:
 
 ### Critic
 
-[:octicons-workflow-24: Extension][Critic] ·
+[:octicons-tag-24: 1.0.0][Critic support] ·
-[:octicons-tag-24: 1.0.0 ... present][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
@@ -195,8 +195,8 @@ See reference for usage:
 
 ### Details
 
-[:octicons-workflow-24: Extension][Details] ·
+[:octicons-tag-24: 1.9.0][Details support] ·
-[:octicons-tag-24: 1.9.0 ... present][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
@@ -218,8 +218,8 @@ No configuration options are available. See reference for usage:
 
 ### Emoji
 
-[:octicons-workflow-24: Extension][Emoji] ·
+[:octicons-tag-24: 1.0.0][Emoji support] ·
-[:octicons-tag-24: 1.0.0 ... present][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`:
@@ -297,13 +297,14 @@ See reference for usage:
 
 ### Highlight
 
+[:octicons-tag-24: 5.0.0][Highlight support] ·
 [:octicons-workflow-24: Extension][Highlight] ·
-[:octicons-tag-24: 5.0.0 ... present][Highlight support] ·
 :octicons-zap-24: Supersedes [CodeHilite]
 
 The [Highlight] extension adds support for syntax highlighting of code blocks
-(with the help of [SuperFences][SuperFences #]) and inline code blocks (with
+(with the help of [SuperFences][pymdownx.superfences]) and inline code blocks
-the help of [InlineHilite][InlineHilite #]). Enable it via `mkdocs.yml`:
+(with the help of [InlineHilite][pymdownx.inlinehilite]). Enable it via
+`mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:
@@ -311,7 +312,7 @@ markdown_extensions:
   - pymdownx.superfences # (1)
 ```
 
-1.  [Highlight] is used by the [SuperFences][SuperFences #] extension to
+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.
 
@@ -410,8 +411,8 @@ See reference for usage:
   [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
-  [SuperFences #]: #superfences
+  [pymdownx.superfences]: #superfences
-  [InlineHilite #]: #inlinehilite
+  [pymdownx.inlinehilite]: #inlinehilite
   [Pygments]: https://pygments.org
   [additional CSS]: ../../customization.md#additional-css
   [Highlight.js]: https://highlightjs.org/
@@ -422,12 +423,12 @@ See reference for usage:
 
 ### InlineHilite
 
-[:octicons-workflow-24: Extension][InlineHilite] ·
+[:octicons-tag-24: 5.0.0][InlineHilite support] ·
-[:octicons-tag-24: 5.0.0 ... present][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][Highlight #] extension, from which
+blocks. It's built on top of the [Highlight][pymdownx.highlight] extension, from
-it sources its configuration. Enable it via `mkdocs.yml`:
+which it sources its configuration. Enable it via `mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:
@@ -447,13 +448,13 @@ See reference for usage:
   [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
-  [Highlight #]: #highlight
+  [pymdownx.highlight]: #highlight
   [Highlighting inline code blocks]: ../../reference/code-blocks.md#highlighting-inline-code-blocks
 
 ### Keys
 
-[:octicons-workflow-24: Extension][Keys] ·
+[:octicons-tag-24: 1.0.0][Keys support] ·
-[:octicons-tag-24: 1.0.0 ... present][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`:
@@ -479,8 +480,8 @@ See reference for usage:
 
 ### SmartSymbols
 
-[:octicons-workflow-24: Extension][SmartSymbols] ·
+[:octicons-tag-24: 0.1.0][SmartSymbols support] ·
-[:octicons-tag-24: 0.1.0 ... present][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
@@ -500,8 +501,8 @@ documentation][SmartSymbols] for guidance.
 
 ### Snippets
 
-[:octicons-workflow-24: Extension][Snippets] ·
+[:octicons-tag-24: 0.1.0][Snippets support] ·
-[:octicons-tag-24: 0.1.0 ... present][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
@@ -528,8 +529,8 @@ See reference for usage:
 
 ### SuperFences
 
+[:octicons-tag-24: 0.1.0][SuperFences support] ·
 [:octicons-workflow-24: Extension][SuperFences] ·
-[:octicons-tag-24: 0.1.0 ... present][SuperFences support] ·
 :octicons-zap-24: Supersedes [Fenced Code Blocks]
 
 The [SuperFences] extension allows for arbitrary nesting of code and content
@@ -587,8 +588,8 @@ See reference for usage:
 
 ### Tabbed
 
-[:octicons-workflow-24: Extension][Tabbed] ·
+[:octicons-tag-24: 5.0.0][Tabbed support] ·
-[:octicons-tag-24: 5.0.0 ... present][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
@@ -636,8 +637,8 @@ See reference for usage:
 
 ### Tasklist
 
-[:octicons-workflow-24: Extension][Tasklist] ·
+[:octicons-tag-24: 1.0.0][Tasklist support] ·
-[:octicons-tag-24: 1.0.0 ... present][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
@@ -686,6 +687,5 @@ See reference for usage:
   [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 #]: #tasklist
   [Tasklist specification]: https://github.github.com/gfm/#task-list-items-extension-
   [Using task lists]: ../../reference/lists.md#using-task-lists

docs/setup/extensions/python-markdown.md

@@ -15,8 +15,8 @@ reference for which features they need to be enabled.
 
 ### Abbreviations
 
-[:octicons-workflow-24: Extension][Abbreviations] ·
+[:octicons-tag-24: 1.0.0][Abbreviations support] ·
-[:octicons-tag-24: 1.0.0 ... present][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
@@ -39,8 +39,8 @@ No configuration options are available. See reference for usage:
 
 ### Admonition
 
-[:octicons-workflow-24: Extension][Admonition] ·
+[:octicons-tag-24: 0.1.0][Admonition support] ·
-[:octicons-tag-24: 0.1.0 ... present][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
@@ -67,8 +67,8 @@ No configuration options are available. See reference for usage:
 
 ### Attribute Lists
 
-[:octicons-workflow-24: Extension][Attribute Lists] ·
+[:octicons-tag-24: 0.1.0][Attribute Lists support] ·
-[:octicons-tag-24: 0.1.0 ... present][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
@@ -96,8 +96,8 @@ No configuration options are available. See reference for usage:
 
 ### Definition Lists
 
-[:octicons-workflow-24: Extension][Definition Lists] ·
+[:octicons-tag-24: 1.1.0][Definition Lists support] ·
-[:octicons-tag-24: 1.1.0 ... present][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
@@ -119,8 +119,8 @@ No configuration options are available. See reference for usage:
 
 ### Footnotes
 
-[:octicons-workflow-24: Extension][Footnotes] ·
+[:octicons-tag-24: 1.0.0][Footnotes support] ·
-[:octicons-tag-24: 1.0.0 ... present][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`:
@@ -142,8 +142,8 @@ No configuration options are supported. See reference for usage:
 
 ### Metadata
 
-[:octicons-workflow-24: Extension][Metadata] ·
+[:octicons-tag-24: 1.0.0][Metadata support] ·
-[:octicons-tag-24: 1.0.0 ... present][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.
@@ -170,8 +170,8 @@ No configuration options are available. See reference for usage:
 
 ### Markdown in HTML
 
-[:octicons-workflow-24: Extension][Markdown in HTML] ·
+[:octicons-tag-24: 0.1.0][Markdown in HTML support] ·
-[:octicons-tag-24: 0.1.0 ... present][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
@@ -198,8 +198,8 @@ No configuration options are available. See reference for usage:
 
 ### Table of Contents
 
-[:octicons-workflow-24: Extension][Table of Contents] ·
+[:octicons-tag-24: 0.1.0][Table of Contents support] ·
-[:octicons-tag-24: 0.1.0 ... present][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 
@@ -292,8 +292,8 @@ own risk.
 
 ### Tables
 
-[:octicons-workflow-24: Extension][Tables] ·
+[:octicons-tag-24: 0.1.0][Tables support] ·
-[:octicons-tag-24: 0.1.0 ... present][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
@@ -322,8 +322,8 @@ should be considered.
 
 ### Fenced Code Blocks
 
-[:octicons-workflow-24: Extension][Fenced Code Blocks] ·
+[:octicons-tag-24: 0.1.0][Fenced Code Blocks support] ·
-[:octicons-tag-24: 0.1.0 ... present][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 
@@ -335,8 +335,8 @@ nesting, and is therefore recommended.
 
 ### CodeHilite
 
-[:octicons-workflow-24: Extension][CodeHilite] ·
+[:octicons-tag-24: 0.1.0 ... 5.5.14][CodeHilite support] ·
-[: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 

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:
@@ -84,23 +84,23 @@ theme:
 
 === ":octicons-check-circle-fill-16: Enabled"
 
-    [![With tabs][8]][8]
+    [![navigation.tabs enabled]][navigation.tabs enabled]
 
 === ":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`:
 
@@ -113,22 +113,22 @@ theme:
 
 === ":octicons-check-circle-fill-16: Enabled"
 
-    [![With sticky tabs][11]][11]
+    [![navigation.tabs.sticky enabled]][navigation.tabs.sticky enabled]
 
 === ":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`:
 
@@ -140,25 +140,27 @@ theme:
 
 === ":octicons-check-circle-fill-16: Enabled"
 
-    [![With sections][14]][14]
+    [![navigation.sections enabled]][navigation.sections enabled]
 
 === ":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`:
 
@@ -170,21 +172,23 @@ theme:
 
 === ":octicons-check-circle-fill-16: Enabled"
 
-    [![With expansion][15]][15]
+    [![navigation.expand enabled]][navigation.expand enabled]
 
 === ":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`:
 
@@ -196,11 +200,11 @@ theme:
 
 === ":octicons-check-circle-fill-16: Enabled"
 
-    [![With expansion][17]][17]
+    [![navigation.indexes enabled]][navigation.indexes enabled]
 
 === ":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,128 +219,21 @@ 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
 
-### Back-to-top button
+### Integrated table of contents
 
-[:octicons-file-code-24: Source][20] ·
+[:octicons-tag-24: 6.2.0][toc.integrate support] ·
 :octicons-unlock-24: Feature flag
 
-A _back-to-top button_ can be shown when the user, after scrolling down, starts
+When navigation integration for the table of contents is enabled, it is always
-to scroll up again. It's rendered centered and just below the header. Add the
+rendered as part of the navigation sidebar on the left. Add the following lines
-following lines to `mkdocs.yml`:
+to `mkdocs.yml`:
-
-``` yaml
-theme:
-  features:
-    - navigation.top
-```
-
-[![back-to-top button][21]][21]
-
-  [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:
@@ -346,29 +243,44 @@ theme:
 
 === ":octicons-check-circle-fill-16: Enabled"
 
-    [![Integrate table of contents][27]][27]
+    [![toc.integrate enabled]][toc.integrate enabled]
 
 === ":octicons-skip-16: Disabled"
 
-    [![Separate table of contents][8]][8]
+    [![toc.integrate disabled]][toc.integrate disabled]
 
-  [26]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_nav.scss
+This feature flag is not compatible with [`navigation.indexes`]
-  [27]: ../assets/screenshots/toc-integrate.png
+[navigation.indexes].
 
-The content section will now always stretch to the right side, resulting in
+  [toc.integrate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
-more space for your content. This feature flag can be combined with all other
+  [toc.integrate enabled]: ../assets/screenshots/toc-integrate.png
-feature flags, e.g. [tabs][1] and [sections][2]. 
+  [toc.integrate disabled]: ../assets/screenshots/navigation-tabs.png
+  [navigation.indexes]: #section-index-pages
+
+### Back-to-top button
+
+[: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
+to scroll up again. It's rendered centered and just below the header. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+  features:
+    - navigation.top
+```
+
+  [navigation.top support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
 
 ## 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,29 +295,25 @@ 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:
 
@@ -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 style sheet][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

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

@@ -18,7 +18,7 @@ and extendable [cookie consent][2].
 
 :octicons-hash-24: Setting ·
 :octicons-milestone-24: Default: _none_ ·
-[:octicons-tag-24: 7.1.8 ... present][Google Analytics support]
+[:octicons-tag-24: 7.1.8][Google Analytics support]
 
 Material for MkDocs integrates with both, Google Analytics 4 and the now phasing
 out Universal Analytics (`UA-*`). Depending on the prefix of the property, add
@@ -68,7 +68,7 @@ yourself, [this tutorial][4] might be a good start._
 [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
 :octicons-hash-24: Setting ·
 :octicons-milestone-24: Default: _none_ ·
-[:octicons-tag-24: insiders-2.10.0 ... present][Insiders]
+[:octicons-tag-24: insiders-2.10.0][Insiders]
 
 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

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

@@ -39,7 +39,7 @@ The following options are supported:
 
 `lang`{ #lang }
 
-:   :octicons-milestone-24: Default: _automatically set_ – This option allows
+:   :octicons-milestone-24: Default: _auto_ – This option allows
     to include the language-specific stemmers provided by [lunr-languages][5].
     Note that Material for MkDocs will set this automatically based on the
     [site language][6], but it may be overridden, e.g. to support multiple
@@ -100,7 +100,7 @@ The following options are supported:
 
 `separator`{ #separator }
 
-:   :octicons-milestone-24: Default: _automatically set_ – The separator for
+:   :octicons-milestone-24: Default: _auto_ – The separator for
     indexing and query tokenization can be customized, making it possible to
     index parts of words separated by other characters than whitespace and `-`,
     e.g. by including `.`:
@@ -148,7 +148,7 @@ Use them at your own risk._
 
 :octicons-unlock-24: Feature flag ·
 :octicons-beaker-24: Experimental ·
-[:octicons-tag-24: 7.2.0 ... present][Search suggestions support]
+[:octicons-tag-24: 7.2.0][Search suggestions support]
 
 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
@@ -175,7 +175,7 @@ Searching for [:octicons-search-24: search su][9] yields ^^search suggestions^^
 
 :octicons-unlock-24: Feature flag ·
 :octicons-beaker-24: Experimental ·
-[:octicons-tag-24: 7.2.0 ... present][Search highlighting support]
+[:octicons-tag-24: 7.2.0][Search highlighting support]
 
 When _search highlighting_ is enabled and a user clicks on a search result,
 Material for MkDocs will highlight all occurrences after following the link.
@@ -200,7 +200,7 @@ Searching for [:octicons-search-24: code blocks][12] yields:
 
 :octicons-unlock-24: Feature flag ·
 :octicons-beaker-24: Experimental ·
-[:octicons-tag-24: 7.2.0 ... present][Search highlighting support]
+[:octicons-tag-24: 7.2.0][Search highlighting support]
 
 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
@@ -250,7 +250,7 @@ For setup instructions, refer to the [official documentation][19].
 
 [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
 :octicons-note-24: Metadata ·
-[:octicons-tag-24: insiders-2.8.0 ... present][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
@@ -275,7 +275,7 @@ search:
 [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
 :octicons-note-24: Metadata ·
 :octicons-beaker-24: Experimental ·
-[:octicons-tag-24: insiders-3.1.0 ... present][Insiders]
+[:octicons-tag-24: insiders-3.1.0][Insiders]
 
 #### Excluding pages
 

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

@@ -26,7 +26,7 @@ MkDocs can generate beautiful social cards automatically, using the [colors][1],
 [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
 :octicons-cpu-24: Plugin ·
 :octicons-beaker-24: Experimental ·
-[:octicons-tag-24: insiders-2.12.0 ... present][Insiders]
+[:octicons-tag-24: insiders-2.12.0][Insiders]
 
 The [built-in social cards plugin][4] generates a social card image for every
 page and adds the necessary meta tags, so it's displayed on social media when
@@ -57,8 +57,8 @@ are available:
 
 `cards_color`{ #cards-color } :material-new-box:
 
-:   :octicons-milestone-24: Default: _automatically set based on [primary
+:   :octicons-milestone-24: Default: [`primary
-    color][8]_ – This option specifies which colors to use for the background
+    color`][8]_ – This option specifies which colors to use for the background
     `fill` and foreground `text` when generating the social card.
 
     ``` yaml

docs/setup/setting-up-tags.md

@@ -16,7 +16,7 @@ can help to discover relevant information faster.
 [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
 :octicons-cpu-24: Plugin ·
 :octicons-beaker-24: Experimental ·
-[:octicons-tag-24: insiders-2.7.0 ... present][Insiders]
+[:octicons-tag-24: insiders-2.7.0][Insiders]
 
 The [built-in tags plugin][1] 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

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

@@ -17,7 +17,7 @@ configured via `mkdocs.yml`.
 
 :octicons-hash-24: Setting ·
 :octicons-milestone-24: Default: _none_ ·
-[:octicons-tag-24: 1.0.0 ... present][Social links support]
+[:octicons-tag-24: 1.0.0][Social links support]
 
 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` 
@@ -30,7 +30,7 @@ extra:
       link: https://twitter.com/squidfunk
 ```
 
-For each entry, the following fields are available:
+For each entry, the following settings are available:
 
 `icon`{ #icon }
 
@@ -95,7 +95,7 @@ For each entry, the following fields are available:
 
 :octicons-hash-24: Setting ·
 :octicons-milestone-24: Default: _none_ ·
-[:octicons-tag-24: 0.1.0 ... present][Copyright notice support]
+[:octicons-tag-24: 0.1.0][Copyright notice support]
 
 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`:
@@ -111,7 +111,7 @@ copyright: Copyright © 2016 - 2020 Martin Donath
 
 :octicons-hash-24: Setting ·
 :octicons-milestone-24: Default: `true` ·
-[:octicons-tag-24: 7.3.0 ... present][Generator notice support]
+[:octicons-tag-24: 7.3.0][Generator notice support]
 
 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

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

@@ -17,7 +17,7 @@ It also includes the [search bar][1] and a place to display your project's
 ### Automatic hiding
 
 :octicons-unlock-24: Feature flag ·
-[:octicons-tag-24: 6.2.0 ... present][Automatic hiding support]
+[:octicons-tag-24: 6.2.0][Automatic hiding support]
 
 When _autohiding_ is enabled, the header is automatically hidden when the
 user scrolls past a certain threshold, leaving more space for content. Add the
@@ -36,7 +36,7 @@ theme:
 ### Announcement bar
 
 :octicons-file-symlink-file-24: Customization ·
-[:octicons-tag-24: 5.0.0 ... present][Announcement bar support]
+[:octicons-tag-24: 5.0.0][Announcement bar support]
 
 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

docs/setup/setting-up-versioning.md

@@ -70,7 +70,7 @@ Material for MkDocs._
 
 [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
 :octicons-file-symlink-file-24: Customization ·
-[:octicons-tag-24: insiders-2.5.0 ... present][Insiders]
+[:octicons-tag-24: insiders-2.5.0][Insiders]
 
 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],
@@ -119,7 +119,7 @@ Make sure that this matches the [default version][11].
 ### Stay on page
 
 [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-2.6.0 ... present][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