diff --git a/CHANGELOG b/CHANGELOG
index a4f6710f8..df7d50d90 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -1,3 +1,7 @@
+mkdocs-material-6.2.7+insiders-1.17.0 (2021-01-31)
+
+ * Added support for section index pages
+
mkdocs-material-6.2.7 (2021-01-31)
* Fixed #2251: Updated Docker image to latest Alpine Linux
diff --git a/docs/assets/screenshots/navigation-index-off.png b/docs/assets/screenshots/navigation-index-off.png
new file mode 100644
index 000000000..86beb6f15
Binary files /dev/null and b/docs/assets/screenshots/navigation-index-off.png differ
diff --git a/docs/assets/screenshots/navigation-index-on.png b/docs/assets/screenshots/navigation-index-on.png
new file mode 100644
index 000000000..5db82df1c
Binary files /dev/null and b/docs/assets/screenshots/navigation-index-on.png differ
diff --git a/docs/changelog/insiders.md b/docs/changelog/insiders.md
index 1ecbc4ae5..4add91c3c 100644
--- a/docs/changelog/insiders.md
+++ b/docs/changelog/insiders.md
@@ -6,6 +6,10 @@ template: overrides/main.html
## Material for MkDocs Insiders
+### 1.17.0 _ January 31, 2021
+
+- Added support for section index pages
+
### 1.16.1 _ January 26, 2021
- Fixed #2249: Instant loading + sticky tabs result in invalid links
diff --git a/docs/insiders.md b/docs/insiders.md
index fe6564faf..d48e71045 100644
--- a/docs/insiders.md
+++ b/docs/insiders.md
@@ -100,17 +100,18 @@ The following features are currently exclusively available to sponsors:
-- [x] [Latest release tag :material-new-box:][15]
+- [x] [Section index pages :material-new-box:][21]
+- [x] [Latest release tag][15]
- [x] [Color palette toggle][16]
- [x] [Versioning][14]
- [x] [Site language selection][13]
- [x] [Sticky navigation tabs][20]
-- [x] [Native Mermaid.js integration][22]
+- [x] [Native Mermaid.js integration][23]
- [x] [Admonition inline blocks][12]
- [x] [Search suggestions][17]
- [x] [Search highlighting][18]
- [x] [Search sharing][19]
-- [x] [Remove generator notice][21]
+- [x] [Remove generator notice][22]
@@ -160,21 +161,23 @@ the public for general availability.
#### $ 3,000 – Caribbean Red
- [x] [Sticky navigation tabs][20]
-- [x] [Remove generator notice][21]
-- [ ] Support for index pages
+- [x] [Section index pages][21]
+- [x] [Remove generator notice][22]
[20]: setup/setting-up-navigation.md#sticky-navigation-tabs
- [21]: setup/setting-up-the-footer.md#remove-generator
+ [21]: setup/setting-up-navigation.md#section-index-pages
+ [22]: setup/setting-up-the-footer.md#remove-generator
+
#### $ 5,000 – Aji Panca
-- [x] [Native Mermaid.js integration][22]
+- [x] [Native Mermaid.js integration][23]
- [22]: reference/diagrams.md
+ [23]: reference/diagrams.md
#### Future
-- [ ] [Material for MkDocs Live Edit][23]
+- [ ] [Material for MkDocs Live Edit][24]
- [ ] Improved search result summaries
- [ ] List of last searches
- [ ] Table of contents follows active anchor
@@ -184,7 +187,7 @@ the public for general availability.
- [ ] New layouts and styles (e.g. vertical)
- [ ] ... and much more ...
- [23]: https://twitter.com/squidfunk/status/1338252230265360391
+ [24]: https://twitter.com/squidfunk/status/1338252230265360391
### Goals completed
@@ -220,10 +223,10 @@ implemented behind feature flags; all configuration changes are
backward-compatible. This means that your users will be able to build the
documentation locally with Material for MkDocs and when they push their changes,
it can be built with Insiders (e.g. as part of GitHub Actions). Thus, it's
-recommended to [install Insiders][24] only in CI, as you don't want to expose
+recommended to [install Insiders][25] only in CI, as you don't want to expose
your `GH_TOKEN` to users.
- [24]: publishing-your-site.md#github-pages
+ [25]: publishing-your-site.md#github-pages
### Terms
@@ -232,7 +235,7 @@ commercial project. Can we use Insiders under the same terms and conditions?_
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][25]. However, we kindly ask you to respect the following
+by the [MIT license][26]. However, we kindly ask you to respect the following
guidelines:
- Please __don't distribute the source code__ of Insiders. You may freely use
@@ -243,7 +246,7 @@ guidelines:
- If you cancel your subscription, you're removed as a collaborator and will
miss out on future updates of 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][26].
+ [GitHub deletes private forks][27].
- [25]: license.md
- [26]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository
+ [26]: license.md
+ [27]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository
diff --git a/docs/setup/setting-up-navigation.md b/docs/setup/setting-up-navigation.md
index 7f349b486..1c833bc4b 100644
--- a/docs/setup/setting-up-navigation.md
+++ b/docs/setup/setting-up-navigation.md
@@ -161,11 +161,56 @@ theme:
[14]: ../assets/screenshots/navigation-expand.png
+### Section index pages
+
+[:octicons-file-code-24: Source][9] ·
+:octicons-unlock-24: Feature flag ·
+:octicons-beaker-24: Experimental ·
+[:octicons-heart-fill-24:{: .tx-heart } Insiders only][9]{: .tx-insiders }
+
+When _section indexes_ are enabled, documents can be directly attached to
+sections, which is especially useful for providing overview pages. This can be
+enabled via `mkdocs.yml` with:
+
+``` yaml
+theme:
+ features:
+ - navigation.indexes
+```
+
+=== "With section index pages"
+
+ [![With expansion][15]][15]
+
+=== "Without section index pages"
+
+ [![Without expansion][16]][16]
+
+In order to link a page to the section, create a new Markdown document with the
+name `index.md` in the respective folder, and add it to the beginning of your
+navigation section like so:
+
+``` yaml
+nav:
+ - Section:
+ - section/index.md
+ - Page 1: section/page-1.md
+ ...
+ - Page n: section/page-n.md
+```
+
+_This feature flag can be combined with all other feature flags, e.g. [tabs][1]
+and [sections][2], except for when integrating the table of contents into the
+navigation with_ `toc.integrate`.
+
+ [15]: ../assets/screenshots/navigation-index-on.png
+ [16]: ../assets/screenshots/navigation-index-off.png
+
### Table of contents
-[:octicons-file-code-24: Source][15] · [:octicons-workflow-24: Extension][16]
+[:octicons-file-code-24: Source][17] · [:octicons-workflow-24: Extension][18]
-The [Table of contents][17] extension, which is part of the standard Markdown
+The [Table of contents][19] extension, which is part of the standard Markdown
library, provides some options that are supported by Material for MkDocs to
customize its appearance:
@@ -197,7 +242,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][18]:
+ like for example those from [Python Markdown Extensions][20]:
=== "Unicode"
@@ -238,25 +283,25 @@ customize its appearance:
toc_depth: 0
```
- Note that MkDocs will not generate [anchor links][19] for levels outside
+ Note that MkDocs will not generate [anchor links][21] for levels outside
the range defined with `toc_depth`. However, Material for MkDocs also allows
- to [hide the table of contents][20] on a specific page while keeping
+ to [hide the table of contents][22] 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._
- [15]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
- [16]: https://python-markdown.github.io/extensions/toc/
- [17]: https://python-markdown.github.io/extensions/toc/#usage
- [18]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
- [19]: #permalink
- [20]: #hide-the-sidebars
+ [17]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
+ [18]: https://python-markdown.github.io/extensions/toc/
+ [19]: https://python-markdown.github.io/extensions/toc/#usage
+ [20]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
+ [21]: #permalink
+ [22]: #hide-the-sidebars
#### Navigation integration
-[:octicons-file-code-24: Source][21] ·
+[:octicons-file-code-24: Source][23] ·
:octicons-unlock-24: Feature flag
When _integration_ is enabled, the table of contents is rendered as part of
@@ -271,14 +316,14 @@ theme:
=== "Integrate table of contents"
- [![Integrate table of contents][22]][22]
+ [![Integrate table of contents][24]][24]
=== "Separate table of contents"
[![Separate table of contents][8]][8]
- [21]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_nav.scss
- [22]: ../assets/screenshots/toc-integrate.png
+ [23]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_nav.scss
+ [24]: ../assets/screenshots/toc-integrate.png
The content section will now always stretch to the right side, resulting in
more space for your content. This feature flag can be combined with all other
@@ -286,12 +331,12 @@ feature flags, e.g. [tabs][1] and [sections][2].
### Hide the sidebars
-[:octicons-file-code-24: Source][23] ·
+[:octicons-file-code-24: Source][25] ·
:octicons-note-24: Metadata
Sometimes it's desirable to hide the navigation and/or table of contents
sidebar, especially when there's a single navigation item. This can be done for
-any page using the [Metadata][24] extension:
+any page using the [Metadata][26] extension:
``` yaml
---
@@ -305,27 +350,27 @@ hide:
=== "Hide navigation"
- [![Hide navigation][25]][25]
+ [![Hide navigation][27]][27]
=== "Hide table of contents"
- [![Hide table of contents][26]][26]
+ [![Hide table of contents][28]][28]
=== "Hide both"
- [![Hide navigation and table of contents][27]][27]
+ [![Hide navigation and table of contents][29]][29]
- [23]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
- [24]: ../../reference/meta-tags/#metadata
- [25]: ../assets/screenshots/hide-navigation.png
- [26]: ../assets/screenshots/hide-toc.png
- [27]: ../assets/screenshots/hide-navigation-toc.png
+ [25]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
+ [26]: ../../reference/meta-tags/#metadata
+ [27]: ../assets/screenshots/hide-navigation.png
+ [28]: ../assets/screenshots/hide-toc.png
+ [29]: ../assets/screenshots/hide-navigation-toc.png
## Customization
### Keyboard shortcuts
-[:octicons-file-code-24: Source][28] ·
+[:octicons-file-code-24: Source][30] ·
:octicons-mortar-board-24: Difficulty: _easy_
Material for MkDocs includes several keyboard shortcuts that make it possible
@@ -351,7 +396,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][29], you can subscribe to the `keyboard$` observable and attach
+JavaScript][31], you can subscribe to the `keyboard$` observable and attach
your custom event listener:
``` js
@@ -367,12 +412,12 @@ 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.
- [28]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts
- [29]: ../customization.md#additional-javascript
+ [30]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts
+ [31]: ../customization.md#additional-javascript
### Content area width
-[:octicons-file-code-24: Source][30] ·
+[:octicons-file-code-24: Source][32] ·
:octicons-mortar-board-24: Difficulty: _easy_
The width of the content area is set so the length of each line doesn't exceed
@@ -381,7 +426,7 @@ is a reasonable default, as longer lines tend to be harder to read, it may be
desirable to increase the overall width of the content area, or even make it
stretch to the entire available space.
-This can easily be achieved with an [additional stylesheet][31] and a few lines
+This can easily be achieved with an [additional stylesheet][33] and a few lines
of CSS:
=== "Increase width"
@@ -400,5 +445,5 @@ of CSS:
}
```
- [30]: https://github.com/squidfunk/mkdocs-material/blob/aeaa00a625abf952f355164de02c539b061e6127/src/assets/stylesheets/main/layout/_base.scss
- [31]: ../customization.md#additional-css
+ [32]: https://github.com/squidfunk/mkdocs-material/blob/aeaa00a625abf952f355164de02c539b061e6127/src/assets/stylesheets/main/layout/_base.scss
+ [33]: ../customization.md#additional-css