Adjusted front matter and deprecation docs

docs/deprecations.md

@@ -4,19 +4,20 @@ template: overrides/main.html
 
 # Deprecations
 
-This page includes a list of deprecations, indicating which features should not
-be used anymore, as they will be removed in a future release.
+This page includes a list of deprecations, indicating which features of Material
+for MkDocs were replaced with newer, more flexible alternatives, and thus should
+not be used anymore.
 
 ## Front matter
 
-### Redirects
+### Redirect
 
 :octicons-archive-24: Deprecated: 5.5.0 ·
-:octicons-trash-24: Will be removed in 6.0
+:octicons-trash-24: Removal: 6.x
 
 The `redirect` key, which could be added via [Metadata][1], allowed to
-specify a redirect URL from within a markdown page to a new address, to notify
-the user when content was moved:
+specify a redirect from within a document to a new address, which is a good
+idea when moving content around:
 
 ``` markdown
 ---
@@ -39,14 +40,14 @@ plugins:
   [1]: reference/meta-tags.md#metadata
   [2]: https://github.com/datarobot/mkdocs-redirects
 
-### Linking sources
+### Source link
 
 :octicons-archive-24: Deprecated: 5.5.0 ·
-:octicons-trash-24: Will be removed in 6.0
+:octicons-trash-24: Removal: 6.x
 
 The `source` and `path` keys, which could be added via [Metadata][1], showed
-a source icon at the top right of a document, linking a document to a single
-source file:
+a source icon at the top right corner of a document, linking a document to a
+single source file:
 
 ``` markdown
 ---
@@ -63,10 +64,46 @@ approach is to use the new [icon integration][3]:
 [:octicons-file-code-24: Source](https://github.com/squidfunk/mkdocs-material/blob/master/docs/deprecations.md)
 ```
 
-This will render as:
-
-[:octicons-file-code-24: Source][4]
-
+This will render as [:octicons-file-code-24: Source][4], which can be included
+at arbitrary positions in any document.
 
   [3]: setup/changing-the-logo-and-icons.md#icons
   [4]: https://github.com/squidfunk/mkdocs-material/blob/master/docs/deprecations.md
+
+### Hero
+
+:octicons-archive-24: Deprecated: 5.5.0 ·
+:octicons-trash-24: Removal: 6.x
+
+The `hero` key, which could be added via [Metadata][1], allowed to render a
+simple, text-only and page-local teaser text as part of a document. It could
+be set from front matter with:
+
+``` markdown
+---
+hero: Lorem ipsum dolor sit amet
+---
+```
+
+The recommended way is to [override the `hero` block][5] via [theme
+extension][6] for a specific page, which has the nice side effect that hero
+templates can be shared among multiple pages:
+
+=== "Markdown"
+
+    ``` markdown
+    ---
+    template: overrides/hero.html
+    ---
+    ```
+
+=== "Template"
+
+    ``` jinja
+    {% block hero %}
+      {# Add custom hero here #}
+    {% endblock %}
+    ```
+
+  [5]: customization.md#overriding-blocks
+  [6]: customization.md#extending-the-theme

docs/reference/code-blocks.md

@@ -22,7 +22,7 @@ The [Highlight][3] extension, which is part of [Python Markdown Extensions][5],
 integrates with Material for MkDocs and provides several options for
 configuring syntax highlighting of code blocks:
 
-`use_pygments`{: #use_pygments }
+`use_pygments`{: #use-pygments }
 
 :   :octicons-milestone-24: Default: `true` – This option allows to control
     whether highlighting should be carried out during build time by
@@ -84,7 +84,7 @@ configuring syntax highlighting of code blocks:
           linenums: true
     ```
 
-`linenums_style`{: #linenums_style }
+`linenums_style`{: #linenums-style }
 
 :   :octicons-milestone-24: Default: `table` – The Highlight extension provides
     three ways to add line numbers, all of which are supported by Material for
@@ -283,7 +283,7 @@ The `#!python range()` function is used to generate a sequence of numbers.
 
 ### Adding keyboard keys
 
-When [Keys][19] is enabled, keyboard keys can be inserted with a simple syntax.
+When [Keys][19] is enabled, keyboard keys can be rendered with a simple syntax.
 Consult the [Python Markdown Extensions][16] documentation to learn about all
 available short key codes.
 
@@ -299,9 +299,9 @@ _Result_:
 
   [19]: #keys
 
-### Adding external files
+### Embedding external files
 
-When [Snippets][20] is enabled, content from other files can be inserted, which
+When [Snippets][20] is enabled, content from other files can be embedded, which
 is especially useful to reference and embed the contents of source files
 directly into your project documentation.
 
@@ -320,7 +320,21 @@ _Result_:
 ```
 
 Note that [Snippets][20] is not limited to code blocks, but can be used anywhere
-in a Markdown file to put repeating content into separate files, which is also
+from a document to move repeating content to separate files, which is also
 explained in the [official documentation][16].
 
   [20]: #snippets
+
+## Customization
+
+### Custom syntax theme
+
+[:octicons-file-code-24: Source][21] ·
+:octicons-mortar-board-24: Difficulty: _easy_
+
+If syntax highlighting is done with [Pygments][22], Material for MkDocs
+provides the styles defining the [appeareance][21] of code blocks, which can
+be adjusted with [additional stylesheets][6].
+
+  [21]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/_codehilite.scss
+  [22]: #use-pygments

docs/reference/lists.md

@@ -35,7 +35,7 @@ The [Tasklist][4] extension, which is part of [Python Markdown Extensions][5],
 adds support for lists with styled checkboxes, and provides several options for 
 configuring the style:
 
-`custom_checkbox`{: #custom_checkbox }
+`custom_checkbox`{: #custom-checkbox }
 
 :   :octicons-milestone-24: Default: `false` · This option toggles the rendering
     style of checkboxes, replacing native checkbox styles with beautiful icons, 
@@ -47,7 +47,7 @@ configuring the style:
           custom_checkbox: true
     ```
 
-`clickable_checkbox`{: #clickable_checkbox }
+`clickable_checkbox`{: #clickable-checkbox }
 
 :   :octicons-milestone-24: Default: `false` · This option toggles whether
     checkboxes are clickable. As the state is not persisted, the use of this 

docs/reference/meta-tags.md

@@ -4,8 +4,6 @@ template: overrides/main.html
 
 # Meta tags
 
-<!-- TBD -->
-
 ## Configuration
 
 ### Metadata
@@ -23,12 +21,10 @@ markdown_extensions:
 
 ## Usage
 
-Metadata is written as a series of key-value pairs at the beginning of the
-Markdown document, delimited by a blank line which ends the metadata context.
-Naturally, the metadata is stripped from the document before rendering the
-actual page content and made available to the theme.
-
-Example:
+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.
+Naturally, front matter is stripped from the document before rendering the
+actual page content and made available to the theme:
 
 ``` markdown
 ---
@@ -41,29 +37,14 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
 ...
 ```
 
-See the next section which covers the supported metadata.
-
-### Setting a hero
-
-Material for MkDocs exposes a simple text-only page-local hero via Metadata, as
-you can see on the current page when you scroll to the top. It's as simple as:
-
-``` markdown
-hero: Set heroes with metadata
-```
-
-
-
-accessing that document's URL will automatically redirect to `/new/url`.
-
-### Overrides
-
-#### Page title
+### Setting the page title
 
 The page title can be overridden on a per-document basis:
 
 ``` markdown
+---
 title: Lorem ipsum dolor sit amet
+---
 ```
 
 This will set the `title` tag inside the document `head` for the current page
@@ -71,12 +52,14 @@ to the provided value. It will also override the default behavior of Material
 for MkDocs which appends the site title using a dash as a separator to the page
 title.
 
-#### Page description
+### Setting the page description
 
 The page description can also be overridden on a per-document basis:
 
-``` yaml
+``` markdown
+---
 description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
+---
 ```
 
 This will set the `meta` tag containing the site description inside the

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

@@ -102,7 +102,7 @@ The following options are supported:
           separator: '[\s\-\.]+'
     ```
 
-`prebuild_index`{: #prebuild_index }
+`prebuild_index`{: #prebuild-index }
 
 :   :octicons-milestone-24: Default: `false` · :octicons-beaker-24:
     Experimental – MkDocs can generate a [prebuilt index][7] of all pages during