diff --git a/docs/setup/setting-up-navigation.md b/docs/setup/setting-up-navigation.md index 375ceee48..930316ce2 100644 --- a/docs/setup/setting-up-navigation.md +++ b/docs/setup/setting-up-navigation.md @@ -4,14 +4,14 @@ template: overrides/main.html # Setting up navigation -A clear and concise navigation structure is an important aspect of good project +A clear and concise navigation structure is an important aspect of good project documentation. Material for MkDocs provides a multitude of options to configure the 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 +[1]: #navigation-tabs +[2]: #navigation-sections +[3]: #instant-loading ## Configuration @@ -24,22 +24,22 @@ When _instant loading_ is enabled, clicks on all internal links will be intercepted and dispatched via [XHR][5] without fully reloading the page. Add the following lines to `mkdocs.yml`: -``` yaml +```yaml theme: features: - navigation.instant ``` The resulting page is parsed and injected and all event handlers and components -are rebound automatically. This means that __Material for MkDocs behaves like a -Single Page Application__, which is especially useful for large documentation +are rebound automatically. This means that **Material for MkDocs behaves like a +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. _Material for MkDocs is the only MkDocs theme offering this feature._ - [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 +[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 ### Anchor tracking @@ -51,7 +51,7 @@ When _anchor tracking_ is enabled, the URL in the address bar is automatically updated with the active anchor as highlighted in the table of contents. Add the following lines to `mkdocs.yml`: -``` yaml +```yaml theme: features: - navigation.tracking @@ -65,7 +65,7 @@ When _tabs_ are enabled, top-level sections are rendered in a menu layer below the header for viewports above `1220px`, but remain as-is on mobile.[^1] Add the following lines to `mkdocs.yml`: - [^1]: +[^1]: Prior to version 6.2, navigation tabs had a slightly different behavior. All top-level pages (i.e. all top-level entries that directly refer to an `*.md` file) defined inside the `nav` entry of `mkdocs.yml` were grouped @@ -74,7 +74,7 @@ the following lines to `mkdocs.yml`: as was reported in #1884 and #2072. From version 6.2 on, navigation tabs include all top-level pages and sections. -``` yaml +```yaml theme: features: - navigation.tabs @@ -88,9 +88,9 @@ theme: [![Without tabs][8]][8] - [6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/tabs.html - [7]: ../assets/screenshots/navigation-tabs.png - [8]: ../assets/screenshots/navigation.png +[6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/tabs.html +[7]: ../assets/screenshots/navigation-tabs.png +[8]: ../assets/screenshots/navigation.png #### Sticky navigation tabs @@ -103,7 +103,7 @@ When _sticky tabs_ are enabled, navigation tabs will lock below the header and always remain visible when scrolling down. Just add the following two feature flags to `mkdocs.yml`: -``` yaml +```yaml theme: features: - navigation.tabs @@ -118,9 +118,9 @@ theme: [![Without sticky tabs][11]][11] - [9]: ../insiders.md - [10]: ../assets/screenshots/navigation-tabs-sticky.png - [11]: ../assets/screenshots/navigation-tabs-collapsed.png +[9]: ../insiders.md +[10]: ../assets/screenshots/navigation-tabs-sticky.png +[11]: ../assets/screenshots/navigation-tabs-collapsed.png ### Navigation sections @@ -131,7 +131,7 @@ When _sections_ are enabled, top-level sections are rendered as groups in the sidebar for viewports above `1220px`, but remain as-is on mobile. Add the following lines to `mkdocs.yml`: -``` yaml +```yaml theme: features: - navigation.sections @@ -145,8 +145,8 @@ theme: [![Without sections][8]][8] - [12]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/nav-item.html - [13]: ../assets/screenshots/navigation-sections.png +[12]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/nav-item.html +[13]: ../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 level 2 navigation @@ -161,7 +161,7 @@ When _expansion_ is enabled, the left sidebar will expand all collapsible subsections by default, so the user doesn't have to open subsections manually. Add the following lines to `mkdocs.yml`: -``` yaml +```yaml theme: features: - navigation.expand @@ -175,7 +175,7 @@ theme: [![Without expansion][8]][8] - [14]: ../assets/screenshots/navigation-expand.png +[14]: ../assets/screenshots/navigation-expand.png ### Section index pages @@ -188,7 +188,7 @@ When _section index pages_ are enabled, documents can be directly attached to sections, which is particularly useful for providing overview pages. Add the following lines to `mkdocs.yml`: -``` yaml +```yaml theme: features: - navigation.indexes @@ -206,7 +206,7 @@ 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 +```yaml nav: - Section: - section/index.md @@ -219,16 +219,16 @@ _This feature flag can be combined with all other feature flags, e.g. [tabs][1] and [sections][2], except for table of contents [navigation integration][17]. Note that it doesn't rely on third-party plugins[^2]._ - [^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 navigation-related features offered by Material for MkDocs. - [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 +[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 ### Back-to-top button @@ -240,7 +240,7 @@ A _back-to-top button_ can be shown when the user, after scrolling down, starts to scroll up again. It's rendered in the lower right corner of the viewport. Add the following lines to `mkdocs.yml`: -``` yaml +```yaml theme: features: - navigation.top @@ -258,8 +258,8 @@ A demo is worth a thousand words — check it out at - [19]: ../assets/screenshots/back-to-top.png - [20]: https://squidfunk.github.io/mkdocs-material-insiders/setup/setting-up-navigation/#back-to-top-button +[19]: ../assets/screenshots/back-to-top.png +[20]: https://squidfunk.github.io/mkdocs-material-insiders/setup/setting-up-navigation/#back-to-top-button ### Table of contents @@ -271,10 +271,10 @@ customize its appearance: `permalink`{ #permalink } -: :octicons-milestone-24: Default: `false` – This option adds an anchor link - containing the paragraph symbol `¶` or another custom symbol at the end of - each headline, exactly like on the page you're currently viewing, which - Material for MkDocs will make appear on hover: +: :octicons-milestone-24: Default: `false` – This option adds an anchor link +containing the paragraph symbol `¶` or another custom symbol at the end of +each headline, exactly like on the page you're currently viewing, which +Material for MkDocs will make appear on hover: === "¶" @@ -294,10 +294,10 @@ customize its appearance: `slugify`{ #slugify } -: :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][24]: +: :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][24]: === "Unicode" @@ -317,10 +317,10 @@ customize its appearance: `toc_depth`{ #toc_depth } -: :octicons-milestone-24: Default: `6` – Define the range of levels to be - included in the table of contents. This may be useful for project - documentation with deeply structured headings to decrease the length of the - table of contents, or to remove the table of contents altogether: +: :octicons-milestone-24: Default: `6` – Define the range of levels to be +included in the table of contents. This may be useful for project +documentation with deeply structured headings to decrease the length of the +table of contents, or to remove the table of contents altogether: === "Hide levels 4-6" @@ -342,10 +342,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._ - [21]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html - [22]: https://python-markdown.github.io/extensions/toc/ - [23]: https://python-markdown.github.io/extensions/toc/#usage - [24]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/ +[21]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html +[22]: https://python-markdown.github.io/extensions/toc/ +[23]: https://python-markdown.github.io/extensions/toc/#usage +[24]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/ #### Navigation integration @@ -356,7 +356,7 @@ When _integration_ is enabled, the table of contents is rendered as part of the navigation for viewports above `1220px`, but remains as-is on mobile. Add the following lines to `mkdocs.yml`: -``` yaml +```yaml theme: features: - toc.integrate @@ -370,12 +370,12 @@ theme: [![Separate table of contents][8]][8] - [25]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_nav.scss - [26]: ../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 -feature flags, e.g. [tabs][1] and [sections][2]. +feature flags, e.g. [tabs][1] and [sections][2]. ### Hide the sidebars @@ -386,33 +386,32 @@ 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][28] extension: -``` yaml +```yaml --- hide: - navigation # Hide navigation - - toc # Hide table of contents + - toc # Hide table of contents --- -... ``` === "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] - [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 +[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 @@ -426,8 +425,8 @@ to navigate your project documentation via keyboard. There're two modes: `search`{ #search } -: This mode is active when the _search is focused_. It provides several key - bindings to make search accessible and navigable via keyboard: +: This mode is active when the _search is focused_. It provides several key +bindings to make search accessible and navigable via keyboard: * ++arrow-down++ , ++arrow-up++ : select next / previous result * ++esc++ , ++tab++ : close search dialog @@ -435,9 +434,9 @@ to navigate your project documentation via keyboard. There're two modes: `global`{ #global } -: This mode is active when _search is not focussed_ and when there's no other - focussed element that is susceptible to keyboard input. The following keys - are bound: +: This mode is active when _search is not focussed_ and when there's no other +focussed element that is susceptible to keyboard input. The following keys +are bound: * ++f++ , ++s++ , ++slash++ : open search dialog * ++p++ , ++comma++ : go to previous page @@ -447,21 +446,21 @@ Let's say you want to bind some action to the ++x++ key. By using [additional JavaScript][33], you can subscribe to the `keyboard$` observable and attach your custom event listener: -``` js -keyboard$.subscribe(function(key) { +```js +keyboard$.subscribe(function (key) { if (key.mode === "global" && key.type === "x") { /* Add custom keyboard handler here */ - key.claim() + key.claim(); } -}) +}); ``` 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. - [32]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts - [33]: ../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 @@ -493,5 +492,5 @@ of CSS: } ``` - [34]: https://github.com/squidfunk/mkdocs-material/blob/aeaa00a625abf952f355164de02c539b061e6127/src/assets/stylesheets/main/layout/_base.scss - [35]: ../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