mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-06-14 11:52:32 +03:00
450 lines
13 KiB
Markdown
450 lines
13 KiB
Markdown
---
|
|
template: overrides/main.html
|
|
---
|
|
|
|
# Setting up navigation
|
|
|
|
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][navigation.tabs] and
|
|
[sections][navigation.sections], and its flag-ship feature: [instant loading]
|
|
[navigation.instant].
|
|
|
|
[navigation.tabs]: #navigation-tabs
|
|
[navigation.sections]: #navigation-sections
|
|
[navigation.instant]: #instant-loading
|
|
|
|
## Configuration
|
|
|
|
### Instant loading
|
|
|
|
[:octicons-tag-24: 5.0.0][navigation.instant support] ·
|
|
:octicons-unlock-24: Feature flag
|
|
|
|
When instant loading is enabled, clicks on all internal links will be
|
|
intercepted and dispatched via [XHR] without fully reloading the page. Add
|
|
the following lines to `mkdocs.yml`:
|
|
|
|
``` yaml
|
|
theme:
|
|
features:
|
|
- navigation.instant
|
|
```
|
|
|
|
The resulting page is parsed and injected and all event handlers and components
|
|
are rebound automatically, i.e., __Material for MkDocs now behaves like a Single
|
|
Page Application__. Now, the search index survives navigation, which is
|
|
especially useful for large documentation sites.
|
|
|
|
[navigation.instant support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.0
|
|
[XHR]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
|
|
|
|
### Anchor tracking
|
|
|
|
[:octicons-tag-24: 8.0.0][Anchor tracking support] ·
|
|
:octicons-unlock-24: Feature flag ·
|
|
:octicons-beaker-24: Experimental
|
|
|
|
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
|
|
theme:
|
|
features:
|
|
- navigation.tracking
|
|
```
|
|
|
|
[Anchor tracking support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.0.0
|
|
|
|
### Navigation tabs
|
|
|
|
[:octicons-tag-24: 1.1.0][navigation.tabs support] ·
|
|
:octicons-unlock-24: Feature flag
|
|
|
|
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]:
|
|
Prior to :octicons-tag-24: 6.2.0, navigation tabs had a slightly different
|
|
behavior. All top-level pages (i.e. all top-level entries directly
|
|
refefring to a `*.md` file) defined inside the `nav` entry of `mkdocs.yml`
|
|
were grouped under the first tab which received the title of the first page.
|
|
This made it impossible to include a top-level page (or external link) as a
|
|
tab item, as was reported in #1884 and #2072. From :octicons-tag-24: 6.2.0
|
|
on, navigation tabs include all top-level pages and sections.
|
|
|
|
``` yaml
|
|
theme:
|
|
features:
|
|
- navigation.tabs
|
|
```
|
|
|
|
=== ":octicons-check-circle-fill-16: Enabled"
|
|
|
|
[![navigation.tabs enabled]][navigation.tabs enabled]
|
|
|
|
=== ":octicons-skip-16: Disabled"
|
|
|
|
[![navigation.tabs disabled]][navigation.tabs disabled]
|
|
|
|
[navigation.tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0
|
|
[navigation.tabs enabled]: ../assets/screenshots/navigation-tabs.png
|
|
[navigation.tabs disabled]: ../assets/screenshots/navigation.png
|
|
|
|
#### Sticky navigation tabs
|
|
|
|
[:octicons-tag-24: 7.3.0][navigation.tabs.sticky support] ·
|
|
:octicons-unlock-24: Feature flag
|
|
|
|
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
|
|
theme:
|
|
features:
|
|
- navigation.tabs
|
|
- navigation.tabs.sticky
|
|
```
|
|
|
|
=== ":octicons-check-circle-fill-16: Enabled"
|
|
|
|
[![navigation.tabs.sticky enabled]][navigation.tabs.sticky enabled]
|
|
|
|
=== ":octicons-skip-16: Disabled"
|
|
|
|
[![navigation.tabs.sticky disabled]][navigation.tabs.sticky disabled]
|
|
|
|
[navigation.tabs.sticky support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
|
|
[navigation.tabs.sticky enabled]: ../assets/screenshots/navigation-tabs-sticky.png
|
|
[navigation.tabs.sticky disabled]: ../assets/screenshots/navigation-tabs-collapsed.png
|
|
|
|
### Navigation sections
|
|
|
|
[:octicons-tag-24: 6.2.0][navigation.sections support] ·
|
|
:octicons-unlock-24: Feature flag
|
|
|
|
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
|
|
theme:
|
|
features:
|
|
- navigation.sections
|
|
```
|
|
|
|
=== ":octicons-check-circle-fill-16: Enabled"
|
|
|
|
[![navigation.sections enabled]][navigation.sections enabled]
|
|
|
|
=== ":octicons-skip-16: Disabled"
|
|
|
|
[![navigation.sections disabled]][navigation.sections disabled]
|
|
|
|
[navigation.sections support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
|
|
[navigation.sections enabled]: ../assets/screenshots/navigation-sections.png
|
|
[navigation.sections disabled]: ../assets/screenshots/navigation.png
|
|
|
|
Both feature flags, [`navigation.tabs`][navigation.tabs] and
|
|
[`navigation.sections`][navigation.sections], can be combined with each other.
|
|
If both feature flags are enabled, sections are rendered for level 2 navigation
|
|
items.
|
|
|
|
### Navigation expansion
|
|
|
|
[:octicons-tag-24: 6.2.0][navigation.expand support] ·
|
|
:octicons-unlock-24: Feature flag
|
|
|
|
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
|
|
theme:
|
|
features:
|
|
- navigation.expand
|
|
```
|
|
|
|
=== ":octicons-check-circle-fill-16: Enabled"
|
|
|
|
[![navigation.expand enabled]][navigation.expand enabled]
|
|
|
|
=== ":octicons-skip-16: Disabled"
|
|
|
|
[![navigation.expand disabled]][navigation.expand disabled]
|
|
|
|
[navigation.expand support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
|
|
[navigation.expand enabled]: ../assets/screenshots/navigation-expand.png
|
|
[navigation.expand disabled]: ../assets/screenshots/navigation.png
|
|
|
|
### Navigation pruning :material-alert-decagram:{ title="Added on May 25, 2022" }
|
|
|
|
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
|
|
[:octicons-tag-24: insiders-4.16.0][Insiders] ·
|
|
:octicons-beaker-24: Experimental
|
|
|
|
When pruning is enabled, only the visible navigation items are included in the
|
|
rendered HTML, __reducing the size of the built site by 33% or more__. Add the
|
|
following lines to `mkdocs.yml`:
|
|
|
|
``` yaml
|
|
theme:
|
|
features:
|
|
- navigation.prune # (1)!
|
|
```
|
|
|
|
1. This feature flag is not compatible with
|
|
[`navigation.expand`][navigation.expand], as navigation expansion requires
|
|
the complete navigation structure.
|
|
|
|
This feature flag is especially useful for documentation sites with 100+ or even
|
|
1,000+ of pages, as the navigation makes up a significant fraction of the HTML.
|
|
Navigation pruning will replace all expandable sections with links to the first
|
|
page in that section (or the section index page).
|
|
|
|
[navigation.expand]: #navigation-expansion
|
|
|
|
### Section index pages
|
|
|
|
[:octicons-tag-24: 7.3.0][navigation.indexes support] ·
|
|
:octicons-unlock-24: Feature flag
|
|
|
|
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
|
|
theme:
|
|
features:
|
|
- navigation.indexes # (1)!
|
|
```
|
|
|
|
1. This feature flag is not compatible with [`toc.integrate`][toc.integrate],
|
|
as sections cannot host the table of contents due to missing space.
|
|
|
|
=== ":octicons-check-circle-fill-16: Enabled"
|
|
|
|
[![navigation.indexes enabled]][navigation.indexes enabled]
|
|
|
|
=== ":octicons-skip-16: Disabled"
|
|
|
|
[![navigation.indexes disabled]][navigation.indexes disabled]
|
|
|
|
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:
|
|
- Section:
|
|
- section/index.md
|
|
- Page 1: section/page-1.md
|
|
...
|
|
- Page n: section/page-n.md
|
|
```
|
|
|
|
[navigation.indexes support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
|
|
[navigation.indexes enabled]: ../assets/screenshots/navigation-index-on.png
|
|
[navigation.indexes disabled]: ../assets/screenshots/navigation-index-off.png
|
|
[toc.integrate]: #navigation-integration
|
|
|
|
### Table of contents
|
|
|
|
#### Anchor following
|
|
|
|
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
|
|
[:octicons-tag-24: insiders-4.8.0][Insiders] ·
|
|
:octicons-beaker-24: Experimental
|
|
|
|
When anchor following for the [table of contents] is enabled, the sidebar is
|
|
automatically scrolled so that the active anchor is always visible. Add the
|
|
following lines to `mkdocs.yml`:
|
|
|
|
``` yaml
|
|
theme:
|
|
features:
|
|
- toc.follow
|
|
```
|
|
|
|
[Insiders]: ../insiders/index.md
|
|
|
|
#### Navigation integration
|
|
|
|
[:octicons-tag-24: 6.2.0][toc.integrate support] ·
|
|
:octicons-unlock-24: Feature flag
|
|
|
|
When navigation integration for the [table of contents] is enabled, it is always
|
|
rendered as part of the navigation sidebar on the left. Add the following lines
|
|
to `mkdocs.yml`:
|
|
|
|
``` yaml
|
|
theme:
|
|
features:
|
|
- toc.integrate # (1)!
|
|
```
|
|
|
|
1. This feature flag is not compatible with
|
|
[`navigation.indexes`][navigation.indexes], as sections cannot host the
|
|
table of contents due to missing space.
|
|
|
|
=== ":octicons-check-circle-fill-16: Enabled"
|
|
|
|
[![toc.integrate enabled]][toc.integrate enabled]
|
|
|
|
=== ":octicons-skip-16: Disabled"
|
|
|
|
[![toc.integrate disabled]][toc.integrate disabled]
|
|
|
|
[table of contents]: extensions/python-markdown.md#table-of-contents
|
|
[toc.integrate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
|
|
[toc.integrate enabled]: ../assets/screenshots/toc-integrate.png
|
|
[toc.integrate disabled]: ../assets/screenshots/navigation-tabs.png
|
|
[navigation.indexes]: #section-index-pages
|
|
|
|
### Back-to-top button
|
|
|
|
[:octicons-tag-24: 7.1.0][navigation.top support] ·
|
|
:octicons-unlock-24: Feature flag
|
|
|
|
A back-to-top button can be shown when the user, after scrolling down, starts
|
|
to scroll up again. It's rendered centered and just below the header. Add the
|
|
following lines to `mkdocs.yml`:
|
|
|
|
``` yaml
|
|
theme:
|
|
features:
|
|
- navigation.top
|
|
```
|
|
|
|
[navigation.top support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
|
|
|
|
## Usage
|
|
|
|
### Hiding the sidebars
|
|
|
|
When [Metadata] is enabled, the navigation and/or table of contents sidebars
|
|
can be hidden for a document with custom front matter. Add the following lines
|
|
at the top of a Markdown file:
|
|
|
|
``` sh
|
|
---
|
|
hide:
|
|
- navigation
|
|
- toc
|
|
---
|
|
|
|
# Document title
|
|
...
|
|
```
|
|
|
|
=== "Hide navigation"
|
|
|
|
[![hide.navigation enabled]][hide.navigation enabled]
|
|
|
|
=== "Hide table of contents"
|
|
|
|
[![hide.toc enabled]][hide.toc enabled]
|
|
|
|
=== "Hide both"
|
|
|
|
[![hide.* enabled]][hide.* enabled]
|
|
|
|
[Metadata]: extensions/python-markdown.md#metadata
|
|
[hide.navigation enabled]: ../assets/screenshots/hide-navigation.png
|
|
[hide.toc enabled]: ../assets/screenshots/hide-toc.png
|
|
[hide.* enabled]: ../assets/screenshots/hide-navigation-toc.png
|
|
|
|
## Customization
|
|
|
|
### Keyboard shortcuts
|
|
|
|
Material for MkDocs includes several keyboard shortcuts that make it possible
|
|
to navigate your project documentation via keyboard. There're two modes:
|
|
|
|
`search`{ #mode-search }
|
|
|
|
: 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
|
|
* ++enter++ : follow selected result
|
|
|
|
`global`{ #mode-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:
|
|
|
|
* ++f++ , ++s++ , ++slash++ : open search dialog
|
|
* ++p++ , ++comma++ : go to previous page
|
|
* ++n++ , ++period++ : go to next page
|
|
|
|
Let's say you want to bind some action to the ++x++ key. By using [additional
|
|
JavaScript], you can subscribe to the `keyboard$` observable and attach
|
|
your custom event listener:
|
|
|
|
=== ":octicons-file-code-16: docs/javascripts/shortcuts.js"
|
|
|
|
``` js
|
|
keyboard$.subscribe(function(key) {
|
|
if (key.mode === "global" && key.type === "x") {
|
|
/* Add custom keyboard handler here */
|
|
key.claim() // (1)!
|
|
}
|
|
})
|
|
```
|
|
|
|
1. The call to `key.claim()` will execute `preventDefault()` on the
|
|
underlying event, so the keypress will not propagate further and
|
|
touch other event listeners.
|
|
|
|
=== ":octicons-file-code-16: mkdocs.yml"
|
|
|
|
``` yaml
|
|
extra_javascript:
|
|
- javascripts/shortcuts.js
|
|
```
|
|
|
|
[additional JavaScript]: ../customization.md#additional-javascript
|
|
|
|
### Content area width
|
|
|
|
The width of the content area is set so the length of each line doesn't exceed
|
|
80-100 characters, depending on the width of the characters. While this
|
|
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 style sheet] and a few lines
|
|
of CSS:
|
|
|
|
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
|
|
|
|
``` css
|
|
.md-grid {
|
|
max-width: 1440px; /* (1)! */
|
|
}
|
|
```
|
|
|
|
1. If you want the content area to always stretch to the available screen
|
|
space, reset `max-width` with the following CSS:
|
|
|
|
``` css
|
|
.md-grid {
|
|
max-width: initial;
|
|
}
|
|
```
|
|
|
|
=== ":octicons-file-code-16: mkdocs.yml"
|
|
|
|
``` yaml
|
|
extra_css:
|
|
- stylesheets/extra.css
|
|
```
|
|
|
|
[additional style sheet]: ../customization.md#additional-css
|