2020-07-17 14:08:27 +03:00
|
|
|
|
---
|
|
|
|
|
template: overrides/main.html
|
|
|
|
|
---
|
|
|
|
|
|
2020-07-20 16:18:09 +03:00
|
|
|
|
# Setting up navigation
|
2020-07-17 14:08:27 +03:00
|
|
|
|
|
|
|
|
|
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_.
|
|
|
|
|
|
|
|
|
|
## Configuration
|
|
|
|
|
|
|
|
|
|
### Instant loading
|
|
|
|
|
|
2020-07-19 23:23:26 +03:00
|
|
|
|
[:octicons-file-code-24: Source][1] ·
|
|
|
|
|
:octicons-unlock-24: Feature flag ·
|
|
|
|
|
:octicons-beaker-24: Experimental
|
2020-07-17 14:08:27 +03:00
|
|
|
|
|
|
|
|
|
When _instant loading_ is activated, clicks on all internal links will be
|
|
|
|
|
intercepted and dispatched via [XHR][2] without fully reloading the page. It
|
2020-07-23 14:17:50 +03:00
|
|
|
|
can be enabled via `mkdocs.yml` with:
|
2020-07-17 14:08:27 +03:00
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
theme:
|
|
|
|
|
features:
|
|
|
|
|
- instant
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The resulting page is parsed and injected and all event handlers and components
|
2020-07-26 15:46:09 +03:00
|
|
|
|
are rebound automatically. This means that __Material for MkDocs behaves like a
|
2020-07-17 14:08:27 +03:00
|
|
|
|
Single Page Application__, which is especially useful for large documentation
|
2020-07-26 15:46:09 +03:00
|
|
|
|
sites that come with a massive search index, as the search index will now
|
|
|
|
|
remain intact in-between document switches.
|
2020-07-17 14:08:27 +03:00
|
|
|
|
|
|
|
|
|
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/instant/index.ts
|
|
|
|
|
[2]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
|
|
|
|
|
|
2020-08-11 20:14:42 +03:00
|
|
|
|
### Navigation expansion
|
|
|
|
|
|
|
|
|
|
[: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
|
|
|
|
|
|
2020-07-20 20:28:13 +03:00
|
|
|
|
### Navigation tabs
|
2020-07-17 14:08:27 +03:00
|
|
|
|
|
2020-08-11 20:14:42 +03:00
|
|
|
|
[:octicons-file-code-24: Source][4] · :octicons-unlock-24: Feature flag
|
2020-07-17 14:08:27 +03:00
|
|
|
|
|
|
|
|
|
When _tabs_ are activated, top-level sections are rendered in a menu layer
|
|
|
|
|
below the header on big screens (but not when the sidebar is hidden). It can be
|
2020-07-23 14:17:50 +03:00
|
|
|
|
enabled via `mkdocs.yml` with:
|
2020-07-17 14:08:27 +03:00
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
theme:
|
|
|
|
|
features:
|
|
|
|
|
- tabs
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Note that all __top-level pages__ (i.e. all top-level entries that directly
|
2020-08-11 20:14:42 +03:00
|
|
|
|
refer to an `*.md` file) defined inside the [`nav`][5] entry of `mkdocs.yml`
|
2020-07-21 14:33:44 +03:00
|
|
|
|
will be grouped under the first tab which will receive the title of the first
|
|
|
|
|
page.
|
2020-07-17 14:08:27 +03:00
|
|
|
|
|
|
|
|
|
This means that there will effectively be no collapsible subsections for the
|
|
|
|
|
first tab, because each subsection is rendered as another tab. If you want more
|
|
|
|
|
fine-grained control, _i.e. collapsible subsections for the first tab_, you can
|
|
|
|
|
use __top-level sections__, so that the top-level is entirely made up of
|
|
|
|
|
sections. This is illustrated in the following example:
|
|
|
|
|
|
|
|
|
|
=== "Top-level pages"
|
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
nav:
|
2020-07-19 23:23:26 +03:00
|
|
|
|
- Tab 1 + Page 1.1
|
|
|
|
|
- Page 1.2
|
2020-07-17 14:08:27 +03:00
|
|
|
|
- Tab 2:
|
|
|
|
|
- Page 2.1
|
|
|
|
|
- Page 2.2
|
2020-07-19 23:23:26 +03:00
|
|
|
|
- Page 2.3
|
|
|
|
|
- Page 1.3
|
2020-07-17 14:08:27 +03:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
=== "Top-level sections"
|
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
nav:
|
|
|
|
|
- Tab 1:
|
|
|
|
|
- Page 1.1
|
|
|
|
|
- Page 1.2
|
2020-07-19 23:23:26 +03:00
|
|
|
|
- Page 1.3
|
2020-07-17 14:08:27 +03:00
|
|
|
|
- Tab 2:
|
|
|
|
|
- Page 2.1
|
|
|
|
|
- Page 2.2
|
2020-07-19 23:23:26 +03:00
|
|
|
|
- Page 2.3
|
2020-07-17 14:08:27 +03:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Note that tabs are only shown for larger screens, so make sure that navigation
|
2020-08-11 20:14:42 +03:00
|
|
|
|
is plausible on mobile devices. As another example, see the [`mkdocs.yml`][6]
|
2020-07-17 14:08:27 +03:00
|
|
|
|
used to render these pages.
|
|
|
|
|
|
2020-08-11 20:14:42 +03:00
|
|
|
|
[4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/tabs.html
|
|
|
|
|
[5]: https://www.mkdocs.org/user-guide/configuration/#nav
|
|
|
|
|
[6]: https://github.com/squidfunk/mkdocs-material/blob/master/mkdocs.yml
|
2020-07-17 14:08:27 +03:00
|
|
|
|
|
|
|
|
|
### Table of contents
|
|
|
|
|
|
2020-08-11 20:14:42 +03:00
|
|
|
|
[:octicons-file-code-24: Source][7] · [:octicons-workflow-24: Extension][8]
|
2020-07-17 14:08:27 +03:00
|
|
|
|
|
2020-08-11 20:14:42 +03:00
|
|
|
|
The [Table of contents][9] extension, which is part of the standard Markdown
|
2020-07-17 14:08:27 +03:00
|
|
|
|
library, provides some options that are supported by Material for MkDocs to
|
2020-07-17 15:33:52 +03:00
|
|
|
|
customize its appearance:
|
2020-07-17 14:08:27 +03:00
|
|
|
|
|
2020-07-22 15:05:07 +03:00
|
|
|
|
`permalink`{: #permalink }
|
2020-07-17 14:08:27 +03:00
|
|
|
|
|
2020-07-20 16:18:09 +03:00
|
|
|
|
: :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:
|
2020-07-17 14:08:27 +03:00
|
|
|
|
|
|
|
|
|
=== "¶"
|
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
markdown_extensions:
|
|
|
|
|
- toc:
|
|
|
|
|
permalink: true
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
=== "⚓︎"
|
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
markdown_extensions:
|
|
|
|
|
- toc:
|
|
|
|
|
permalink: ⚓︎
|
|
|
|
|
```
|
|
|
|
|
|
2020-07-22 15:05:07 +03:00
|
|
|
|
`slugify`{: #slugify }
|
2020-07-17 14:08:27 +03:00
|
|
|
|
|
2020-07-20 16:18:09 +03:00
|
|
|
|
: :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
|
2020-08-11 20:14:42 +03:00
|
|
|
|
like for example those from [Python Markdown Extensions][10]:
|
2020-07-17 14:08:27 +03:00
|
|
|
|
|
|
|
|
|
=== "Unicode"
|
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
markdown_extensions:
|
|
|
|
|
- toc:
|
2020-09-06 12:49:05 +03:00
|
|
|
|
slugify: !!python/name:pymdownx.slugs.uslugify
|
2020-07-17 14:08:27 +03:00
|
|
|
|
```
|
|
|
|
|
|
2020-07-17 15:33:52 +03:00
|
|
|
|
=== "Unicode, case-sensitive"
|
2020-07-17 14:08:27 +03:00
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
markdown_extensions:
|
|
|
|
|
- toc:
|
2020-09-06 12:49:05 +03:00
|
|
|
|
slugify: !!python/name:pymdownx.slugs.uslugify_cased
|
2020-07-17 14:08:27 +03:00
|
|
|
|
```
|
|
|
|
|
|
2020-07-22 15:05:07 +03:00
|
|
|
|
`toc_depth`{: #toc_depth }
|
2020-07-17 14:08:27 +03:00
|
|
|
|
|
2020-07-20 16:18:09 +03:00
|
|
|
|
: :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:
|
2020-07-17 14:08:27 +03:00
|
|
|
|
|
|
|
|
|
=== "Hide levels 4-6"
|
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
markdown_extensions:
|
|
|
|
|
- toc:
|
|
|
|
|
toc_depth: 3
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
=== "Hide table of contents"
|
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
markdown_extensions:
|
|
|
|
|
- toc:
|
|
|
|
|
toc_depth: 0
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
_Material for MkDocs doesn't provide official support for the other options of
|
2020-07-19 23:23:26 +03:00
|
|
|
|
this extension, so they may be supported but can also yield weird results. Use
|
|
|
|
|
them at your own risk._
|
2020-07-17 14:08:27 +03:00
|
|
|
|
|
2020-08-11 20:14:42 +03:00
|
|
|
|
[7]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
|
|
|
|
|
[8]: https://python-markdown.github.io/extensions/toc/
|
|
|
|
|
[9]: https://python-markdown.github.io/extensions/toc/#usage
|
|
|
|
|
[10]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
|
2020-07-23 14:17:50 +03:00
|
|
|
|
|
|
|
|
|
## Customization
|
|
|
|
|
|
|
|
|
|
### Keyboard shortcuts
|
|
|
|
|
|
2020-08-11 20:14:42 +03:00
|
|
|
|
[:octicons-file-code-24: Source][11] ·
|
2020-07-23 14:17:50 +03:00
|
|
|
|
:octicons-mortar-board-24: Difficulty: _easy_
|
|
|
|
|
|
|
|
|
|
Material for MkDocs includes several keyboard shortcuts that make it possible
|
|
|
|
|
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:
|
|
|
|
|
|
2020-07-27 13:05:07 +03:00
|
|
|
|
* ++arrow-down++ , ++arrow-up++ : select next / previous result
|
|
|
|
|
* ++esc++ , ++tab++ : close search dialog
|
|
|
|
|
* ++enter++ : follow selected result
|
2020-07-23 14:17:50 +03:00
|
|
|
|
|
|
|
|
|
`global`{: #global }
|
|
|
|
|
|
2020-07-26 15:46:09 +03:00
|
|
|
|
: 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:
|
2020-07-23 14:17:50 +03:00
|
|
|
|
|
2020-07-27 13:05:07 +03:00
|
|
|
|
* ++f++ , ++s++ , ++slash++ : open search dialog
|
|
|
|
|
* ++p++ , ++comma++ : go to previous page
|
|
|
|
|
* ++n++ , ++period++ : go to next page
|
2020-07-23 14:17:50 +03:00
|
|
|
|
|
|
|
|
|
Let's say you want to bind some action to the ++x++ key. By using [additional
|
2020-08-11 20:14:42 +03:00
|
|
|
|
JavaScript][12], you can subscribe to the `keyboard$` observable and attach
|
2020-07-23 14:17:50 +03:00
|
|
|
|
your custom event listener:
|
|
|
|
|
|
|
|
|
|
``` js
|
2020-09-19 17:19:18 +03:00
|
|
|
|
app.keyboard$.subscribe(function(key) {
|
2020-07-23 14:17:50 +03:00
|
|
|
|
if (key.mode === "global" && key.type === "x") {
|
|
|
|
|
/* Add custom keyboard handler here */
|
|
|
|
|
key.claim()
|
|
|
|
|
}
|
|
|
|
|
})
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The call to `#!js key.claim()` will essentially execute `#!js preventDefault()`
|
2020-07-26 15:46:09 +03:00
|
|
|
|
on the underlying event, so the keypress will not propagate further and touch
|
2020-07-23 14:17:50 +03:00
|
|
|
|
other event listeners.
|
|
|
|
|
|
2020-08-11 20:14:42 +03:00
|
|
|
|
[11]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts
|
|
|
|
|
[12]: ../customization.md#additional-javascript
|