Updated documentation with more screenshots and examples

CHANGELOG

@@ -1,3 +1,8 @@
+mkdocs-material-6.1.4+insiders-1.9.0 (2020-11-07)
+
+  * Added support for hidding navigation and table of contents on any page
+  * Removed autohiding table of contents when empty
+
 mkdocs-material-6.1.4 (2020-11-07)
 
   * Fixed sidebar jitter when scrolling footer into view

docs/reference/variables.md

@@ -90,13 +90,11 @@ The unit price is 12.50.
 
 ### Using variables in snippets
 
-You may want to use variables in snippets, for example, when describing the same
-procedure in multiple contexts where only one piece of information differs. This
-does not work with snippets that are included using the [Snippets][2] extension.
-Instead, you can use the [macros][3] plugin for defining snippets.
-
-To this end, add the snippet location using the `include_dir` parameter to the 
-plugin's configuration in `mkdocs.yml`, for example:
+In order to use variables in snippets, e.g., when using the same snippet in
+multiple contexts. This does not work with snippets that are included using the
+[Snippets][2] extension. Instead, you can use the [macros][3] plugin for
+defining snippets. Add the snippet location using the `include_dir` parameter
+to the plugin configuration in `mkdocs.yml`, for example:
 
 ``` yaml
 plugins:
@@ -105,14 +103,13 @@ plugins:
       include_dir: snippets
 ```
 
-In your Markdown file, you can include snippets with Jinja's [`include`][4]
-function:
+In your Markdown file, include snippets with Jinja's [`include`][4] function:
 
 ``` markdown
 {% include "definitions.md" %}
 ```
 
-This example illustrates the behavior:
+_Example_:
 
 === "snippets/definitions.md"
 

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

@@ -92,6 +92,6 @@ In order to integrate another JavaScript-based comment system provider, you can
 {% endblock %}
 ```
 
-  [8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L318-L321
+  [8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L325-L328
   [9]: ../customization.md#extending-the-theme
   [10]: ../customization.md#overriding-blocks

docs/setup/adding-a-git-repository.md

@@ -93,7 +93,7 @@ behavior can be changed by setting [`edit_uri`][9] in `mkdocs.yml`:
     edit_uri: ""
     ```
 
-  [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L285-L294
+  [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L292-L301
   [6]: https://github.com/
   [7]: https://about.gitlab.com/
   [8]: https://bitbucket.org/

docs/setup/changing-the-fonts.md

@@ -30,7 +30,7 @@ theme:
 
 The typeface will be loaded in 300, 400, _400i_ and __700__.
 
-  [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L100-L125
+  [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L107-L132
   [3]: https://fonts.google.com/specimen/Roboto
 
 ### Proportional font

docs/setup/changing-the-language.md

@@ -94,7 +94,7 @@ work properly. Material for MkDocs relies on [lunr-languages][4] to provide this
 functionality. See the guide detailing how to [set up site search][5] for
 more information.
 
-  [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/main/index.ts#L90-L112
+  [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/main/index.ts#L77-L108
   [4]: https://github.com/MihaiValentin/lunr-languages
   [5]: setting-up-site-search.md
 
@@ -132,7 +132,7 @@ directionality:
   })
 </script>
 
-  [6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L178
+  [6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L185
 
 ## Customization
 

docs/setup/changing-the-logo-and-icons.md

@@ -53,7 +53,7 @@ theme:
   favicon: images/favicon.png
 ```
 
-  [4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L53-L54
+  [4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L60-L61
 
 ### Icons
 

docs/setup/setting-up-navigation.md

@@ -55,8 +55,16 @@ theme:
     - navigation.tabs
 ```
 
+=== "With tabs"
+
+    [![With tabs][7]][7]
+
+=== "Without tabs"
+
+    [![Without tabs][8]][8]
+
 Note that all __top-level pages__ (i.e. all top-level entries that directly
-refer to an `*.md` file) defined inside the [`nav`][7] entry of `mkdocs.yml`
+refer to an `*.md` file) defined inside the [`nav`][9] entry of `mkdocs.yml`
 will be grouped under the first tab which will receive the title of the first
 page.
 
@@ -93,19 +101,21 @@ sections. This is illustrated in the following example:
         - Page 2.3
     ```
 
-Note that tabs are only shown for larger screens, so make sure that navigation
-is plausible on mobile devices. As another example, see the [`mkdocs.yml`][8]
-used to render these pages.
+Also note that tabs are only shown for larger screens, so make sure that
+navigation is plausible on mobile devices. As another example, see the
+[`mkdocs.yml`][10] used to render these pages.
 
   [6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/tabs.html
-  [7]: https://www.mkdocs.org/user-guide/configuration/#nav
-  [8]: https://github.com/squidfunk/mkdocs-material/blob/master/mkdocs.yml
+  [7]: ../assets/screenshots/navigation-tabs.png
+  [8]: ../assets/screenshots/navigation.png
+  [9]: https://www.mkdocs.org/user-guide/configuration/#nav
+  [10]: https://github.com/squidfunk/mkdocs-material/blob/master/mkdocs.yml
 
 ### Navigation sections
 
-[:octicons-file-code-24: Source][9] ·
+[:octicons-file-code-24: Source][11] ·
 :octicons-unlock-24: Feature flag ·
-[:octicons-heart-fill-24:{: .tx-heart } Insiders only][9]{: .tx-insiders }
+[:octicons-heart-fill-24:{: .tx-heart } Insiders only][11]{: .tx-insiders }
 
 When _sections_ are enabled, top-level sections are rendered as groups in the
 sidebar on big screens (but not when the sidebar is hidden). It can be enabled
@@ -117,20 +127,26 @@ theme:
     - navigation.sections
 ```
 
+=== "With sections"
+
+    [![With sections][12]][12]
+
+=== "Without sections"
+
+    [![Without sections][8]][8]
+
+  [11]: ../insiders.md
+  [12]: ../assets/screenshots/navigation-sections.png
+
 Both feature flags, _tabs_ and _sections_, can be combined with each other. If
 both feature flags are enabled, sections are rendered for 2nd level navigation
 items.
 
-[![Search highlighting][10]][10]
-
-  [9]: ../insiders.md
-  [10]: ../assets/screenshots/navigation-sections.png
-
 ### Navigation expansion
 
-[:octicons-file-code-24: Source][9] ·
+[:octicons-file-code-24: Source][11] ·
 :octicons-unlock-24: Feature flag ·
-[:octicons-heart-fill-24:{: .tx-heart } Insiders only][9]{: .tx-insiders }
+[:octicons-heart-fill-24:{: .tx-heart } Insiders only][11]{: .tx-insiders }
 
 When _expansion_ is enabled, the left sidebar will expand all collapsible
 subsections by default, so the user doesn't have to open subsections manually.
@@ -142,11 +158,21 @@ theme:
     - navigation.expand
 ```
 
+=== "With expansion"
+
+    [![With expansion][13]][13]
+
+=== "Without expansion"
+
+    [![Without expansion][8]][8]
+
+  [13]: ../assets/screenshots/navigation-expand.png
+
 ### Table of contents
 
-[:octicons-file-code-24: Source][11] · [:octicons-workflow-24: Extension][12]
+[:octicons-file-code-24: Source][14] · [:octicons-workflow-24: Extension][15]
 
-The [Table of contents][13] extension, which is part of the standard Markdown
+The [Table of contents][16] extension, which is part of the standard Markdown
 library, provides some options that are supported by Material for MkDocs to
 customize its appearance:
 
@@ -178,7 +204,7 @@ customize its appearance:
 :   :octicons-milestone-24: Default: `headerid.slugify` – This option allows for 
     customization of the slug function. For some languages, the default may not
     produce good and readable identifiers. Consider using another slug function
-    like for example those from [Python Markdown Extensions][14]:
+    like for example those from [Python Markdown Extensions][17]:
 
     === "Unicode"
 
@@ -219,39 +245,63 @@ customize its appearance:
               toc_depth: 0
         ```
 
+    Note that MkDocs will not generate [anchor links][18] for levels outside
+    the range defined with `toc_depth`. However, Material for MkDocs also allows
+    to [hide the table of contents][19] on a specific page while keeping
+    permalinks.
+
 _Material for MkDocs doesn't provide official support for the other options of
 this extension, so they may be supported but can also yield weird results. Use
 them at your own risk._
 
-  [11]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
-  [12]: https://python-markdown.github.io/extensions/toc/
-  [13]: https://python-markdown.github.io/extensions/toc/#usage
-  [14]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
+  [14]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
+  [15]: https://python-markdown.github.io/extensions/toc/
+  [16]: https://python-markdown.github.io/extensions/toc/#usage
+  [17]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
+  [18]: #permalink
+  [19]: #hide-the-sidebars
 
-#### Automatic hiding
+### Hide the sidebars
 
-[:octicons-file-code-24: Source][3] ·
-:octicons-unlock-24: Feature flag ·
-:octicons-beaker-24: Experimental ·
-[:octicons-heart-fill-24:{: .tx-heart } Insiders only][3]{: .tx-insiders }
+[:octicons-file-code-24: Source][11] ·
+[:octicons-heart-fill-24:{: .tx-heart } Insiders only][11]{: .tx-insiders }
 
-When _autohiding_ is enabled, the table of contents is automatically hidden
-when the current page defines no headings, or only a single `h1` heading to be
-rendered, so content stretches.
-
-It can be enabled via `mkdocs.yml` with:
+Sometimes it's desirable to hide the navigation sidebar or table of contents,
+especially when there's a single navigation item. This can be done for any
+page using the [Metadata][20] extension:
 
 ``` yaml
-theme:
-  features:
-    - toc.autohide
+---
+hide:
+  - navigation # Hide navigation
+  - toc        # Hide table of contents
+---
+
+...
 ```
 
+=== "Hide navigation"
+
+    [![Hide navigation][21]][21]
+
+=== "Hide table of contents"
+
+    [![Hide table of contents][22]][22]
+
+=== "Hide both"
+
+    [![Hide navigation and table of contents][23]][23]
+
+  [20]: ../../reference/meta-tags/#metadata
+  [21]: ../assets/screenshots/hide-navigation.png
+  [22]: ../assets/screenshots/hide-toc.png
+  [23]: ../assets/screenshots/hide-navigation-toc.png
+
 ## Customization
 
 ### Keyboard shortcuts
 
-[:octicons-file-code-24: Source][15] ·
+[:octicons-file-code-24: Source][24] ·
 :octicons-mortar-board-24: Difficulty: _easy_
 
 Material for MkDocs includes several keyboard shortcuts that make it possible
@@ -277,7 +327,7 @@ to navigate your project documentation via keyboard. There're two modes:
     * ++n++ , ++period++ : go to next page
 
 Let's say you want to bind some action to the ++x++ key. By using [additional
-JavaScript][16], you can subscribe to the `keyboard$` observable and attach
+JavaScript][25], you can subscribe to the `keyboard$` observable and attach
 your custom event listener:
 
 ``` js
@@ -293,5 +343,5 @@ The call to `#!js key.claim()` will essentially execute `#!js preventDefault()`
 on the underlying event, so the keypress will not propagate further and touch
 other event listeners.
 
-  [15]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts
-  [16]: ../customization.md#additional-javascript
+  [24]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts
+  [25]: ../customization.md#additional-javascript

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

@@ -204,7 +204,7 @@ combination with @squidfunk's [iframe-worker][15] polyfill.
 
 For setup instructions, refer to the [official documentation][16].
 
-  [13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L360-L372
+  [13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L368-L369
   [14]: https://github.com/wilhelmer/mkdocs-localsearch/
   [15]: https://github.com/squidfunk/iframe-worker
   [16]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5