Skip to content

Navigation

Material for MkDocs provides a comprehensive set of navigation features that create an intuitive and user-friendly documentation experience.

Overview

The navigation system in Material for MkDocs includes:

  • Instant navigation - SPA-like page transitions
  • Navigation tabs - Top-level section organization
  • Expandable sidebar - Hierarchical content structure
  • Breadcrumbs - Current location tracking
  • Table of contents - In-page navigation
  • Previous/Next links - Sequential reading support

Configuration

Enable navigation features in mkdocs.yml:

theme:
  features:
    # Core Navigation
    - navigation.instant       # SPA-like navigation
    - navigation.tracking      # Update URL on scroll
    - navigation.tabs          # Top-level tabs
    - navigation.tabs.sticky   # Keep tabs visible
    - navigation.sections      # Render sections as groups
    - navigation.expand        # Expand all sections
    - navigation.path          # Breadcrumb navigation
    - navigation.indexes       # Section index pages
    - navigation.top           # Back to top button
    - navigation.footer        # Previous/next links

Features in Detail

Instant Navigation

Enable single-page application behavior:

theme:
  features:
    - navigation.instant
    - navigation.instant.progress  # Progress indicator

This feature: - Intercepts internal links - Loads pages via XHR - Updates content without full reload - Preserves scroll position - Shows loading progress

Organize top-level sections into tabs:

theme:
  features:
    - navigation.tabs
    - navigation.tabs.sticky  # Keep visible on scroll

Example structure: 

nav:
  - Home: index.md
  - Getting Started:
    - Installation: getting-started/install.md
    - Quick Start: getting-started/quickstart.md
  - User Guide:
    - Overview: guide/index.md
    - Features: guide/features.md

Sections

Group navigation items visually:

theme:
  features:
    - navigation.sections

This renders top-level items as section headers rather than links.

Expansion

Control section expansion behavior:

theme:
  features:
    - navigation.expand  # Expand all sections

Without this feature, only the active section expands.

Integration

Integrate table of contents into sidebar:

theme:
  features:
    - toc.integrate

Show the current location path:

theme:
  features:
    - navigation.path

Breadcrumbs appear above the page title, showing: 

Home > Getting Started > Installation

Index Pages

Enable section landing pages:

theme:
  features:
    - navigation.indexes

Structure: 

docs/
├── guide/
│   ├── index.md      # Becomes "Guide" link
│   ├── intro.md
│   └── advanced.md

Table of Contents

Configure the on-page navigation:

markdown_extensions:
  - toc:
      permalink: true      # Add anchor links
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
      toc_depth: 3        # Maximum depth

theme:
  features:
    - toc.follow          # Highlight on scroll
    - toc.integrate       # Merge with sidebar

Add previous/next navigation:

theme:
  features:
    - navigation.footer

This adds links at the bottom of each page for sequential reading.

Back to Top

Add a floating button to return to top:

theme:
  features:
    - navigation.top

The button appears when scrolling down and smoothly scrolls to top when clicked.

Advanced Configuration

URL Tracking

Update URL hash on scroll:

theme:
  features:
    - navigation.tracking

This updates the URL to match the current section, enabling direct linking to sections.

Pruning (Insiders)

For large documentation sites:

theme:
  features:
    - navigation.prune    # Render only visible items

This improves performance by only rendering the active navigation path.

Custom Navigation

Override navigation rendering:

<!-- overrides/partials/nav.html -->
<nav class="md-nav md-nav--primary">
  <!-- Custom navigation structure -->
</nav>

Best Practices

1. Logical Structure

Organize content hierarchically:

nav:
  - Introduction: index.md
  - Getting Started:
    - Prerequisites: getting-started/prerequisites.md
    - Installation: getting-started/installation.md
    - First Steps: getting-started/first-steps.md
  - Core Concepts:
    - Overview: concepts/index.md
    - Architecture: concepts/architecture.md
    - Components: concepts/components.md
  - Guides:
    - Beginner:
      - guide/beginner/index.md
      - Your First App: guide/beginner/first-app.md
    - Advanced:
      - guide/advanced/index.md
      - Performance: guide/advanced/performance.md

2. Meaningful Titles

Use clear, descriptive navigation labels:

nav:
  - Home: index.md
  - User Guide:              # Clear section
    - Getting Started: guide/start.md
    - Core Features: guide/features.md
    - Advanced Usage: guide/advanced.md
  - API Reference:           # Technical section
    - Classes: api/classes.md
    - Functions: api/functions.md

3. Consistent Depth

Maintain consistent navigation depth:

  • 2-3 levels for most documentation
  • 4 levels maximum for complex projects
  • Use index pages for deep hierarchies

4. Mobile Optimization

Test navigation on mobile devices:

  • Collapsible sidebar works well
  • Tabs scroll horizontally
  • Touch targets are adequate
  • Back button behavior is correct

Styling

Custom CSS

/* docs/assets/stylesheets/navigation.css */

/* Customize tab appearance */
.md-tabs__link {
  font-weight: 700;
  text-transform: uppercase;
}

/* Active tab indicator */
.md-tabs__link--active {
  color: var(--md-primary-fg-color);
  border-bottom: 2px solid currentColor;
}

/* Sidebar section styling */
.md-nav__title {
  font-weight: 700;
  color: var(--md-default-fg-color--light);
}

/* Breadcrumb styling */
.md-path {
  font-size: 0.7rem;
  color: var(--md-default-fg-color--light);
}

/* Back to top button */
.md-top {
  background-color: var(--md-primary-fg-color);
  color: var(--md-primary-bg-color);
}

Icons

Add icons to navigation items:

nav:
  - Getting Started:
    - :material-download: Installation: install.md
    - :material-rocket-launch: Quick Start: quickstart.md
    - :material-cog: Configuration: config.md

Examples

Multi-Level Navigation

nav:
  - Home: index.md
  - Documentation:
    - Getting Started:
      - Overview: docs/getting-started/index.md
      - Installation:
        - Requirements: docs/getting-started/requirements.md
        - Ubuntu: docs/getting-started/install-ubuntu.md
        - macOS: docs/getting-started/install-macos.md
        - Windows: docs/getting-started/install-windows.md
      - Configuration: docs/getting-started/configuration.md
    - User Guide:
      - Basics: docs/guide/basics.md
      - Advanced: docs/guide/advanced.md
    - Reference:
      - API: docs/reference/api.md
      - CLI: docs/reference/cli.md
      - Configuration: docs/reference/config.md
  - Tutorials:
    - tutorials/index.md
    - Beginner: tutorials/beginner.md
    - Intermediate: tutorials/intermediate.md
    - Advanced: tutorials/advanced.md
  - Blog:
    - blog/index.md
  - About:
    - about/index.md
    - Team: about/team.md
    - License: about/license.md

Dynamic Navigation

Using mkdocs-awesome-pages:

# .pages
nav:
  - index.md
  - getting-started
  - features
  - ...  # Other pages alphabetically
  - about.md

Troubleshooting

Common Issues

  1. Tabs not showing: Ensure top-level navigation has multiple items
  2. Sections not expanding: Check navigation.expand feature
  3. Breadcrumbs missing: Enable navigation.path
  4. TOC not integrating: Add toc.integrate feature

Performance

For large sites: - Use navigation.prune (Insiders) - Limit navigation depth - Consider splitting into multiple sites - Use navigation.instant for faster transitions

Accessibility

Navigation features include:

  • Keyboard navigation support
  • ARIA labels and roles
  • Focus management
  • Screen reader announcements
  • Skip navigation links

See Also