From accc2a34d15635884448d0c61b9b7f8301c0fddb Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sun, 31 Jan 2021 18:51:49 +0100 Subject: [PATCH] Added reference to mkdocs-section-index plugin --- docs/setup/setting-up-navigation.md | 90 ++++++++++++++++------------- 1 file changed, 49 insertions(+), 41 deletions(-) diff --git a/docs/setup/setting-up-navigation.md b/docs/setup/setting-up-navigation.md index 1c833bc4b..f288e668d 100644 --- a/docs/setup/setting-up-navigation.md +++ b/docs/setup/setting-up-navigation.md @@ -168,9 +168,9 @@ theme: :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: +When _section index pages_ are enabled, documents can be directly attached to +sections, which is particularly useful for providing overview pages. This can +be enabled via `mkdocs.yml` with: ``` yaml theme: @@ -186,9 +186,9 @@ theme: [![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: +In order to link a page to a section, create a new document with the name +`index.md` in the respective folder, and add it to the beginning of your +navigation section: ``` yaml nav: @@ -200,17 +200,25 @@ nav: ``` _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`. +and [sections][2], except for table of contents [navigation integration][17]. +Note that it doesn't rely on third-party plugins[^2]._ + + [^2]: + If you don't want to use the native integration, the + [mkdocs-section-index][18] plugin might be an alternative. However, note + that this plugin may not be compatible with all features offered by Material + for MkDocs, e.g. [tabs][1] and [sections][2]. [15]: ../assets/screenshots/navigation-index-on.png [16]: ../assets/screenshots/navigation-index-off.png + [17]: #navitation-intergation + [18]: https://github.com/oprypin/mkdocs-section-index ### Table of contents -[:octicons-file-code-24: Source][17] · [:octicons-workflow-24: Extension][18] +[:octicons-file-code-24: Source][19] · [:octicons-workflow-24: Extension][20] -The [Table of contents][19] extension, which is part of the standard Markdown +The [Table of contents][21] extension, which is part of the standard Markdown library, provides some options that are supported by Material for MkDocs to customize its appearance: @@ -242,7 +250,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][20]: + like for example those from [Python Markdown Extensions][22]: === "Unicode" @@ -283,25 +291,25 @@ customize its appearance: toc_depth: 0 ``` - Note that MkDocs will not generate [anchor links][21] for levels outside + Note that MkDocs will not generate [anchor links][23] for levels outside the range defined with `toc_depth`. However, Material for MkDocs also allows - to [hide the table of contents][22] on a specific page while keeping + to [hide the table of contents][24] 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._ - [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 + [19]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html + [20]: https://python-markdown.github.io/extensions/toc/ + [21]: https://python-markdown.github.io/extensions/toc/#usage + [22]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/ + [23]: #permalink + [24]: #hide-the-sidebars #### Navigation integration -[:octicons-file-code-24: Source][23] · +[:octicons-file-code-24: Source][25] · :octicons-unlock-24: Feature flag When _integration_ is enabled, the table of contents is rendered as part of @@ -316,14 +324,14 @@ theme: === "Integrate table of contents" - [![Integrate table of contents][24]][24] + [![Integrate table of contents][26]][26] === "Separate table of contents" [![Separate table of contents][8]][8] - [23]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_nav.scss - [24]: ../assets/screenshots/toc-integrate.png + [25]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_nav.scss + [26]: ../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 @@ -331,12 +339,12 @@ feature flags, e.g. [tabs][1] and [sections][2]. ### Hide the sidebars -[:octicons-file-code-24: Source][25] · +[:octicons-file-code-24: Source][27] · :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][26] extension: +any page using the [Metadata][28] extension: ``` yaml --- @@ -350,27 +358,27 @@ hide: === "Hide navigation" - [![Hide navigation][27]][27] + [![Hide navigation][29]][29] === "Hide table of contents" - [![Hide table of contents][28]][28] + [![Hide table of contents][30]][30] === "Hide both" - [![Hide navigation and table of contents][29]][29] + [![Hide navigation and table of contents][31]][31] - [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 + [27]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html + [28]: ../../reference/meta-tags/#metadata + [29]: ../assets/screenshots/hide-navigation.png + [30]: ../assets/screenshots/hide-toc.png + [31]: ../assets/screenshots/hide-navigation-toc.png ## Customization ### Keyboard shortcuts -[:octicons-file-code-24: Source][30] · +[:octicons-file-code-24: Source][32] · :octicons-mortar-board-24: Difficulty: _easy_ Material for MkDocs includes several keyboard shortcuts that make it possible @@ -396,7 +404,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][31], you can subscribe to the `keyboard$` observable and attach +JavaScript][33], you can subscribe to the `keyboard$` observable and attach your custom event listener: ``` js @@ -412,12 +420,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. - [30]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts - [31]: ../customization.md#additional-javascript + [32]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts + [33]: ../customization.md#additional-javascript ### Content area width -[:octicons-file-code-24: Source][32] · +[:octicons-file-code-24: Source][34] · :octicons-mortar-board-24: Difficulty: _easy_ The width of the content area is set so the length of each line doesn't exceed @@ -426,7 +434,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][33] and a few lines +This can easily be achieved with an [additional stylesheet][35] and a few lines of CSS: === "Increase width" @@ -445,5 +453,5 @@ of CSS: } ``` - [32]: https://github.com/squidfunk/mkdocs-material/blob/aeaa00a625abf952f355164de02c539b061e6127/src/assets/stylesheets/main/layout/_base.scss - [33]: ../customization.md#additional-css + [34]: https://github.com/squidfunk/mkdocs-material/blob/aeaa00a625abf952f355164de02c539b061e6127/src/assets/stylesheets/main/layout/_base.scss + [35]: ../customization.md#additional-css