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 several options to configure the behavior of navigational elements, some of those through feature flags.

Configuration

Instant loading

:octicons-file-code-24: Source · :octicons-unlock-24: Feature flag · :octicons-beaker-24: Experimental

When instant loading is activated, clicks on all internal links will be intercepted and dispatched via XHR without fully reloading the page. It can be enabled via mkdocs.yml with:

theme:
  features:
    - 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 sites that come with a massive search index, as the search index will now remain intact in-between document switches.

Navigation expansion

:octicons-file-code-24: Source · :octicons-unlock-24: Feature flag · :octicons-beaker-24: Experimental · :octicons-heart-fill-24:{: .tx-heart } Insiders only{: .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:

theme:
  features:
    - navigation.expand

Navigation tabs

:octicons-file-code-24: Source · :octicons-unlock-24: Feature flag

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 enabled via mkdocs.yml with:

theme:
  features:
    - tabs

Note that 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 will be grouped under the first tab which will receive the title of the first page.

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:
  - Tab 1 + Page 1.1
  - Page 1.2
  - Tab 2:
    - Page 2.1
    - Page 2.2
    - Page 2.3
  - Page 1.3
```

=== "Top-level sections"

``` yaml
nav:
  - Tab 1:
    - Page 1.1
    - Page 1.2
    - Page 1.3
  - Tab 2:
    - Page 2.1
    - Page 2.2
    - Page 2.3
```

Note that tabs are only shown for larger screens, so make sure that navigation is plausible on mobile devices. As another example, see the mkdocs.yml used to render these pages.

Table of contents

:octicons-file-code-24: Source · :octicons-workflow-24: Extension

The Table of contents extension, which is part of the standard Markdown library, provides some options that are supported by Material for MkDocs to 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:

=== "¶"

``` yaml
markdown_extensions:
  - toc:
      permalink: true
```

=== "⚓︎"

``` yaml
markdown_extensions:
  - toc:
      permalink: ⚓︎
```

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:

=== "Unicode"

``` yaml
markdown_extensions:
  - toc:
      slugify: pymdownx.slugs.uslugify
```

=== "Unicode, case-sensitive"

``` yaml
markdown_extensions:
  - toc:
      slugify: pymdownx.slugs.uslugify_cased
```

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:

=== "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 this extension, so they may be supported but can also yield weird results. Use them at your own risk.

Customization

Keyboard shortcuts

:octicons-file-code-24: Source · :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:

• ++arrow-down++ , ++arrow-up++ : select next / previous result
• ++esc++ , ++tab++ : close search dialog
• ++enter++ : follow selected result

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:

• ++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:

app.keyboard$.subscribe(key => {
  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() on the underlying event, so the keypress will not propagate further and touch other event listeners.