Updated documentation

Author: squidfunk

docs/customization.md

@@ -39,7 +39,7 @@ 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.
+additional style sheet file – you should see them almost instantly after saving.
 
   [2]: creating-your-site.md#previewing-as-you-write
 

docs/insiders/getting-started.md

@@ -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
-2. Click on [Generate a new token][5]
-3. Enter a name and select the [`repo`][6] scope
-4. Generate the token and store it in a safe place
+1.  Go to https://github.com/settings/tokens
+2.  Click on [Generate a new token][5]
+3.  Enter a name and select the [`repo`][6] scope
+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]
-2. Enable [GitHub Actions][9] on your fork[^2]
-3. Create a new personal access token[^3]
-    1. Go to https://github.com/settings/tokens
-    2. Click on [Generate a new token][5]
-    3. Enter a name and select the [`write:packages`][10] scope
-    4. Generate the token and store it in a safe place
-4. Add a [GitHub Actions secret][11] on your fork
-    1. Set the name to `GHCR_TOKEN`
-    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
-6. Install [Pull App][13] on your fork to stay in-sync with upstream
+1.  [Fork the Insiders repository][8]
+2.  Enable [GitHub Actions][9] on your fork[^2]
+3.  Create a new personal access token[^3]
+    1.  Go to https://github.com/settings/tokens
+    2.  Click on [Generate a new token][5]
+    3.  Enter a name and select the [`write:packages`][10] scope
+    4.  Generate the token and store it in a safe place
+4.  Add a [GitHub Actions secret][11] on your fork
+    1.  Set the name to `GHCR_TOKEN`
+    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
+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,

docs/reference/abbreviations.md

@@ -4,7 +4,7 @@ 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.
@@ -69,7 +69,7 @@ all abbreviations in a dedicated file[^1], and embedding it with the
 
 _Example_:
 
-=== ":octicons-file-code-16: docs/page.md"
+=== ":octicons-file-code-16: docs/example.md"
 
     ```` markdown
     The HTML specification is maintained by the W3C.

docs/reference/admonitions.md

@@ -404,37 +404,9 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
 
 ### Custom admonitions
 
-[:octicons-file-code-24: Source][Source] ·
-:octicons-mortar-board-24: Difficulty: _easy_
-
 If you want to add a custom admonition type, all you need is a color and an
-`*.svg` icon. Copy the icon's code from the [`.icons`][Custom icons] folder
-and add the following CSS to an [additional stylesheet]:
-
-``` 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][Custom animations].
+`*.svg` icon. Copy the icon's code from the [`.icons`][custom icons] folder
+and add the following CSS to an [additional style sheet]:
 
 <style>
   :root {
@@ -459,13 +431,45 @@ colors. [You can even add animations][Custom animations].
 
 _Example_:
 
-``` markdown
-!!! pied-piper "Pied Piper"
+=== ":octicons-file-code-16: docs/example.md"
 
-    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.
-```
+    ``` markdown
+    !!! pied-piper "Pied Piper"
+
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+        euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+        purus auctor massa, nec semper lorem quam in massa.
+    ```
+
+=== ":octicons-file-code-16: docs/stylesheets/admonitions.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/admonitions.css
+    ```
 
 _Result_:
 
@@ -475,7 +479,5 @@ _Result_:
     nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
     massa, nec semper lorem quam in massa.
 
-  [Source]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_admonition.scss
-  [Custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
-  [Custom animations]: icons-emojis.md#with-animations
-  [additional stylesheet]: ../customization.md#additional-css
+  [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
+  [additional style sheet]: ../customization.md#additional-css

docs/reference/buttons.md

@@ -30,38 +30,38 @@ See additional configuration options:
 ### Adding buttons
 
 In order to render a link as a button, suffix it with curly braces and add the
-`#!css .md-button` class selector to it. The button will receive the selected
+`.md-button` class selector to it. The button will receive the selected
 [primary color] and [accent color] if active.
 
 _Example_:
 
 ``` markdown
-[Don't click me](#){ .md-button }
+[Subscribe to our newsletter](#){ .md-button }
 ```
 
 _Result_:
 
-[Don't click me][Demo]{ .md-button }
+[Subscribe to our newsletter][Demo]{ .md-button }
 
   [primary color]: ../setup/changing-the-colors.md#primary-color
   [accent color]: ../setup/changing-the-colors.md#accent-color 
-  [Demo]: javascript:alert$.next("Hi!")
+  [Demo]: javascript:alert$.next("Demo")
 
 ### Adding primary buttons
 
 If you want to display a filled, primary button (like on the [landing page]
-of Material for MkDocs), add both, the `#!css .md-button` and
-`#!css .md-button--primary` CSS class selectors.
+of Material for MkDocs), add both, the `.md-button` and `.md-button--primary`
+CSS class selectors.
 
 _Example_:
 
 ``` markdown
-[Don't click me](#){ .md-button .md-button--primary }
+[Subscribe to our newsletter](#){ .md-button .md-button--primary }
 ```
 
 _Result_:
 
-[Don't click me][Demo]{ .md-button .md-button--primary }
+[Subscribe to our newsletter][Demo]{ .md-button .md-button--primary }
 
   [landing page]: ../index.md
 

docs/reference/code-blocks.md

@@ -63,7 +63,7 @@ theme:
     If you don't want to enable code annotations globally, because you don't
     like the automatic inlining behavior, you can enable them for a specific
     code block by using a slightly different syntax based on the
-    [Attribute List] extension:
+    [Attribute Lists] extension:
 
     ```` yaml
     ``` { .yaml .annotate }
@@ -75,7 +75,7 @@ theme:
     prefixed by a `.`.
 
   [Insiders]: ../insiders/index.md
-  [Attribute List]: ../setup/extensions/python-markdown.md#attribute-lists
+  [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
 
 ## Usage
 
@@ -270,11 +270,8 @@ last 4 years
 
 ### Custom syntax theme
 
-[:octicons-file-code-24: Source][Source] ·
-:octicons-mortar-board-24: Difficulty: _easy_
-
 If [Pygments] is used, Material for MkDocs provides the [styles for code blocks]
-[Source], which are built with a custom and well-balanced palette that works
+[colors], which are built with a custom and well-balanced palette that works
 equally well for both [color schemes]:
 
 - :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-number-color) " } `--md-code-hl-number-color`
@@ -298,26 +295,44 @@ Code block foreground, background and line highlight colors are defined via:
 
 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 stylesheet]:
+a new color by using an [additional style sheet]:
 
-``` css
-:root > * {
-  --md-code-hl-string-color: #0FF1CE;
-}
-```
+=== ":octicons-file-code-16: docs/stylesheets/colors.css"
+
+    ``` css
+    :root > * {
+      --md-code-hl-string-color: #0FF1CE;
+    }
+    ```
+
+=== ":octicons-file-code-16: mkdocs.yml"
+
+    ``` yaml
+    extra_css:
+      - stylesheets/colors.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 stylesheet]:
+override it as part of your [additional style sheet]:
 
-``` css
-.highlight .sb {
-  color: #0FF1CE;
-}
-```
+=== ":octicons-file-code-16: docs/stylesheets/colors.css"
+
+    ``` css
+    .highlight .sb {
+      color: #0FF1CE;
+    }
+    ```
+
+=== ":octicons-file-code-16: mkdocs.yml"
+
+    ``` yaml
+    extra_css:
+      - stylesheets/colors.css
+    ```
 
-  [Source]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
+  [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 stylesheet]: ../customization.md#additional-css
+  [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

docs/reference/content-tabs.md

@@ -52,18 +52,18 @@ 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.
 
-=== "With linking"
+=== ":octicons-check-circle-fill-16: Enabled"
 
-    [![With linking]][With linking]
+    [![linking enabled]][linking enabled]
 
-=== "Without linking"
+=== ":octicons-skip-16: Disabled"
 
-    [![Without linking]][Without linking]
+    [![linking disabled]][linking disabled]
 
   [Insiders]: ../insiders/index.md
   [instant loading]: ../setup/setting-up-navigation.md#instant-loading
-  [With linking]: ../assets/screenshots/content-tabs-link.png
-  [Without linking]: ../assets/screenshots/content-tabs.png
+  [linking enabled]: ../assets/screenshots/content-tabs-link.png
+  [linking disabled]: ../assets/screenshots/content-tabs.png
 
 ## Usage
 

docs/reference/data-tables.md

@@ -132,7 +132,7 @@ 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] via [additional JavaScript]:
 
-=== ":octicons-file-code-16: docs/javascripts/tables.js"
+=== ":octicons-file-code-16: docs/javascripts/tablesort.js"
 
     ``` js
     document$.subscribe(function() {
@@ -148,7 +148,7 @@ loading] via [additional JavaScript]:
     ``` 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] provides alternative comparison implementations like

docs/reference/diagrams.md

@@ -34,8 +34,8 @@ No further configuration is necessary. Advantages over a custom integration:
 
 - [x] Works with [instant loading] without any additional effort
 - [x] Diagrams automatically use fonts and colors defined in `mkdocs.yml`[^1]
-- [x] Fonts and colors can be customized with [additional stylesheets]
-- [x] Support for both, light and dark color schemes
+- [x] Fonts and colors can be customized with [additional style sheets]
+- [x] Support for both, light and dark color schemes – _try it on this page!_
 
   [^1]:
     While all [Mermaid.js] features should work out-of-the-box, Material for
@@ -45,7 +45,7 @@ No further configuration is necessary. Advantages over a custom integration:
 
   [Insiders]: ../insiders/index.md
   [instant loading]: ../setup/setting-up-navigation.md#instant-loading
-  [additional stylesheets]: ../customization.md#additional-css
+  [additional style sheets]: ../customization.md#additional-css
 
 ## Usage
 

docs/reference/footnotes.md

@@ -4,16 +4,16 @@ template: overrides/main.html
 
 # Footnotes
 
-Footnotes are a great way to add references to supplemental or additional
-information to a specific word, phrase or sentence without interrupting the
-flow of a document. Material for MkDocs provides the ability to define and
-render footnotes.
+Footnotes are a great way to add supplemental or additional information to a
+specific word, phrase or sentence without interrupting the flow of a document.
+Material for MkDocs provides the ability to define, reference and render
+footnotes.
 
 ## Configuration
 
-This configuration adds the ability to define footnotes inline with the content,
-which are then rendered below all Markdown content of a document. Add the 
-following lines to `mkdocs.yml`:
+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
+`mkdocs.yml`:
 
 ``` yaml
 markdown_extensions: