Finished rewrite of reference documentation

Author: squidfunk

docs/reference/code-blocks.md

@@ -110,7 +110,7 @@ import tensorflow as tf
 
 Code annotations can be placed anywhere in a code block where a comment for the
 language of the block can be placed, e.g. for JavaScript in `#!js // ...` and
-`#!js /* ... */`, for Yaml `#!yaml # ...`, etc.[^1]
+`#!js /* ... */`, for YAML in `#!yaml # ...`, etc.[^1]
 
   [^1]:
     Code annotations require syntax highlighting with [Pygments] – they're
@@ -202,7 +202,7 @@ at `1`, regardless of the starting line number specified as part of
                     items[j], items[j + 1] = items[j + 1], items[j]
     ```
 
-=== "Line ranges"
+=== "Line number ranges"
 
     _Example_:
 

docs/reference/meta-tags.md

@@ -6,57 +6,60 @@ template: overrides/main.html
 
 In HTML, `meta` tags allow to provide additional metadata for a document, e.g.
 page titles and descriptions, additional assets to be loaded, and [Open Graph]
-[1] data. While arbitrary metadata can always be added via [customization][2],
+metadata. While arbitrary `meta` tags can always be added via [customization],
 some common `meta` tags can be configured.
 
-  [1]: https://ogp.me/
-  [2]: #customization
+  [Open Graph]: https://ogp.me/
+  [customization]: #customization
 
 ## Configuration
 
-### Metadata
-
-The [Metadata][3] extension, which is part of the standard Markdown library,
-adds the ability to add [front matter][4] to a document and can be enabled via
-`mkdocs.yml`:
+This configuration adds support for setting custom page titles and descriptions
+in [front matter], as well as for using custom metadata in templates. Add the
+following lines to `mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:
   - meta
 ```
 
-Front matter is written as a series of key-value pairs at the beginning of the
-Markdown document, delimited by a blank line which ends the YAML context.
+See additional configuration options:
+
+- [Metadata]
 
-  [3]: https://python-markdown.github.io/extensions/meta_data/
-  [4]: https://jekyllrb.com/docs/front-matter/
+  [front matter]: https://jekyllrb.com/docs/front-matter/
+  [Metadata]: ../setup/extensions/python-markdown.md#metadata
 
 ## Usage
 
 ### Setting the page title
 
-If the [Metadata][5] extension is enabled, the page title can be overridden on
-a per-document basis with custom front matter:
+When [Metadata] is enabled, the page title can be overridden on a per-document
+basis with custom front matter. Add the following lines at the top of a Markdown
+file:
 
 ``` bash
 ---
-title: Lorem ipsum dolor sit amet
+title: Lorem ipsum dolor sit amet # (1)
 ---
 
 # Document title
 ...
 ```
 
-This will set the `title` tag inside the document `head` for the current page
-to the provided value. Note that the site title is appended using a dash as a
-separator, which is the default behavior.
+1.  This will set the [`title`][title] inside the HTML document's [`head`][head]
+    for the generated page to this value. Note that the site title, which is set
+    via [`site_name`][site_name], is appended with a dash.
 
-  [5]: #metadata
+  [title]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title
+  [head]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head
+  [site_name]: https://www.mkdocs.org/user-guide/configuration/#site_name
 
 ### Setting the page description
 
-If the [Metadata][5] extension is enabled, the page description can also be
-overridden on a per-document basis with custom front matter:
+When [Metadata] is enabled, the page description can also be overridden on a
+per-document basis with custom front matter. Add the following lines at the top
+of a Markdown file:
 
 ``` bash
 ---
@@ -70,47 +73,41 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
 This will set the `meta` tag containing the site description inside the
 document `head` for the current page to the provided value.
 
+<div class="mdx-deprecated" markdown>
+
 ### Adding a web app manifest
 
-A [web app manifest][6] is a simple JSON file that specifies how your web
+:octicons-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
 application should behave when installed on the user's mobile device or desktop,
 which can be set via `mkdocs.yml`:
 
 ``` yaml
 extra:
-  manifest: manifest.webmanifest
+  manifest: manifest.webmanifest # (1)
 ```
 
-  [6]: https://developers.google.com/web/fundamentals/web-app-manifest/
+1.  This option was deprecated, as it's not widely used and the same behavior
+    can be achieved with [theme extension].
 
-## Customization
-
-### Displaying the metadata
+  [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
+  [theme extension]: ../customization.md#extending-the-theme
 
-Sometimes it's useful to be able to display the medatada in the page body, e.g.
-print the name of the page author at the bottom of the page. To achieve that,
-you can [extend the theme][7] by adding the following contents to `main.html`:
+</div>
 
-``` html
-{% extends "base.html" %}
-
-{% block content %}
-  {{ super() }}
-  {% if page and page.meta and page.meta.author %}
-    <p><small>Author: {{ page.meta.author }}</small></p>
-  {% endif %}
-{% endblock %}
-```
-
-  [7]: ../customization.md#extending-the-theme
+## Customization
 
-### Custom meta tags
+### Using metadata in templates
 
 #### on all pages
 
 In order to add custom `meta` tags to your document, you can [extend the theme
-][7] and simply [override the `extrahead` block][8], e.g. to add indexing
-policies for search engines:
+][theme extension] and [override the `extrahead` block][override block],
+e.g. to add indexing policies for search engines via the `robots` property:
 
 ``` html
 {% extends "base.html" %}
@@ -120,7 +117,7 @@ policies for search engines:
 {% endblock %}
 ```
 
-  [8]: ../customization.md#overriding-blocks-recommended
+  [override block]: ../customization.md#overriding-blocks-recommended
 
 #### on a single page
 
@@ -140,63 +137,9 @@ template override, e.g.:
 {% endblock %}
 ```
 
-You can now use `robots` exactly like [`title`][9] and [`description`][10] to
-set values. Note that in this case, the template defines an `else` branch, which
-would set a default if none was given.
-
-  [9]: #setting-the-page-title
-  [10]: #setting-the-page-description
-
-### Social meta tags
-
-Some further examples, including [Open Graph][1] and [Twitter Cards][11]:
-
-=== "Open Graph"
-
-    ``` html
-    {% block extrahead %}
-      {% set title = config.site_name %}
-      {% if page and page.meta and page.meta.title %}
-        {% set title = title ~ " - " ~ page.meta.title %}
-      {% elif page and page.title and not page.is_homepage %}
-        {% set title = title ~ " - " ~ page.title | striptags %}
-      {% endif %}
-      <meta property="og:type" content="website" />
-      <meta property="og:title" content="{{ title }}" />
-      <meta property="og:description" content="{{ config.site_description }}" />
-      <meta property="og:url" content="{{ page.canonical_url }}" />
-      <meta property="og:image" content="<url>" />
-      <meta property="og:image:type" content="image/png" />
-      <meta property="og:image:width" content="1200" />
-      <meta property="og:image:height" content="630" />
-    {% endblock %}
-    ```
-
-=== "Twitter Cards"
-
-    ``` html
-    {% block extrahead %}
-      {% set title = config.site_name %}
-      {% if page and page.meta and page.meta.title %}
-        {% set title = title ~ " - " ~ page.meta.title %}
-      {% elif page and page.title and not page.is_homepage %}
-        {% set title = title ~ " - " ~ page.title | striptags %}
-      {% endif %}
-      <meta name="twitter:card" content="summary_large_image" />
-      <meta name="twitter:site" content="<username>" />
-      <meta name="twitter:creator" content="<username>" />
-      <meta name="twitter:title" content="{{ title }}" />
-      <meta name="twitter:description" content="{{ config.site_description }}" />
-      <meta name="twitter:image" content="<url>" />
-    {% endblock %}
-    ```
-
-!!! tip "Automatically generated social cards"
-
-    If you don't want to bother with meta tags and social cards yourself, you
-    can let the [built-in social cards plugin][12] do the work for you, which
-    generates beautiful image previews for social media automatically during
-    the build.
-
-  [11]: https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards
-  [12]: ../setup/setting-up-social-cards.md
+You can now use `robots` exactly like [`title`][title] and
+[`description`][description] to set values. Note that in this case, the
+template defines an `else` branch, which would set a default if none was given.
+
+  [title]: #setting-the-page-title
+  [description]: #setting-the-page-description