mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-12-29 15:53:10 +01:00
9d901a3caf
in response to https://github.com/squidfunk/mkdocs-material/discussions/6995#discussioncomment-8960916
649 lines
18 KiB
Markdown
649 lines
18 KiB
Markdown
# 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] and [sections], and one
|
|
of its flagship features: [instant loading].
|
|
|
|
[tabs]: #navigation-tabs
|
|
[sections]: #navigation-sections
|
|
[instant loading]: #instant-loading
|
|
|
|
Additional navigation can be configured [in the footer] as well as with the
|
|
[tags plugin]. The [blog plugin] also sets up additional navigation.
|
|
|
|
[in the footer]: setting-up-the-footer.md#navigation
|
|
[tags plugin]: ../plugins/tags.md
|
|
[blog plugin]: ../plugins/blog.md
|
|
|
|
## Configuration
|
|
|
|
### Instant loading
|
|
|
|
<!-- md:version 5.0.0 -->
|
|
<!-- md:feature -->
|
|
|
|
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.
|
|
|
|
!!! info "The [`site_url`][mkdocs.site_url] setting must be set"
|
|
|
|
Note that you must set [`site_url`][mkdocs.site_url] when using instant
|
|
navigation, as instant navigation relies on the generated `sitemap.xml`
|
|
which will be empty if this setting is omitted. Example:
|
|
|
|
``` yaml
|
|
site_url: https://example.com
|
|
```
|
|
|
|
[XHR]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
|
|
|
|
#### Instant prefetching
|
|
|
|
<!-- md:sponsors -->
|
|
<!-- md:version insiders-4.36.0 -->
|
|
<!-- md:feature -->
|
|
<!-- md:flag experimental -->
|
|
|
|
Instant prefetching is a new experimental feature that will start to fetch a
|
|
page once the user hovers over a link. This will reduce the perceived loading
|
|
time for the user, especially on slow connections, as the page will be available
|
|
immediately upon navigation. Enable it with:
|
|
|
|
``` yaml
|
|
theme:
|
|
features:
|
|
- navigation.instant
|
|
- navigation.instant.prefetch
|
|
```
|
|
|
|
#### Progress indicator
|
|
|
|
<!-- md:version 9.4.3 -->
|
|
<!-- md:feature -->
|
|
<!-- md:flag experimental -->
|
|
|
|
In order to provide a better user experience on slow connections when using
|
|
instant navigation, a progress indicator can be enabled. It will be shown at
|
|
the top of the page and will be hidden once the page has fully loaded. You can
|
|
enable it in `mkdocs.yml` with:
|
|
|
|
``` yaml
|
|
theme:
|
|
features:
|
|
- navigation.instant
|
|
- navigation.instant.progress
|
|
```
|
|
|
|
The progress indicator will only show if the page hasn't finished loading after
|
|
400ms, so that fast connections will never show it for a better instant
|
|
experience.
|
|
|
|
### Instant previews :material-alert-decagram:{ .mdx-pulse title="Added on January 28, 2024" }
|
|
|
|
<!-- md:sponsors -->
|
|
<!-- md:version insiders-4.52.0 -->
|
|
<!-- md:feature -->
|
|
<!-- md:flag experimental -->
|
|
|
|
Instant previews are a brand new feature that allow the user to preview another
|
|
site of your documentation without navigating to it. They can be very helpful to
|
|
keep the user in context. Instant previews can be enabled on any header link
|
|
with the `data-preview` attribute:
|
|
|
|
```` markdown title="Link with instant preview"
|
|
``` markdown
|
|
[Attribute Lists](#){ data-preview }
|
|
```
|
|
````
|
|
|
|
<div class="result" markdown>
|
|
|
|
[Attribute Lists](extensions/python-markdown.md#attribute-lists){ data-preview }
|
|
|
|
</div>
|
|
|
|
!!! info "Limitations"
|
|
|
|
Instant previews are still an experimental feature and currently limited to
|
|
headerlinks. This means, you can use them on any internal link that points
|
|
to a header on another page, but not other elements with `id` attributes.
|
|
After we have gathered enough feedback, we will consider extending this
|
|
feature to other, and possibly arbitrary elements.
|
|
|
|
#### Automatic previews
|
|
|
|
<!-- md:sponsors -->
|
|
<!-- md:version insiders-4.53.0 -->
|
|
<!-- md:extension -->
|
|
<!-- md:flag experimental -->
|
|
|
|
The recommended way to work with instant previews is to use the Markdown
|
|
extension that is included with Material for MkDocs, as it allows you to enable
|
|
instant previews on a per-page or per-section level for your documentation:
|
|
|
|
``` yaml
|
|
markdown_extensions:
|
|
- material.extensions.preview:
|
|
targets:
|
|
include:
|
|
- changelog/index.md
|
|
- customization.md
|
|
- insiders/changelog/*
|
|
- setup/extensions/*
|
|
```
|
|
|
|
The above configuration is what we use for our documentation. We've enabled
|
|
instant previews for our changelogs, customization guide, and Insiders sections,
|
|
as well as for all Markdown extensions that we support.
|
|
|
|
!!! info "Full configuration example"
|
|
|
|
``` yaml
|
|
markdown_extensions:
|
|
- material.extensions.preview:
|
|
sources: # (1)!
|
|
include:
|
|
- ...
|
|
exclude:
|
|
- ...
|
|
targets: # (2)!
|
|
include:
|
|
- ...
|
|
exclude:
|
|
- ...
|
|
```
|
|
|
|
1. Sources specify the pages _on_ which instant previews should be enabled.
|
|
If this setting is omitted, instant previews will be enabled on all
|
|
pages. You can use patterns to include or exclude pages. Exclusion is
|
|
evaluated on top of inclusion, so if a page is matched by both, it will
|
|
be excluded.
|
|
|
|
2. Targets specify the pages _to_ which instant previews should be enabled.
|
|
This is the recommended way to enable instant previews.
|
|
---
|
|
|
|
Instant previews can also be enabled globally by adding the following lines to
|
|
`mkdocs.yml`, which will enable instant previews for all header links,
|
|
alleviating the need to add data attributes:
|
|
|
|
``` yaml
|
|
theme:
|
|
features:
|
|
- navigation.instant.preview
|
|
```
|
|
|
|
!!! info "The [`site_url`][mkdocs.site_url] setting must be set"
|
|
|
|
Note that you must set [`site_url`][mkdocs.site_url] when using instant
|
|
previews, as instant previews rely on the generated `sitemap.xml`
|
|
which will be empty if this setting is omitted. Example:
|
|
|
|
``` yaml
|
|
site_url: https://example.com
|
|
```
|
|
|
|
### Anchor tracking
|
|
|
|
<!-- md:version 8.0.0 -->
|
|
<!-- md:feature -->
|
|
|
|
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
|
|
```
|
|
|
|
### Navigation tabs
|
|
|
|
<!-- md:version 1.1.0 -->
|
|
<!-- md:feature -->
|
|
|
|
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 <!-- md:version 6.2.0 -->, navigation tabs had a slightly different
|
|
behavior. All top-level pages (i.e. all top-level entries directly
|
|
referring 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 <!-- md:version 6.2.0 -->
|
|
on, navigation tabs include all top-level pages and sections.
|
|
|
|
``` yaml
|
|
theme:
|
|
features:
|
|
- navigation.tabs
|
|
```
|
|
|
|
=== "With tabs"
|
|
|
|
[![Navigation tabs enabled]][Navigation tabs enabled]
|
|
|
|
=== "Without"
|
|
|
|
[![Navigation tabs disabled]][Navigation tabs disabled]
|
|
|
|
[Navigation tabs enabled]: ../assets/screenshots/navigation-tabs.png
|
|
[Navigation tabs disabled]: ../assets/screenshots/navigation.png
|
|
|
|
#### Sticky navigation tabs
|
|
|
|
<!-- md:version 7.3.0 -->
|
|
<!-- md:feature -->
|
|
|
|
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
|
|
```
|
|
|
|
=== "With sticky tabs"
|
|
|
|
[![Sticky navigation tabs enabled]][Sticky navigation tabs enabled]
|
|
|
|
=== "Without"
|
|
|
|
[![Sticky navigation tabs disabled]][Sticky navigation tabs disabled]
|
|
|
|
[Sticky navigation tabs enabled]: ../assets/screenshots/navigation-tabs-sticky.png
|
|
[Sticky navigation tabs disabled]: ../assets/screenshots/navigation-tabs-collapsed.png
|
|
|
|
### Navigation sections
|
|
|
|
<!-- md:version 6.2.0 -->
|
|
<!-- md:feature -->
|
|
|
|
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
|
|
```
|
|
|
|
=== "With sections"
|
|
|
|
[![Navigation sections enabled]][Navigation sections enabled]
|
|
|
|
=== "Without"
|
|
|
|
[![Navigation sections disabled]][Navigation sections disabled]
|
|
|
|
[Navigation sections enabled]: ../assets/screenshots/navigation-sections.png
|
|
[Navigation sections disabled]: ../assets/screenshots/navigation.png
|
|
|
|
Both feature flags, [`navigation.tabs`][tabs] and
|
|
[`navigation.sections`][sections], can be combined with each other. If both
|
|
feature flags are enabled, sections are rendered for level 2 navigation items.
|
|
|
|
### Navigation expansion
|
|
|
|
<!-- md:version 6.2.0 -->
|
|
<!-- md:feature -->
|
|
|
|
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
|
|
```
|
|
|
|
=== "With expansion"
|
|
|
|
[![Navigation expansion enabled]][Navigation expansion enabled]
|
|
|
|
=== "Without"
|
|
|
|
[![Navigation expansion disabled]][Navigation expansion disabled]
|
|
|
|
[Navigation expansion enabled]: ../assets/screenshots/navigation-expand.png
|
|
[Navigation expansion disabled]: ../assets/screenshots/navigation.png
|
|
|
|
### Navigation path <small>Breadcrumbs</small> { id=navigation-path }
|
|
|
|
<!-- md:sponsors -->
|
|
<!-- md:version insiders-4.28.0 -->
|
|
<!-- md:feature -->
|
|
<!-- md:flag experimental -->
|
|
|
|
When navigation paths are activated, a breadcrumb navigation is rendered above
|
|
the title of each page, which might make orientation easier for users visiting your
|
|
documentation on devices with smaller screens. Add the following lines to
|
|
`mkdocs.yml`:
|
|
|
|
``` yaml
|
|
theme:
|
|
features:
|
|
- navigation.path
|
|
```
|
|
|
|
=== "With navigation path"
|
|
|
|
[![Navigation path enabled]][Navigation path enabled]
|
|
|
|
=== "Without"
|
|
|
|
[![Navigation path disabled]][Navigation path disabled]
|
|
|
|
[Navigation path enabled]: ../assets/screenshots/navigation-path-on.png
|
|
[Navigation path disabled]: ../assets/screenshots/navigation-path-off.png
|
|
|
|
### Navigation pruning
|
|
|
|
<!-- md:version 9.2.0 -->
|
|
<!-- md:feature -->
|
|
<!-- md:flag 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
|
|
|
|
<!-- md:version 7.3.0 -->
|
|
<!-- md:feature -->
|
|
|
|
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.
|
|
|
|
=== "With section index pages"
|
|
|
|
[![Section index pages enabled]][Section index pages enabled]
|
|
|
|
=== "Without"
|
|
|
|
[![Section index pages disabled]][Section index pages 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 # (1)!
|
|
- Page 1: section/page-1.md
|
|
...
|
|
- Page n: section/page-n.md
|
|
```
|
|
|
|
1. MkDocs also considers files called `README.md` as [index pages].
|
|
|
|
[Section index pages enabled]: ../assets/screenshots/navigation-index-on.png
|
|
[Section index pages disabled]: ../assets/screenshots/navigation-index-off.png
|
|
[toc.integrate]: #navigation-integration
|
|
[index pages]: https://www.mkdocs.org/user-guide/writing-your-docs/#index-pages
|
|
|
|
### Table of contents
|
|
|
|
#### Anchor following
|
|
|
|
<!-- md:version 8.5.0 -->
|
|
<!-- md:feature -->
|
|
<!-- md:flag 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
|
|
```
|
|
|
|
#### Navigation integration
|
|
|
|
<!-- md:version 6.2.0 -->
|
|
<!-- md:feature -->
|
|
|
|
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.
|
|
|
|
=== "With navigation integration"
|
|
|
|
[![Navigation integration enabled]][Navigation integration enabled]
|
|
|
|
=== "Without"
|
|
|
|
[![Navigation integration disabled]][Navigation integration disabled]
|
|
|
|
[table of contents]: extensions/python-markdown.md#table-of-contents
|
|
[Navigation integration enabled]: ../assets/screenshots/toc-integrate.png
|
|
[Navigation integration disabled]: ../assets/screenshots/navigation-tabs.png
|
|
[navigation.indexes]: #section-index-pages
|
|
|
|
### Back-to-top button
|
|
|
|
<!-- md:version 7.1.0 -->
|
|
<!-- md:feature -->
|
|
|
|
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
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Hiding the sidebars
|
|
|
|
<!-- md:version 6.2.0 -->
|
|
<!-- md:flag metadata -->
|
|
|
|
The navigation and/or table of contents sidebars can be hidden for a document
|
|
with the front matter `hide` property. Add the following lines at the top of a
|
|
Markdown file:
|
|
|
|
``` yaml
|
|
---
|
|
hide:
|
|
- navigation
|
|
- toc
|
|
---
|
|
|
|
# Page title
|
|
...
|
|
```
|
|
|
|
=== "Hide navigation"
|
|
|
|
[![Hide navigation enabled]][Hide navigation enabled]
|
|
|
|
=== "Hide table of contents"
|
|
|
|
[![Hide table of contents enabled]][Hide table of contents enabled]
|
|
|
|
=== "Hide both"
|
|
|
|
[![Hide both enabled]][Hide both enabled]
|
|
|
|
[Hide navigation enabled]: ../assets/screenshots/hide-navigation.png
|
|
[Hide table of contents enabled]: ../assets/screenshots/hide-toc.png
|
|
[Hide both enabled]: ../assets/screenshots/hide-navigation-toc.png
|
|
|
|
### Hiding the navigation path
|
|
|
|
<!-- md:sponsors -->
|
|
<!-- md:version insiders-4.28.0 -->
|
|
<!-- md:flag metadata -->
|
|
|
|
While the [navigation path] is rendered above the main headline, sometimes, it
|
|
might be desirable to hide it for a specific page, which can be achieved with
|
|
the front matter `hide` property:
|
|
|
|
``` yaml
|
|
---
|
|
hide:
|
|
- path
|
|
---
|
|
|
|
# Page title
|
|
...
|
|
```
|
|
|
|
[navigation path]: #navigation-path
|
|
|
|
## Customization
|
|
|
|
### Keyboard shortcuts
|
|
|
|
Material for MkDocs includes several keyboard shortcuts that make it possible
|
|
to navigate your project documentation via keyboard. There are two modes:
|
|
|
|
<!-- md:option 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
|
|
|
|
<!-- md:option 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
|