Sidebar¶

The sidebar contains the profile card, search filter, and the main navigation tree.

Profile card¶

extra:
  sidebar:
    image: assets/img/avatar.png   # path relative to docs/
    name: My Project
    tagline: Short description
    links:
      - platform: github
        url: https://github.com/user/repo
      - platform: twitter
        url: https://twitter.com/user
      - platform: linkedin
        url: https://linkedin.com/in/user
      - platform: website
        url: https://example.com

All fields are optional. If image is omitted, no avatar is shown.

Supported platforms for links¶

Each link uses platform: to automatically render the correct icon:

If you omit platform: and use title: instead, a text pill is shown:

links:
  - title: Documentation  # renders as a text badge
    url: https://example.com

Navigation tree¶

The sidebar navigation is driven by the nav: key in mkdocs.yml. MkDocs processes it and marks active pages automatically.

nav:
  - Home: index.md
  - Getting Started:
    - Installation: getting-started/install.md
    - Config: getting-started/config.md
  - API: api.md

Nesting¶

Sections collapse and expand with animation. The currently active section is auto-expanded on page load. You can nest as deep as needed — there is no limit.

nav:
  - Level 1:
    - Level 2:
      - Level 3:
        - Level 4:
          - Level 5: deep/page.md

Search filter¶

The search box at the top of the sidebar filters navigation links in real-time on the client side. It does not perform full-text search across page content — for that, the built-in MkDocs search plugin is used.

Customising the sidebar width¶

/* docs/assets/extra.css */
:root { --sidebar-w: 320px; }