mkdocs-material/docs/setup/setting-up-navigation.md

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 and sections, and its flag-ship feature: [instant loading] navigation.instant.

Configuration

Instant loading

:octicons-tag-24: 5.0.0 · :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:

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.

Anchor tracking

:octicons-tag-24: 8.0.0 · :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:

theme:
  features:
    - navigation.tracking

Navigation tabs

:octicons-tag-24: 1.1.0 · :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.¹ Add the following lines to mkdocs.yml:

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]

Sticky navigation tabs

:octicons-tag-24: 7.3.0 · :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:

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 sections

:octicons-tag-24: 6.2.0 · :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:

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]

Both feature flags, navigation.tabs and 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 · :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:

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 pruning :material-alert-decagram:

:octicons-heart-fill-24:{ .mdx-heart } Sponsors only{ .mdx-insiders } · :octicons-tag-24: insiders-4.16.0 · :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:

theme:
  features:
    - navigation.prune # (1)!

1. This feature flag is not compatible with 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).

Section index pages

:octicons-tag-24: 7.3.0 · :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:

theme:
  features:
    - navigation.indexes # (1)!

1. This feature flag is not compatible with 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:

nav:
  - Section:
    - section/index.md
    - Page 1: section/page-1.md
    ...
    - Page n: section/page-n.md

Table of contents

Anchor following

:octicons-heart-fill-24:{ .mdx-heart } Sponsors only{ .mdx-insiders } · :octicons-tag-24: insiders-4.8.0 · :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:

theme:
  features:
    - toc.follow

Navigation integration

:octicons-tag-24: 6.2.0 · :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:

theme:
  features:
    - toc.integrate # (1)!

1. This feature flag is not compatible with 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]

Back-to-top button

:octicons-tag-24: 7.1.0 · :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:

theme:
  features:
    - navigation.top

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:

---
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]

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
```

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
```

---

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. ↩︎