Added documentation for navigation sections

docs/insiders.md

@@ -65,26 +65,28 @@ for MkDocs Insiders. You can click on each feature to learn more about it:
 - [x] [Search suggestions help to save keystrokes][14]
 - [x] [Highlighting of matched search terms in content area][15]
 - [x] Search goes to first result on ++enter++ (I'm feeling lucky)
-- [x] [Navigation can always be expanded via configuration][16]
+- [x] [Navigation can be grouped into sections][16]
-- [x] [Header can be automatically hidden on scrolling][17]
+- [x] [Navigation can always be expanded via configuration][17]
-- [x] [Table of contents can be automatically hidden when empty][18]
+- [x] [Header can be automatically hidden on scrolling][18]
+- [x] [Table of contents can be automatically hidden when empty][19]
 
   [11]: setup/setting-up-the-footer.md#remove-generator
   [12]: setup/changing-the-colors.md#color-palette-toggle
   [13]: setup/setting-up-versioning.md#versioning
   [14]: setup/setting-up-site-search.md#search-suggestions
   [15]: setup/setting-up-site-search.md#search-highlighting
-  [16]: setup/setting-up-navigation.md#navigation-expansion
+  [16]: setup/setting-up-navigation.md#navigation-sections
-  [17]: setup/setting-up-the-header.md#automatic-hiding
+  [17]: setup/setting-up-navigation.md#navigation-expansion
-  [18]: setup/setting-up-navigation.md#automatic-hiding
+  [18]: setup/setting-up-the-header.md#automatic-hiding
+  [19]: setup/setting-up-navigation.md#automatic-hiding
 
 ## Roadmap
 
 The following list of funding goals – named after varieties of chili peppers 
-[I'm growing on my balcony][19] – shows which features are already available
+[I'm growing on my balcony][20] – shows which features are already available
 in Material for MkDocs Insiders.
 
-  [19]: https://www.instagram.com/squidfunk/
+  [20]: https://www.instagram.com/squidfunk/
 
 ### Madame Jeanette
 
@@ -100,9 +102,10 @@ in Material for MkDocs Insiders.
 [:octicons-flame-24: Funding goal: __$1,000__][6] ·
 :octicons-lock-24: Status: _exclusive_
 
-- [x] [Navigation can always be expanded via configuration][16]
+- [x] [Navigation can be grouped into sections][16]
-- [x] [Header can be automatically hidden on scrolling][17]
+- [x] [Navigation can always be expanded via configuration][17]
-- [x] [Table of contents can be automatically hidden when empty][18]
+- [x] [Header can be automatically hidden on scrolling][18]
+- [x] [Table of contents can be automatically hidden when empty][19]
 - [ ] Table of contents can be moved into navigation for more space
 - [ ] Better support for wide screens, i.e. more horizontal space
 
@@ -156,10 +159,10 @@ improvements (e.g. search) do not require any changes to existing configuration.
 This means that your users will be able to build the docs locally with the
 regular version and when they push their changes to CI/CD, they will be built
 with Material for MkDocs Insiders. For this reason, it's recommended to
-[install Insiders][20] only in CI, as you don't want to expose your `GH_TOKEN`
+[install Insiders][21] only in CI, as you don't want to expose your `GH_TOKEN`
 to users.
 
-  [20]: publishing-your-site.md#github-pages
+  [21]: publishing-your-site.md#github-pages
 
 ### Terms
 
@@ -169,7 +172,7 @@ terms?_
 
 Yes. Whether you're an individual or a company, you may use _Material for MkDocs
 Insiders_ precisely under the same terms as Material for MkDocs, which are given
-by the [MIT license][21]. However, we kindly ask you to respect the following
+by the [MIT license][22]. However, we kindly ask you to respect the following
 guidelines:
 
 - Please __don't distribute the source code__ from Material for MkDocs Insiders.
@@ -180,7 +183,7 @@ guidelines:
 - If you cancel your subscription, you're removed as a collaborator and will
   miss out on future updates of Material for MkDocs Insiders. However, you may
   __use the latest version__ that's available to you __as long as you like__.
-  Just remember that __[GitHub deletes private forks][22]__.
+  Just remember that __[GitHub deletes private forks][23]__.
 
-  [21]: license.md
+  [22]: license.md
-  [22]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository
+  [23]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository

docs/setup/setting-up-navigation.md

@@ -6,17 +6,22 @@ template: overrides/main.html
 
 A clear and concise navigation structure is an important aspect of good project 
 documentation. Material for MkDocs provides several options to configure the
-behavior of navigational elements, some of those through _feature flags_.
+behavior of navigational elements, including [tabs][1] and [sections][2], and
+its flag-ship feature: [instant loading][3].
+
+  [1]: #navigation-tabs
+  [2]: #navigation-sections
+  [3]: #instant-loading
 
 ## Configuration
 
 ### Instant loading
 
-[:octicons-file-code-24: Source][1] · 
+[:octicons-file-code-24: Source][4] ·
 :octicons-unlock-24: Feature flag
 
-When _instant loading_ is activated, clicks on all internal links will be
+When _instant loading_ is enabled, clicks on all internal links will be
-intercepted and dispatched via [XHR][2] without fully reloading the page. It
+intercepted and dispatched via [XHR][5] without fully reloading the page. It
 can be enabled via `mkdocs.yml` with:
 
 ``` yaml
@@ -31,34 +36,17 @@ Single Page Application__, which is especially useful for large documentation
 sites that come with a massive search index, as the search index will now
 remain intact in-between document switches.
 
-  [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/instant/index.ts
+_Material for MkDocs is the only MkDocs theme offering this feature._
-  [2]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
 
-### Navigation expansion
+  [4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/instant/index.ts
-
+  [5]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
-[: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 }
-
-When `navigation.expand` is activated, the left sidebar will expand all
-collapsible subsections by default, so the user doesn't have to do it manually.
-It can be enabled via `mkdocs.yml` with:
-
-``` yaml
-theme:
-  features:
-    - navigation.expand
-```
-
-  [3]: ../insiders.md
 
 ### Navigation tabs
 
-[:octicons-file-code-24: Source][4] · :octicons-unlock-24: Feature flag
+[:octicons-file-code-24: Source][6] · :octicons-unlock-24: Feature flag
 
-When _tabs_ are activated, top-level sections are rendered in a menu layer
+When _tabs_ are enabled, top-level sections are rendered in a menu layer below
-below the header on big screens (but not when the sidebar is hidden). It can be
+the header on big screens (but not when the sidebar is hidden). They can be
 enabled via `mkdocs.yml` with:
 
 ``` yaml
@@ -68,7 +56,7 @@ theme:
 ```
 
 Note that all __top-level pages__ (i.e. all top-level entries that directly
-refer to an `*.md` file) defined inside the [`nav`][5] entry of `mkdocs.yml`
+refer to an `*.md` file) defined inside the [`nav`][7] entry of `mkdocs.yml`
 will be grouped under the first tab which will receive the title of the first
 page.
 
@@ -106,18 +94,59 @@ sections. This is illustrated in the following example:
     ```
 
 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`][6]
+is plausible on mobile devices. As another example, see the [`mkdocs.yml`][8]
 used to render these pages.
 
-  [4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/tabs.html
+  [6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/tabs.html
-  [5]: https://www.mkdocs.org/user-guide/configuration/#nav
+  [7]: https://www.mkdocs.org/user-guide/configuration/#nav
-  [6]: https://github.com/squidfunk/mkdocs-material/blob/master/mkdocs.yml
+  [8]: https://github.com/squidfunk/mkdocs-material/blob/master/mkdocs.yml
+
+### Navigation sections
+
+[:octicons-file-code-24: Source][9] ·
+:octicons-unlock-24: Feature flag ·
+[:octicons-heart-fill-24:{: .tx-heart } Insiders only][9]{: .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
+via `mkdocs.yml`:
+
+``` yaml
+theme:
+  features:
+    - navigation.sections
+```
+
+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-unlock-24: Feature flag ·
+[:octicons-heart-fill-24:{: .tx-heart } Insiders only][9]{: .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.
+It can be enabled via `mkdocs.yml` with:
+
+``` yaml
+theme:
+  features:
+    - navigation.expand
+```
 
 ### Table of contents
 
-[:octicons-file-code-24: Source][7] · [:octicons-workflow-24: Extension][8]
+[:octicons-file-code-24: Source][11] · [:octicons-workflow-24: Extension][12]
 
-The [Table of contents][9] extension, which is part of the standard Markdown
+The [Table of contents][13] extension, which is part of the standard Markdown
 library, provides some options that are supported by Material for MkDocs to
 customize its appearance:
 
@@ -149,7 +178,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][10]:
+    like for example those from [Python Markdown Extensions][14]:
 
     === "Unicode"
 
@@ -194,10 +223,10 @@ _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._
 
-  [7]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
+  [11]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
-  [8]: https://python-markdown.github.io/extensions/toc/
+  [12]: https://python-markdown.github.io/extensions/toc/
-  [9]: https://python-markdown.github.io/extensions/toc/#usage
+  [13]: https://python-markdown.github.io/extensions/toc/#usage
-  [10]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
+  [14]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
 
 #### Automatic hiding
 
@@ -206,7 +235,7 @@ them at your own risk._
 :octicons-beaker-24: Experimental ·
 [:octicons-heart-fill-24:{: .tx-heart } Insiders only][3]{: .tx-insiders }
 
-When _autohiding_ is activated, the table of contents is automatically hidden
+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.
 
@@ -222,7 +251,7 @@ theme:
 
 ### Keyboard shortcuts
 
-[:octicons-file-code-24: Source][11] ·
+[:octicons-file-code-24: Source][15] ·
 :octicons-mortar-board-24: Difficulty: _easy_
 
 Material for MkDocs includes several keyboard shortcuts that make it possible
@@ -248,7 +277,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][12], you can subscribe to the `keyboard$` observable and attach
+JavaScript][16], you can subscribe to the `keyboard$` observable and attach
 your custom event listener:
 
 ``` js
@@ -264,5 +293,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.
 
-  [11]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts
+  [15]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts
-  [12]: ../customization.md#additional-javascript
+  [16]: ../customization.md#additional-javascript

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

@@ -137,7 +137,7 @@ them at your own risk._
 :octicons-beaker-24: Experimental ·
 [:octicons-heart-fill-24:{: .tx-heart } Insiders only][8]{: .tx-insiders }
 
-When _search suggestions_ are activated, the search will display the likeliest
+When _search suggestions_ are enabled, the search will display the likeliest
 completion for the last word, saving the user many key strokes by accepting the
 suggestion with ++arrow-right++
 
@@ -170,7 +170,7 @@ Insiders._
 :octicons-beaker-24: Experimental ·
 [:octicons-heart-fill-24:{: .tx-heart } Insiders only][8]{: .tx-insiders }
 
-When _search highlighting_ is activated and a user clicks on a search result,
+When _search highlighting_ is enabled and a user clicks on a search result,
 Material for MkDocs will highlight all occurrences after following the link.
 It can be enabled via `mkdocs.yml` with:
 

docs/setup/setting-up-the-header.md

@@ -21,7 +21,7 @@ It also includes the [search bar][1] and a place to display your project's
 :octicons-beaker-24: Experimental ·
 [:octicons-heart-fill-24:{: .tx-heart } Insiders only][3]{: .tx-insiders }
 
-When _autohiding_ is activated, the header is automatically hidden when the
+When _autohiding_ is enabled, the header is automatically hidden when the
 user scrolls past a certain threshold, leaving more space for content. It can
 be enabled via `mkdocs.yml` with: