Finished rewrite of reference documentation

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/
+  [Open Graph]: https://ogp.me/
-  [2]: #customization
+  [customization]: #customization
 
 ## Configuration
 
-### Metadata
+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
-The [Metadata][3] extension, which is part of the standard Markdown library,
+following lines to `mkdocs.yml`:
-adds the ability to add [front matter][4] to a document and can be enabled via
-`mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:
   - meta
 ```
 
-Front matter is written as a series of key-value pairs at the beginning of the
+See additional configuration options:
-Markdown document, delimited by a blank line which ends the YAML context.
 
-  [3]: https://python-markdown.github.io/extensions/meta_data/
+- [Metadata]
-  [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
+When [Metadata] is enabled, the page title can be overridden on a per-document
-a per-document basis with custom front matter:
+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
+1.  This will set the [`title`][title] inside the HTML document's [`head`][head]
-to the provided value. Note that the site title is appended using a dash as a
+    for the generated page to this value. Note that the site title, which is set
-separator, which is the default behavior.
+    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
+When [Metadata] is enabled, the page description can also be overridden on a
-overridden on a per-document basis with custom front matter:
+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].
+
+  [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
+
+</div>
 
 ## Customization
 
-### Displaying the metadata
+### Using metadata in templates
-
-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`:
-
-``` 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
-
-### Custom meta tags
 
 #### 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
+][theme extension] and [override the `extrahead` block][override block],
-policies for search engines:
+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
+You can now use `robots` exactly like [`title`][title] and
-set values. Note that in this case, the template defines an `else` branch, which
+[`description`][description] to set values. Note that in this case, the
-would set a default if none was given.
+template defines an `else` branch, which would set a default if none was given.
 
-  [9]: #setting-the-page-title
+  [title]: #setting-the-page-title
-  [10]: #setting-the-page-description
+  [description]: #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

docs/reference/variables.md

@@ -1,152 +0,0 @@
----
-template: overrides/main.html
----
-
-# Variables
-
-Macros and variables are powerful tools to parametrize Markdown files, as they 
-allow to perform Jinja templating directly from Markdown. This is especially 
-useful to include technical data from other files and add central variables via 
-`mkdocs.yml`.
-
-## Configuration
-
-### Macros
-
-The [macros][1] plugin adds support to reference variables and call macros and 
-supports Jinja templating directly from Markdown. It can be installed with
-`pip`:
-
-```
-pip install mkdocs-macros-plugin
-```
-
-Then, add the following to `mkdocs.yml`:
-
-``` yaml
-plugins:
-  - macros
-```
-
-  [1]: https://github.com/fralau/mkdocs_macros_plugin
-
-## Usage
-
-### Using predefined variables
-
-A set of predefined variables is enabled by default and can be used from 
-Markdown, including data from `mkdocs.yml`. More specifically, predefined 
-variables fall into the following categories:
-
-- `config.*`: configuration parameters from `mkdocs.yml`
-- `page.*`: metadata and content of current page
-- `navigation.*`: list of all pages and sections
-- `environment.*`: underlying operating system
-- `git.*`: git-related information, if available
-
-_Example_:
-
-``` markdown
-Welcome to {{ config.site_name }}!
-```
-
-_Result_:
-
-``` markdown
-Welcome to Material for MkDocs!
-```
-
-A list of all predefined variables can be printed with:
-
-```
-{{ macros_info() }}
-```
-
-### Using custom variables
-
-All data defined under `extra` in `mkdocs.yml` is automatically exposed as a
-variable and can be used from the template. This enables centralized parameter
-storage and management.
-
-_Example_:
-
-=== "`docs/page.md`"
-
-    ```` markdown
-    The unit price is {{ unit.price }}
-    ````
-
-=== "`mkdocs.yml`"
-
-    ``` yaml
-    extra:
-      unit:
-        price: 12.50
-    ```
-
-_Result_:
-
-The unit price is 12.50.
-
-### Using variables in snippets
-
-The [macros][2] plugin can be used to allow variables in snippets, which is not
-possible with the [Snippets][3] extension alone. Add the snippets location to
-the plugin configuration in `mkdocs.yml`:
-
-``` yaml
-plugins:
-  - search
-  - macros:
-      include_dir: snippets
-```
-
-In your Markdown file, include snippets with Jinja's [`include`][4] function:
-
-``` markdown
-{% include "definitions.md" %}
-```
-
-_Example_:
-
-=== "`snippets/definitions.md`"
-
-    ``` markdown
-    The unit price is {{ page.meta.unit.price }}
-    ```
-
-=== "`docs/page-1.md`"
-
-    ``` markdown
-    ---
-    unit:
-      price: 12.50
-    ---
-
-    {% include "definitions.md" %}
-    ```
-
-=== "`docs/page-2.md`"
-
-    ``` markdown
-    ---
-    unit:
-      price: 25.00
-    ---
-
-    {% include "definitions.md" %}
-    ```
-
-  [2]: #macros
-  [3]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
-  [4]: https://jinja.palletsprojects.com/en/2.11.x/templates/#include
-
-## Customization
-
-### Custom macros
-
-The [macros][1] plugin allows to define custom macros, which can then be used
-from Markdown files. See the [official documentation][5] for more information
-how to define custom macros.
-
-  [5]: https://mkdocs-macros-plugin.readthedocs.io/en/latest/python/

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

@@ -143,3 +143,52 @@ default values.
   [11]: ../reference/meta-tags.md#metadata
   [12]: ../reference/meta-tags.md#setting-the-page-title
   [13]: ../reference/meta-tags.md#setting-the-page-description
+
+### Using social media meta tags
+
+The [built-in social cards plugin] generates beautiful image previews for social
+media during the build and sets all necessary `meta` tags, equivalent to the
+following two customizations:
+
+=== ":material-graph: 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 %}
+    ```
+
+=== ":fontawesome-brands-twitter: 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 %}
+    ```
+
+  [Twitter Cards]: https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards
+  [built-in social cards plugin]: ../setup/setting-up-social-cards.md#built-in-social-cards

material/base.html

@@ -39,7 +39,7 @@
       {% endif %}
     {% endblock %}
     {% block styles %}
-      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.24c991ad.min.css' | url }}">
+      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.76ff9fe5.min.css' | url }}">
       {% if config.theme.palette %}
         {% set palette = config.theme.palette %}
         <link rel="stylesheet" href="{{ 'assets/stylesheets/palette.3f5d1f46.min.css' | url }}">

material/overrides/main.html

@@ -3,7 +3,7 @@
 -#}
 {% extends "base.html" %}
 {% block extrahead %}
-  <link rel="stylesheet" href="{{ 'overrides/assets/stylesheets/main.9307850e.min.css' | url }}">
+  <link rel="stylesheet" href="{{ 'overrides/assets/stylesheets/main.5136944a.min.css' | url }}">
 {% endblock %}
 {% block announce %}
   <a href="https://twitter.com/squidfunk">

mkdocs.yml

@@ -215,7 +215,6 @@ nav:
     - Lists: reference/lists.md
     - MathJax: reference/mathjax.md
     - Meta tags: reference/meta-tags.md
-    - Variables: reference/variables.md
   - Insiders:
     - insiders/index.md
     - Getting started:

src/overrides/assets/stylesheets/main/_typeset.scss

@@ -104,6 +104,18 @@
     }
   }
 
+  // Deprecation
+  .mdx-deprecated {
+    opacity: 0.5;
+    transition: opacity 250ms;
+
+    // Deprecation on focus/hover
+    &:focus-within,
+    &:hover {
+      opacity: 1;
+    }
+  }
+
   // Two-column layout
   .mdx-columns {