Updated documentation

CHANGELOG

@@ -1,3 +1,7 @@
+mkdocs-material-8.1.2+insiders-4.5.0 (2021-12-16)
+
+  * Added support for navigation icons
+
 mkdocs-material-8.1.2 (2012-12-15)
 
   * Switched CSS sources to logical properties

docs/insiders/changelog.md

@@ -6,6 +6,10 @@ template: overrides/main.html
 
 ## Material for MkDocs Insiders
 
+### 4.5.0 <small>_ December 16, 2021</small> { id="4.5.0" }
+
+- Added support for navigation icons
+
 ### 4.4.0 <small>_ December 10, 2021</small> { id="4.4.0" }
 
 - Added support for code annotation anchor links (deep linking)

docs/insiders/index.md

@@ -162,6 +162,7 @@ The following features are solely available via Material for MkDocs Insiders:
 
 <div class="mdx-columns" markdown>
 
+- [x] [Navigation icons] :material-new-box:
 - [x] [Code annotations: anchor links] :material-new-box:
 - [x] [Code annotations: strip comments] :material-new-box:
 - [x] [Dismissable announcement bar]
@@ -250,9 +251,11 @@ are released for general availability.
 
 #### $ 12,000 – Piri Piri
 
-- [ ] Text annotations
-- [ ] Navigation icons
+- [x] [Navigation icons]
 - [ ] Navigation pruning
+- [ ] Text annotations
+
+  [Navigation icons]: ../reference/index.md#setting-the-page-icon
 
 ### Goals completed
 

docs/reference/abbreviations.md

@@ -1,5 +1,6 @@
 ---
 template: overrides/main.html
+icon: material/image-size-select-small
 ---
 
 # Abbreviations

docs/reference/admonitions.md

@@ -1,5 +1,6 @@
 ---
 template: overrides/main.html
+icon: material/alert-outline
 ---
 
 # Admonitions

docs/reference/buttons.md

@@ -1,5 +1,6 @@
 ---
 template: overrides/main.html
+icon: material/gesture-tap-button
 ---
 
 # Buttons

docs/reference/code-blocks.md

@@ -1,5 +1,6 @@
 ---
 template: overrides/main.html
+icon: material/code-tags
 ---
 
 # Code blocks

docs/reference/content-tabs.md

@@ -1,5 +1,6 @@
 ---
 template: overrides/main.html
+icon: material/tab
 ---
 
 # Content tabs

docs/reference/data-tables.md

@@ -1,5 +1,6 @@
 ---
 template: overrides/main.html
+icon: material/table-edit
 ---
 
 # Data tables

docs/reference/diagrams.md

@@ -1,5 +1,6 @@
 ---
 template: overrides/main.html
+icon: material/chart-gantt
 ---
 
 # Diagrams

docs/reference/footnotes.md

@@ -1,5 +1,6 @@
 ---
 template: overrides/main.html
+icon: material/format-superscript
 ---
 
 # Footnotes

docs/reference/formatting.md

@@ -1,5 +1,6 @@
 ---
 template: overrides/main.html
+icon: material/format-font
 ---
 
 # Formatting

docs/reference/icons-emojis.md

@@ -1,5 +1,6 @@
 ---
 template: overrides/main.html
+icon: material/emoticon-wink-outline
 ---
 
 # Icons + Emojis

docs/reference/images.md

@@ -1,5 +1,6 @@
 ---
 template: overrides/main.html
+icon: material/image-frame
 ---
 
 # Images

docs/reference/index.md

@@ -2,21 +2,18 @@
 template: overrides/main.html
 ---
 
-# Meta tags
+# Reference
 
-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]
-metadata. While arbitrary `meta` tags can always be added via [customization],
-some common `meta` tags can be configured.
-
-  [Open Graph]: https://ogp.me/
-  [customization]: #customization
+Material for MkDocs is packed with many great features that make technical
+writing a pleasure. This section of the documentation explains how to set up
+a page, and showcases all available specimen that can be used directly from
+within Markdown files.
 
 ## Configuration
 
-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`:
+This configuration allows to set a title and description for a page, change the
+template or define an icon to be rendered in the navigation. Add the following 
+lines to `mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:
@@ -62,15 +59,57 @@ Markdown file:
 
 ``` bash
 ---
-description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
+description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
 ---
 
 # Document title
 ...
 ```
 
-This will set the `meta` tag containing the site description inside the
-document `head` for the current page to the provided value.
+1.  This will set the `meta` tag containing the site description inside the
+    document `head` for the current page to the provided value.
+
+### Setting the page icon
+
+[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-4.5.0][Insiders] ·
+:octicons-beaker-24: Experimental
+
+An icon can be assigned to each page, which is then rendered as part of the
+navigation sidebar. Ensure [Metadata] is enabled and add the following lines
+at the top of a Markdown file:
+
+``` bash
+---
+icon: material/emoticon-happy # (1)!
+---
+
+# Document title
+...
+```
+
+1.  Check out the left sidebar to see icons in action! Also check out our
+    [icon search] to find the perfect icon with a few keystrokes.
+
+  [Insiders]: ../insiders/index.md
+  [icon search]: icons-emojis.md#search
+
+### Setting the page template
+
+If you're using [theme extension] and created a new page template in the
+`overrides` directory, you can enable it for a specific page. Add the following 
+lines at the top of a Markdown file:
+
+``` bash
+---
+template: custom.html
+---
+
+# Document title
+...
+```
+
+  [theme extension]: ../customization.md#extending-the-theme
 
 ## Customization
 
@@ -90,7 +129,6 @@ e.g. to add indexing policies for search engines via the `robots` property:
 {% endblock %}
 ```
 
-  [theme extension]: ../customization.md#extending-the-theme
   [overriding blocks]: ../customization.md#overriding-blocks
 
 #### on a single page

docs/reference/lists.md

@@ -1,5 +1,6 @@
 ---
 template: overrides/main.html
+icon: material/format-list-bulleted
 ---
 
 # Lists

docs/reference/mathjax.md

@@ -1,5 +1,6 @@
 ---
 template: overrides/main.html
+icon: material/alphabet-greek
 ---
 
 # MathJax

docs/setup/extensions/python-markdown.md

@@ -165,8 +165,8 @@ No configuration options are available. See reference for usage:
 
   [Metadata]: https://python-markdown.github.io/extensions/meta_data/
   [Metadata support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
-  [Setting the page title]: ../../reference/meta-tags.md#setting-the-page-title
-  [Setting the page description]: ../../reference/meta-tags.md#setting-the-page-description
+  [Setting the page title]: ../../reference/index.md#setting-the-page-title
+  [Setting the page description]: ../../reference/index.md#setting-the-page-description
   [Adding tags]: ../../setup/setting-up-tags.md#adding-tags
   [Hiding the tags]: ../../setup/setting-up-tags.md#hiding-the-tags
   [Hiding the sidebars]: ../../setup/setting-up-navigation.md#hiding-the-sidebars

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

@@ -272,5 +272,5 @@ default values.
 - [Changing the description]
 
   [Metadata]: extensions/python-markdown.md#metadata
-  [Changing the title]: ../reference/meta-tags.md#setting-the-page-title
-  [Changing the description]: ../reference/meta-tags.md#setting-the-page-description
+  [Changing the title]: ../reference/index.md#setting-the-page-title
+  [Changing the description]: ../reference/index.md#setting-the-page-description

mkdocs.yml

@@ -91,9 +91,10 @@ plugins:
   - redirects:
       redirect_maps:
         changelog/insiders.md: insiders/changelog.md
-        upgrading.md: upgrade.md
+        reference/meta-tags.md: reference/index.md
         reference/variables.md: https://mkdocs-macros-plugin.readthedocs.io/
         sponsorship.md: insiders/index.md
+        upgrading.md: upgrade.md
   - minify:
       minify_html: true
 
@@ -189,6 +190,7 @@ nav:
       - Python Markdown: setup/extensions/python-markdown.md
       - Python Markdown Extensions: setup/extensions/python-markdown-extensions.md
   - Reference:
+    - reference/index.md
     - Abbreviations: reference/abbreviations.md
     - Admonitions: reference/admonitions.md
     - Buttons: reference/buttons.md
@@ -202,7 +204,6 @@ nav:
     - Images: reference/images.md
     - Lists: reference/lists.md
     - MathJax: reference/mathjax.md
-    - Meta tags: reference/meta-tags.md
   - Insiders:
     - insiders/index.md
     - Getting started: