Updated documentation

docs/reference/footnotes.md

@@ -63,7 +63,7 @@ _Example_:
 
 _Result_:
 
-[Jump to footnote at the bottom of the page](#fn:1)
+[:octicons-arrow-down-24: Jump to footnote](#fn:1)
 
   [^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
@@ -87,4 +87,4 @@ _Result_:
     nulla. Curabitur feugiat, tortor non consequat finibus, justo purus
     auctor massa, nec semper lorem quam in massa.
 
-[Jump to footnote at the bottom of the page](#fn:2)
+[:octicons-arrow-down-24: Jump to footnote](#fn:2)

docs/setup/adding-a-git-repository.md

@@ -198,7 +198,8 @@ The following configuration options are supported:
 
 `enable_creation_date`{ #enable-creation-date }
 
-:   :octicons-milestone-24: Default: `false` – Enables the display of the
+:   [:octicons-tag-24: 7.1.4][enable_creation_date support] ·
+    :octicons-milestone-24: Default: `false` – Enables the display of the
     creation date of the file associated with the page next to the last updated
     date at the bottom of the page:
 
@@ -215,3 +216,4 @@ them at your own risk.
 
   [git-revision-date-localized support]: https://github.com/squidfunk/mkdocs-material/releases/tag/4.6.0
   [git-revision-date-localized]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
+  [enable_creation_date support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.4

docs/setup/changing-the-language.md

@@ -76,7 +76,7 @@ The following languages are supported:
 - `zh` – Chinese (Simplified)
 - `zh-Hant` – Chinese (Traditional)
 - `zh-TW` – Chinese (Taiwanese)
-- [Add language](https://bit.ly/38F5RCa)
+- [Add language]
 
 </div>
 
@@ -85,6 +85,7 @@ the default slug function works. Consider using a [Unicode-aware slug function].
 
   [language support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.12.0
   [Unicode-aware slug function]: setting-up-navigation.md#slugify
+  [Add language]: https://bit.ly/38F5RCa
 
 ### Site language selector
 

docs/setup/setting-up-navigation.md

@@ -231,7 +231,7 @@ This feature flag is not compatible with [`toc.integrate`][toc.integrate].
 [:octicons-tag-24: 6.2.0][toc.integrate support] ·
 :octicons-unlock-24: Feature flag
 
-When navigation integration for the table of contents is enabled, it is always
+When navigation integration for the [table of contents] is enabled, it is always
 rendered as part of the navigation sidebar on the left. Add the following lines
 to `mkdocs.yml`:
 
@@ -252,6 +252,7 @@ theme:
 This feature flag is not compatible with [`navigation.indexes`]
 [navigation.indexes].
 
+  [table of contents]: extensions/python-markdown.md#table-of-contents
   [toc.integrate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
   [toc.integrate enabled]: ../assets/screenshots/toc-integrate.png
   [toc.integrate disabled]: ../assets/screenshots/navigation-tabs.png

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

@@ -9,25 +9,20 @@ search:
 Material for MkDocs provides an excellent, client-side search implementation,
 omitting the need for the integration of third-party services, which might
 be tricky to integrate to be compliant with data privacy regulations. Moreover,
-with some effort, search can be made available [offline][1].
+with some effort, search can be made available [offline].
 
-  [1]: #offline-search
+  [offline]: #offline-search
 
 ## Configuration
 
 ### Built-in search
 
-!!! danger "[Search: better, faster, smaller](../blog/2021/search-better-faster-smaller.md)"
+[:octicons-tag-24: 0.1.0][search support] ·
+:octicons-cpu-24: Plugin
 
-    We rebuilt the search plugin and integration from the ground up, introducing [rich search previews](../blog/2021/search-better-faster-smaller.md#rich-search-previews), much better [tokenizer support](../blog/2021/search-better-faster-smaller.md#tokenizer-lookahead), [more accurate highlighting](../blog/2021/search-better-faster-smaller.md#accurate-highlighting) and much more. Read the [blog article](../blog/2021/search-better-faster-smaller.md) to learn more about our new search implementation. Start using it immediately by [becoming a sponsor][20]!
+The built-in search plugin integrates seamlessly with Material for MkDocs,
-
+adding multilingual client-side search with [lunr] and [lunr-languages]. It's 
-[:octicons-file-code-24: Source][2] ·
+enabled by default, but must be re-added to `mkdocs.yml` when other plugins
-[:octicons-cpu-24: Plugin][3] ·
-[:octicons-heart-fill-24:{ .mdx-heart } Better in Insiders][20]{ .mdx-insiders }
-
-The [built-in search plugin][3] integrates seamlessly with Material for MkDocs,
-adding multilingual client-side search with [lunr][4] and [lunr-languages][5].
-It's enabled by default, but must be re-added to `mkdocs.yml` when other plugins
 are used:
 
 ``` yaml
@@ -35,14 +30,14 @@ plugins:
   - search
 ```
 
-The following options are supported:
+The following configuration options are supported:
 
 `lang`{ #search-lang }
 
 :   :octicons-milestone-24: Default: _automatically set_ – This option allows
-    to include the language-specific stemmers provided by [lunr-languages][5].
+    to include the language-specific stemmers provided by [lunr-languages].
     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
+    [site language], but it may be overridden, e.g. to support multiple
     languages:
 
     === "A single language"
@@ -58,11 +53,15 @@ The following options are supported:
         ``` yaml
         plugins:
           - search:
-              lang:
+              lang: # (1)
                 - en
                 - ru
         ```
 
+        1.  Be aware that including support for other languages increases the
+            general JavaScript payload by around 20kb (before `gzip`) and by
+            another 15-30kb per language.
+
     The following languages are supported:
 
     <div class="mdx-columns" markdown>
@@ -89,14 +88,9 @@ The following options are supported:
 
     </div>
 
-    _Material for MkDocs also tries to support languages that are not part of
+    Material for MkDocs goes to great lengths to support languages that are not
-    this list by choosing the stemmer yielding the best result automatically_.
+    part of this list by automatically falling back to the stemmer yielding the
-
+    best result.
-    !!! warning "Only specify the languages you really need"
-
-        Be aware that including support for other languages increases the general
-        JavaScript payload by around 20kb (before `gzip`) and by another 15-30kb
-        per language.
 
 `separator`{ #search-separator }
 
@@ -108,13 +102,21 @@ The following options are supported:
     ``` yaml
     plugins:
       - search:
-          separator: '[\s\-\.]+'
+          separator: '[\s\-\.]' # (1)
     ```
 
-~~`prebuild_index`~~{ #search-prebuild-index }[^1]
+    1.  Tokenization itself is carried out by [lunr's default tokenizer], which 
+        doesn't allow for lookahead or separators spanning multiple characters.
+
+        For more finegrained control over the tokenization process, see the
+        section on [tokenizer lookahead].
+
+<div class="mdx-deprecated" markdown>
+
+`prebuild_index`{ #search-prebuild-index }
 
 :   :octicons-milestone-24: Default: `false` · :octicons-archive-24: Deprecated
-    – MkDocs can generate a [prebuilt index][7] of all pages during
+    · :octicons-trash-24: 8.0.0 – MkDocs can generate a [prebuilt index] of all pages during
     build time, which provides performance improvements at the cost of more
     bandwidth, as it reduces the build time of the search index:
 
@@ -124,36 +126,126 @@ The following options are supported:
           prebuild_index: true
     ```
 
-    This may be beneficial for large documentation projects served with
+    Note that this configuration option was deprecated, as the [new search
-    appropriate headers, i.e. `Content-Encoding: gzip`, but benchmarking before
+    plugin] generates up to [50% smaller] search indexes, doubling search
-    deployment is recommended.
+    performance.
 
-    [^1]:
+    [:octicons-arrow-right-24: Read more on the new search plugin]
-      The `prebuild_index` feature was deprecated in 7.3.0 and will be removed
+    [new search plugin]
-      in 8.x. Insiders removed support in 3.0.0 with the advent of the new
-      search plugin.
 
-_Material for MkDocs doesn't provide official support for the other options of
+</div>
-this plugin, so they may be supported but might yield unexpected results.
-Use them at your own risk._
 
-  [2]: https://github.com/squidfunk/mkdocs-material/tree/master/src/assets/javascripts/integrations/search
+The other configuration options of this plugin are not officially supported
-  [3]: https://www.mkdocs.org/user-guide/configuration/#search
+by Material for MkDocs, which is why they may yield unexpected results. Use
-  [4]: https://lunrjs.com
+them at your own risk.
-  [5]: https://github.com/MihaiValentin/lunr-languages
+
-  [6]: changing-the-language.md#site-language
+  [search support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
-  [7]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index
+  [lunr]: https://lunrjs.com
+  [lunr-languages]: https://github.com/MihaiValentin/lunr-languages
+  [lunr's default tokenizer]: https://github.com/olivernn/lunr.js/blob/aa5a878f62a6bba1e8e5b95714899e17e8150b38/lunr.js#L413-L456
+  [site language]: changing-the-language.md#site-language
+  [tokenizer lookahead]: #tokenizer-lookahead
+  [prebuilt index]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index
+  [50% smaller]: ../blog/2021/search-better-faster-smaller.md#benchmarks
+
+### Rich search previews
+
+[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-3.0.0][Insiders] ·
+:octicons-beaker-24: Experimental
+
+Insiders ships rich search previews as part of the [new search plugin], which
+will render code blocks directly in the search result, and highlight all
+occurrences inside those blocks:
+
+=== "Insiders"
+
+    ![search preview now]
+
+=== "Material for MkDocs"
+
+    ![search preview before]
+
+  [Insiders]: ../insiders/index.md
+  [new search plugin]: ../blog/2021/search-better-faster-smaller.md
+  [search preview now]: ../blog/2021/search-better-faster-smaller/search-preview-now.png
+  [search preview before]: ../blog/2021/search-better-faster-smaller/search-preview-before.png
+
+### Tokenizer lookahead
+
+[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-3.0.0][Insiders] ·
+:octicons-beaker-24: Experimental
+
+Insiders allows for more complex configurations of the [`separator`][separator] 
+setting as part of the [new search plugin], yielding more influence on the way 
+documents are tokenized:
+
+``` yaml
+plugins:
+  - search:
+      separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
+```
+
+The following section explains what can be achieved with tokenizer lookahead:
+
+=== "Case changes"
+
+    ```
+    (?!\b)(?=[A-Z][a-z])
+    ```
+
+    `PascalCase` and `camelCase` are used as naming conventions in many
+    programming languages. By adding this match group to the [`separator`]
+    [separator], [words are split at case changes], tokenizing the word
+    `PascalCase` into `Pascal` and `Case`, so both terms can be searched 
+    individually.
+
+    [:octicons-arrow-right-24: Read more on tokenizing case changes]
+    [tokenize case changes]
+
+=== "Version numbers"
+
+    ```
+    \.(?!\d)
+    ```
+
+    When `.` is added to the [`separator`][separator], version numbers would be
+    split into parts, rendering them undiscoverable via search. By adding
+    this match group, a small lookahead is introduced, so version numbers will
+    remain as they are, and can be found through search.
+
+    [:octicons-arrow-right-24: Read more on tokenizing version numbers]
+    [tokenize version numbers]
+
+=== "HTML/XML tags"
+
+    ```
+    &[lg]t;
+    ```
+
+    If your documentation includes HTML/XML code examples, you may want to allow
+    users to find specific tag names. Unfortunately, the `<` and `>` control
+    characters are encoded in code blocks as `&lt;` and `&gt;`. Adding this
+    expression to the separator allows for just that.
+
+    [:octicons-arrow-right-24: Read more on tokenizing HTML/XML tags]
+    [tokenize html-xml tags]
+
+  [separator]: #search-separator
+  [words are split at case changes]: ?q=searchHighlight
+  [tokenize case changes]: ../blog/2021/search-better-faster-smaller.md#case-changes
+  [tokenize version numbers]: ../blog/2021/search-better-faster-smaller.md#version-numbers
+  [tokenize html-xml tags]: ../blog/2021/search-better-faster-smaller.md#htmlxml-tags
 
 ### Search suggestions
 
+[:octicons-tag-24: 7.2.0][search.suggest support] ·
 :octicons-unlock-24: Feature flag ·
-:octicons-beaker-24: Experimental ·
+:octicons-beaker-24: Experimental
-[:octicons-tag-24: 7.2.0][Search suggestions support]
 
 When search suggestions are enabled, the search will display the likeliest
-completion for the last word, saving the user many key strokes by accepting the
+completion for the last word which can be accepted with the ++arrow-right++ key.
-suggestion with the ++arrow-right++ key.
-
 Add the following lines to `mkdocs.yml`:
 
 ``` yaml
@@ -162,20 +254,17 @@ theme:
     - search.suggest
 ```
 
-Searching for [:octicons-search-24: search su][9] yields ^^search suggestions^^ as a suggestion:
+Searching for [:octicons-search-24: search su][search.suggest example] yields 
+^^search suggestions^^ as a suggestion.
 
-[![Search suggestions][10]][10]
+  [search.suggest support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
-
+  [search.suggest example]: ?q=search+su
-  [Search suggestions support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
-  [8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/components/search/suggest/index.ts
-  [9]: ?q=search+su
-  [10]: ../assets/screenshots/search-suggestions.png
 
 ### Search highlighting
 
+[:octicons-tag-24: 7.2.0][search.highlight support] ·
 :octicons-unlock-24: Feature flag ·
-:octicons-beaker-24: Experimental ·
+:octicons-beaker-24: Experimental
-[:octicons-tag-24: 7.2.0][Search highlighting support]
 
 When search highlighting is enabled and a user clicks on a search result,
 Material for MkDocs will highlight all occurrences after following the link.
@@ -187,20 +276,17 @@ theme:
     - search.highlight
 ```
 
-Searching for [:octicons-search-24: code blocks][12] yields:
+Searching for [:octicons-search-24: code blocks][search.highlight example]
+highlights all occurrences of both terms.
 
-[![Search highlighting][13]][13]
+  [search.highlight support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
-
+  [search.highlight example]: ../reference/code-blocks.md?h=code+blocks
-  [Search highlighting support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
-  [11]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/components/search/highlight/index.ts
-  [12]: ../reference/code-blocks.md?h=code+blocks
-  [13]: ../assets/screenshots/search-highlighting.png
 
 ### Search sharing
 
+[:octicons-tag-24: 7.2.0][search.share support] ·
 :octicons-unlock-24: Feature flag ·
-:octicons-beaker-24: Experimental ·
+:octicons-beaker-24: Experimental
-[:octicons-tag-24: 7.2.0][Search highlighting support]
 
 When search sharing is activated, a :material-share-variant: share button is
 rendered next to the reset button, which allows to deep link to the current
@@ -215,28 +301,24 @@ theme:
 When a user clicks the share button, the URL is automatically copied to the
 clipboard.
 
-[![Search sharing][15]][15]
+  [search.share support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
-
-  [Search sharing support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
-  [14]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/components/search/share/index.ts
-  [15]: ../assets/screenshots/search-share.png
 
 ### Offline search
 
-[:octicons-file-code-24: Source][16] ·
+[:octicons-tag-24: 5.0.0][offline search support] ·
-[:octicons-cpu-24: Plugin][17]
+[:octicons-cpu-24: Plugin][localsearch]
 
 If you distribute your documentation as `*.html` files, the built-in search
 will not work out-of-the-box due to the restrictions modern browsers impose for
-security reasons. This can be mitigated with the [localsearch][17] plugin in
+security reasons. This can be mitigated with the [localsearch] plugin in
-combination with @squidfunk's [iframe-worker][18] polyfill.
+combination with @squidfunk's [iframe-worker] polyfill.
 
-For setup instructions, refer to the [official documentation][19].
+For setup instructions, refer to the [localsearch documentation].
 
-  [16]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
+  [offline search support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
-  [17]: https://github.com/wilhelmer/mkdocs-localsearch/
+  [localsearch]: https://github.com/wilhelmer/mkdocs-localsearch/
-  [18]: https://github.com/squidfunk/iframe-worker
+  [iframe-worker]: https://github.com/squidfunk/iframe-worker
-  [19]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5
+  [localsearch documentation]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5
 
 !!! tip
 
@@ -249,39 +331,36 @@ For setup instructions, refer to the [official documentation][19].
 ### Search boosting
 
 [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
-:octicons-note-24: Metadata ·
 [:octicons-tag-24: insiders-2.8.0][Insiders]
 
-In order to give specific pages a higher relevance in search, [lunr][4] supports
+When [Metadata] is enabled, pages can be boosted in search with custom front
-page-specific boosts, which can be defined for each page by leveraging the
+matter, which will make them rank higher. Add the following lines at the top of
-[Metadata][21] extension:
+a Markdown file:
 
 ``` bash
 ---
 search:
-  boost: 100
+  boost: 2 # (1)
 ---
 
 # Document title
 ...
 ```
 
-  [Insiders]: ../insiders/index.md
+1.  :woman_in_lotus_position: When boosting pages, be gentle and start with
-  [20]: ../insiders/index.md
+    __low values__.
-  [21]: ../reference/meta-tags.md#metadata
+
+  [Metadata]: extensions/python-markdown.md#metadata
 
 ### Search exclusion
 
 [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
-:octicons-note-24: Metadata ·
+[:octicons-tag-24: insiders-3.1.0][Insiders] ·
-:octicons-beaker-24: Experimental ·
+:octicons-beaker-24: Experimental
-[:octicons-tag-24: insiders-3.1.0][Insiders]
 
-#### Excluding pages
+When [Metadata] is enabled, pages can be excluded from search with custom front 
-
+matter, removing them from the index. Add the following lines at the top of a 
-Sometimes, it's necessary to exclude a page from the search index, which can be
+Markdown file:
-achieved by adding the following front matter using the [Metadata][21]
-extension:
 
 ``` bash
 ---
@@ -295,11 +374,11 @@ search:
 
 #### Excluding sections
 
-With the help of the [Attribute List][22] extension, it's possible to exclude a
+When [Attribute Lists] is enabled, specific sections of pages can be excluded
-specific section of a page from search by adding the `{ data-search-exclude }`
+from search by adding the `{ data-search-exclude }` pragma after a Markdown
-pragma after the Markdown heading:
+heading:
 
-=== "`docs/page.md`"
+=== ":octicons-file-code-16: docs/page.md"
 
     ``` markdown
     # Document title
@@ -313,7 +392,7 @@ pragma after the Markdown heading:
     The content of this section is excluded
     ```
 
-=== "`search_index.json`"
+=== ":octicons-codescan-16: search_index.json"
 
     ``` json
     {
@@ -333,15 +412,15 @@ pragma after the Markdown heading:
     }
     ```
 
-  [22]: ../reference/images.md#attribute-list
+  [Attribute Lists]: extensions/python-markdown.md#attribute-lists
 
 #### Excluding blocks
 
-If even more fine-grained control is needed, content blocks can be excluded
+When [Attribute Lists] is enabled, specific sections of pages can be excluded
-from search sections with a `{ data-search-exclude }` pragma, so they will not
+from search by adding the `{ data-search-exclude }` pragma after a Markdown
-be included in the search index:
+inline- or block-level element:
 
-=== "`docs/page.md`"
+=== ":octicons-file-code-16: docs/page.md"
 
     ``` markdown
     # Document title
@@ -352,7 +431,7 @@ be included in the search index:
     { data-search-exclude }
     ```
 
-=== "`search_index.json`"
+=== ":octicons-codescan-16: search_index.json"
 
     ``` json
     {
@@ -370,8 +449,8 @@ be included in the search index:
 ## Customization
 
 The search implementation of Material for MkDocs is probably its most
-sophisticated feature, as it tries to balance a _great typeahead experience_,
+sophisticated feature, as it tries to balance a great typeahead experience,
-_good performance_, _accessibility_, and a result list that is _easy to scan_.
+good performance, accessibility, and a result list that is easy to scan.
 This is where Material for MkDocs deviates from other themes.
 
 The following section explains how search can be customized to tailor it to
@@ -379,12 +458,9 @@ your needs.
 
 ### Query transformation
 
-[:octicons-file-code-24: Source][23] ·
-:octicons-mortar-board-24: Difficulty: _easy_
-
 When a user enters a query into the search box, the query is pre-processed
 before it is submitted to the search index. Material for MkDocs will apply the
-following transformations, which can be customized by [extending the theme][24]:
+following transformations, which can be customized by [extending the theme]:
 
 ``` ts
 export function defaultTransform(query: string): string {
@@ -417,7 +493,7 @@ export function defaultTransform(query: string): string {
 If you want to switch to the default behavior of the `mkdocs` and `readthedocs`
 themes, both of which don't transform the query prior to submission, or
 customize the `transform` function, you can do this by [overriding the
-`config` block][25]:
+`config` block][overriding blocks]:
 
 ``` html
 {% extends "base.html" %}
@@ -437,19 +513,15 @@ customize the `transform` function, you can do this by [overriding the
 The `transform` function will receive the query string as entered by the user
 and must return the processed query string to be submitted to the search index.
 
-  [23]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts
+  [extending the theme]: ../customization.md#extending-the-theme
-  [24]: ../customization.md#extending-the-theme
+  [overriding blocks]: ../customization.md#overriding-blocks
-  [25]: ../customization.md#overriding-blocks
 
 ### Custom search
 
-[:octicons-file-code-24: Source][26] ·
+Material for MkDocs implements search as part of a [web worker]. If you
-:octicons-mortar-board-24: Difficulty: _challenging_
-
-Material for MkDocs implements search as part of a [web worker][27]. If you
 want to switch the web worker with your own implementation, e.g. to submit
 search to an external service, you can add a custom JavaScript file to the
-`docs` directory and [override the `config` block][24]:
+`docs` directory and [override the `config` block][overriding blocks]:
 
 ``` html
 {% block config %}
@@ -463,12 +535,12 @@ search to an external service, you can add a custom JavaScript file to the
 ```
 
 Communication with the search worker is implemented using a designated message
-format using _discriminated unions_, i.e. through the `type` property of the
+format using discriminated unions, i.e. through the `type` property of the
 message. See the following interface definitions to learn about the message
 formats:
 
-- [:octicons-file-code-24: `SearchMessage`][28]
+- [:octicons-file-code-24: `SearchMessage`][SearchMessage]
-- [:octicons-file-code-24: `SearchIndex` and `SearchResult`][29]
+- [:octicons-file-code-24: `SearchIndex` and `SearchResult`][SearchIndex]
 
 The sequence and direction of messages is rather intuitive:
 
@@ -477,7 +549,6 @@ The sequence and direction of messages is rather intuitive:
 - :octicons-arrow-right-24: `SearchQueryMessage`
 - :octicons-arrow-left-24: `SearchResultMessage`
 
-  [26]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker
+  [web worker]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers
-  [27]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers
+  [SearchMessage]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/message/index.ts
-  [28]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/message/index.ts
+  [SearchIndex]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/_/index.ts
-  [29]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/_/index.ts

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

@@ -60,9 +60,10 @@ The following configuration options are available:
 
 `cards_color`{ #cards-color }
 
-:   :octicons-milestone-24: Default: [primary color][palette.primary] + header
+:   [:octicons-tag-24: insiders-2.13.0][Insiders] · :octicons-milestone-24:
-    text color – This option specifies which colors to use for the background
+    Default: [primary color][palette.primary] – This option specifies which
-    `fill` and foreground `text` when generating the social card:
+    colors to use for the background `fill` and foreground `text` when
+    generating the social card:
 
     ``` yaml
     plugins:

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

@@ -15,7 +15,7 @@ configured via `mkdocs.yml`.
 
 ### Social links
 
-[:octicons-tag-24: 1.0.0][Social links support] ·
+[:octicons-tag-24: 1.0.0][social support] ·
 :octicons-milestone-24: Default: _none_
 
 Social links are rendered next to the copyright notice as part of the 
@@ -33,10 +33,10 @@ For each entry, the following settings are available:
 
 `icon`{ #social-icon }
 
-:   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
+:   [:octicons-tag-24: 5.0.0][social.icon support] · :octicons-milestone-24:
-    This field must point to a valid icon path referencing [any icon bundled
+    Default: _none_ · :octicons-alert-24: Required – This field must point to an 
-    with the theme][custom icons], or the build will not succeed. Some popular
+    icon path referencing [any icon bundled with the theme][custom icons], or
-    choices:
+    the build will not succeed. Some popular choices:
 
     * :fontawesome-brands-behance: – `fontawesome/brands/behance`
     * :fontawesome-brands-docker: – `fontawesome/brands/docker`
@@ -49,9 +49,6 @@ For each entry, the following settings are available:
     * :fontawesome-brands-slack: – `fontawesome/brands/slack`
     * :fontawesome-brands-twitter: – `fontawesome/brands/twitter`
 
-  [Social links support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
-  [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
-
 `link`{ #social-link }
 
 :   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
@@ -78,9 +75,10 @@ For each entry, the following settings are available:
 
 `name`{ #social-name }
 
-:   :octicons-milestone-24: Default: _domain name from_ `link`_, if available_ –
+:   [:octicons-tag-24: 5.1.5][social.name support] · :octicons-milestone-24: 
-    This field is used as the link's `title` attribute and can be set to a 
+    Default: _domain name from_ `link`_, if available_ – This field is used as
-    discernable name to improve accessibility:
+    the link's `title` attribute and can be set to a  discernable name to
+    improve accessibility:
 
     ``` yaml
     extra:
@@ -90,6 +88,11 @@ For each entry, the following settings are available:
           name: squidfunk on Twitter
     ```
 
+  [social support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
+  [social.icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
+  [social.name support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.1.5
+  [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
+
 ### Copyright notice
 
 [:octicons-tag-24: 0.1.0][Copyright notice support] ·