Updated documentation

Author: squidfunk

docs/customization.md

@@ -152,7 +152,7 @@ directory:
 MkDocs will now use the new partial when rendering the theme. This can be done
 with any file.
 
-### Overriding blocks <small>recommended</small> { data-toc-label="Overriding blocks" }
+### Overriding blocks <small>recommended</small> { #overriding-blocks data-toc-label="Overriding blocks" }
 
 Besides overriding partials, it's also possible to override (and extend)
 _template blocks_, which are defined inside the templates and wrap specific
@@ -216,7 +216,7 @@ with Material for MkDocs_ hint in the footer, add the following line to
 {% extends "base.html" %}
 
 {% set extracopyright %}
-  <!-- Add your additional information here -->
+  <!-- Add additional copyright information here -->
 {% endset %}
 ```
 

docs/deprecations.md

@@ -124,7 +124,7 @@ templates can be shared among multiple pages:
     {% endblock %}
     ```
 
-  [5]: customization.md#overriding-blocks-recommended
+  [5]: customization.md#overriding-blocks
   [6]: customization.md#extending-the-theme
 
 ## Docker image

docs/getting-started.md

@@ -19,7 +19,7 @@ In case you're running into problems, consult the [troubleshooting][4] section.
 
 ## Installation
 
-### with pip <small>recommended</small> { data-toc-label="with pip" }
+### with pip <small>recommended</small> { #with-pip data-toc-label="with pip" }
 
 Material for MkDocs can be installed with `pip`:
 

docs/reference/meta-tags.md

@@ -105,7 +105,7 @@ extra:
 #### on all pages
 
 In order to add custom `meta` tags to your document, you can [extend the theme
-][theme extension] and [override the `extrahead` block][override block],
+][theme extension] and [override the `extrahead` block][overriding blocks],
 e.g. to add indexing policies for search engines via the `robots` property:
 
 ``` html
@@ -116,7 +116,7 @@ e.g. to add indexing policies for search engines via the `robots` property:
 {% endblock %}
 ```
 
-  [override block]: ../customization.md#overriding-blocks-recommended
+  [overriding blocks]: ../customization.md#overriding-blocks
 
 #### on a single page
 

docs/setup/adding-a-comment-system.md

@@ -4,47 +4,43 @@ template: overrides/main.html
 
 # Adding a comment system
 
-Material for MkDocs is natively integrated with [Disqus][1], a comment system
-that provides a wide range of features like social integrations, user profiles,
-as well as spam and moderation tools. Of course, other comment systems can be 
+Material for MkDocs is natively integrated with [Disqus], a comment system that
+provides a wide range of features like social integrations, user profiles, as
+well as spam and moderation tools. Of course, other comment systems can be
 integrated, too.
 
-  [1]: https://disqus.com/
+  [Disqus]: https://disqus.com/
 
 ## Configuration
 
 ### Disqus
 
-[:octicons-file-code-24: Source][2] ·
+[:octicons-tag-24: 1.1.0][Disqus support] ·
 :octicons-milestone-24: Default: _none_
 
-First, ensure you've set [`site_url`][3] in `mkdocs.yml`. Then, to integrate
-Material for MkDocs with [Disqus][1], create an account and a site giving you a
-[shortname][4], and add it to `mkdocs.yml`:
+First, ensure you've set [`site_url`][site_url] in `mkdocs.yml`. Then, to
+integrate Material for MkDocs with [Disqus], create an account and a site
+giving you a [shortname], and add it to `mkdocs.yml`:
 
 ``` yaml
 extra:
   disqus: <shortname>
 ```
 
-This will insert a comment system on _every page, except the index page_.
+This will insert a comment system on every page, except the index page.
 
-  [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/integrations/disqus.html
-  [3]: https://www.mkdocs.org/user-guide/configuration/#site_url
-  [4]: https://help.disqus.com/en/articles/1717111-what-s-a-shortname
+  [Disqus support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0
+  [site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
+  [shortname]: https://help.disqus.com/en/articles/1717111-what-s-a-shortname
 
 ## Customization
 
 ### Selective integration
 
-[:octicons-file-code-24: Source][2] ·
-:octicons-note-24: Metadata ·
-:octicons-mortar-board-24: Difficulty: _easy_
+When [Metadata] is enabled, Disqus can be enabled or disabled for a document
+with custom front matter. Add the following lines at the top of a Markdown file:
 
-If the [Metadata][5] extension is enabled, you can disable or enable Disqus for
-specific pages by adding the following to the front matter of a page:
-
-=== "Enable Disqus"
+=== ":octicons-check-circle-fill-16: Enabled"
 
     ``` bash
     ---
@@ -55,7 +51,7 @@ specific pages by adding the following to the front matter of a page:
     ...
     ```
 
-=== "Disable Disqus"
+=== ":octicons-skip-16: Disabled"
 
     ``` bash
     ---
@@ -66,15 +62,13 @@ specific pages by adding the following to the front matter of a page:
     ...
     ```
 
-  [5]: ../../reference/meta-tags/#metadata
+  [Metadata]: extensions/python-markdown.md#metadata
 
 ### Other comment systems
 
-[:octicons-file-code-24: Source][6] ·
-:octicons-mortar-board-24: Difficulty: _easy_
-
 In order to integrate another JavaScript-based comment system provider, you can
-[extend the theme][7] and [override the `disqus` block][8]:
+[extend the theme], create a new `main.html` in `overrides` and [override the
+`disqus` block][overriding blocks]:
 
 ``` html
 {% extends "base.html" %}
@@ -84,6 +78,5 @@ In order to integrate another JavaScript-based comment system provider, you can
 {% endblock %}
 ```
 
-  [6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
-  [7]: ../customization.md#extending-the-theme
-  [8]: ../customization.md#overriding-blocks-recommended
+  [extend the theme]: ../customization.md#extending-the-theme
+  [overriding blocks]: ../customization.md#overriding-blocks

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

@@ -20,7 +20,7 @@ and extendable [cookie consent][extra.consent].
 :octicons-milestone-24: Default: _none_
 
 Material for MkDocs integrates with both, Google Analytics 4 and the now phasing
-out Universal Analytics (`UA-*`). Depending on the property prefix, add the
+out Universal Analytics. Depending on the given property prefix, add the
 following lines to `mkdocs.yml`:
 
 === ":material-google-analytics: Google Analytics 4"

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

@@ -150,7 +150,7 @@ Use them at your own risk._
 :octicons-beaker-24: Experimental ·
 [:octicons-tag-24: 7.2.0][Search suggestions support]
 
-When _search suggestions_ are enabled, the search will display the likeliest
+When search suggestions are enabled, the search will display the likeliest
 completion for the last word, saving the user many key strokes by accepting the
 suggestion with the ++arrow-right++ key.
 
@@ -177,7 +177,7 @@ Searching for [:octicons-search-24: search su][9] yields ^^search suggestions^^
 :octicons-beaker-24: Experimental ·
 [:octicons-tag-24: 7.2.0][Search highlighting support]
 
-When _search highlighting_ is enabled and a user clicks on a search result,
+When search highlighting is enabled and a user clicks on a search result,
 Material for MkDocs will highlight all occurrences after following the link.
 Add the following lines to `mkdocs.yml`:
 
@@ -202,7 +202,7 @@ Searching for [:octicons-search-24: code blocks][12] yields:
 :octicons-beaker-24: Experimental ·
 [:octicons-tag-24: 7.2.0][Search highlighting support]
 
-When _search sharing_ is activated, a :material-share-variant: share button is
+When search sharing is activated, a :material-share-variant: share button is
 rendered next to the reset button, which allows to deep link to the current
 search query and result. Add the following lines to `mkdocs.yml`:
 
@@ -439,7 +439,7 @@ and must return the processed query string to be submitted to the search index.
 
   [23]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts
   [24]: ../customization.md#extending-the-theme
-  [25]: ../customization.md#overriding-blocks-recommended
+  [25]: ../customization.md#overriding-blocks
 
 ### Custom search
 

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

@@ -30,7 +30,12 @@ MkDocs can generate beautiful social cards automatically, using the [colors]
 
 The built-in social cards plugin generates a social preview image for every page
 and adds the necessary meta tags, so it's displayed on social media when shared.
-Enable it via `mkdocs.yml`:
+First, ensure you've set [`site_url`][site_url] in `mkdocs.yml`.[^2] Then, add
+the following lines to `mkdocs.yml` to enable the plugin:
+
+  [^2]:
+    When using this plugin, the [`site_url`][site_url] setting is mandatory, as
+    social preview images don't work with relative URLs.
 
 ``` yaml
 plugins:
@@ -83,12 +88,14 @@ The following configuration options are available:
     ```
 
   [Insiders]: ../insiders/index.md
+  [site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
   [setting up site analytics]: setting-up-site-analytics.md
   [Social cards preview]: ../assets/screenshots/social-cards.png
   [Twitter's Card validator]: https://cards-dev.twitter.com/validator
+  [meta tags]: #meta-tags
   [CSS color keywords]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords
 
-#### Caching <small>recommended</small> { data-toc-label="Caching" }
+#### Caching <small>recommended</small> { #caching data-toc-label="Caching" }
 
 The [built-in social cards plugin] automatically fetches the fonts you define
 in `mkdocs.yml` from Google Fonts, and uses them to render the text that is

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

@@ -15,9 +15,8 @@ configured via `mkdocs.yml`.
 
 ### Social links
 
-:octicons-hash-24: Setting ·
-:octicons-milestone-24: Default: _none_ ·
-[:octicons-tag-24: 1.0.0][Social links support]
+[:octicons-tag-24: 1.0.0][Social links support] ·
+:octicons-milestone-24: Default: _none_
 
 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` 
@@ -36,7 +35,8 @@ For each entry, the following settings are available:
 
 :   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
     This field must point to a valid icon path referencing [any icon bundled
-    with the theme][2], or the build will not succeed. Some popular choices:
+    with the theme][custom icons], or the build will not succeed. Some popular
+    choices:
 
     * :fontawesome-brands-behance: – `fontawesome/brands/behance`
     * :fontawesome-brands-docker: – `fontawesome/brands/docker`
@@ -50,16 +50,15 @@ For each entry, the following settings are available:
     * :fontawesome-brands-twitter: – `fontawesome/brands/twitter`
 
   [Social links support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
-  [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/social.html
-  [2]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
+  [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
 
 `link`{ #social-link }
 
 :   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
     This field must contain a valid relative or absolute URL including the URI 
     scheme. All URI schemes are supported, including `mailto` and `bitcoin`:
 
-    === "Twitter"
+    === ":fontawesome-brands-twitter: Twitter"
 
         ``` yaml
         extra:
@@ -68,7 +67,7 @@ For each entry, the following settings are available:
               link: https://twitter.com/squidfunk
         ```
 
-    === "Email address"
+    === ":octicons-mail-16: Email"
 
         ``` yaml
         extra:
@@ -93,9 +92,8 @@ For each entry, the following settings are available:
 
 ### Copyright notice
 
-:octicons-hash-24: Setting ·
-:octicons-milestone-24: Default: _none_ ·
-[:octicons-tag-24: 0.1.0][Copyright notice support]
+[:octicons-tag-24: 0.1.0][Copyright notice support] ·
+:octicons-milestone-24: Default: _none_
 
 A custom copyright banner can be rendered as part of the footer, which is
 displayed next to the social links. It can be defined as part of `mkdocs.yml`:
@@ -109,9 +107,8 @@ copyright: Copyright © 2016 - 2020 Martin Donath
 
 ### Generator notice
 
-:octicons-hash-24: Setting ·
-:octicons-milestone-24: Default: `true` ·
-[:octicons-tag-24: 7.3.0][Generator notice support]
+[:octicons-tag-24: 7.3.0][Generator notice support] ·
+:octicons-milestone-24: Default: `true`
 
 The footer displays a _Made with Material for MkDocs_ notice to denote how
 the site was generated. The notice can be removed with the following setting
@@ -127,25 +124,24 @@ extra:
     The subtle __Made with Material for MkDocs__ hint in the footer is one of
     the reasons why this project is so popular, as it tells the user how the
     site is generated, helping new users to discover this project. Before
-    removing it, please consider that you're enjoying the benefits of
-    @squidfunk's work for free, as this project is Open Source and has a
-    permissive license. Thousands of hours went into this project, most of them
-    without any financial return. Thus, if you remove this notice, please
-    consider [sponsoring][4] the project. __Thank you__
-    :octicons-heart-fill-24:{ .mdx-heart .mdx-insiders }
+    removing please consider that you're enjoying the benefits of @squidfunk's
+    work for free, as this project is Open Source and has a permissive license.
+    Thousands of hours went into this project, most of them
+    without any financial return.
+
+    Thus, if you remove this notice, please consider [sponsoring][Insiders] the
+    project. __Thank you__ :octicons-heart-fill-24:{ .mdx-heart .mdx-insiders }
 
   [Generator notice support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
+  [Insiders]: ../insiders/index.md
 
 ## Customization
 
 ### Custom icons
 
-[:octicons-file-code-24: Source][2] ·
-:octicons-mortar-board-24: Difficulty: _easy_
-
-The social links feature uses the standard [icon integration][5] of Material for
+The social links feature uses the standard [icon integration] of Material for
 MkDocs. If you want to use custom icons, follow the guide explaining how to
-add [additional icons][6].
+add [additional icons].
 
-  [5]: changing-the-logo-and-icons.md#icons
-  [6]: changing-the-logo-and-icons.md#additional-icons
+  [icon integration]: extensions/python-markdown-extensions.md#emoji
+  [additional icons]: changing-the-logo-and-icons.md#additional-icons