Related sites¶

Link related projects through extra.site_navigation in mkdocs.yml. Omit it to show no related-site navigation. For pages within the current site, use Navigation.

Items¶

Define the links once. The footer and both header presentations use the same ordered items list; catalog adds a link to the complete project directory.

extra:
  site_navigation:
    items:
      - title: Documentation
        url: https://example.com/docs/
        active: true
      - title: API reference
        url: https://example.com/api/
    catalog:
      title: All projects
      url: https://example.com/projects/

Each item and the catalog need a title and URL. Mark the current project with active: true; it isn't inferred from the URL.

The default header presentation is a dropdown. The footer is independently enabled when a catalog is configured. Merge the settings below into the same extra.site_navigation block; keep the items and catalog defined above.

Footer¶

Show related-site links before the theme attribution:

extra:
  site_navigation:
    show_footer: true
    footer_size: 3
    footer_label: Projects

The footer requires catalog. footer_size includes that final link, so the example displays the first two items followed by All projects. The default size of 1 shows only the catalog. Links stack vertically on narrow screens and don't display item icons.

Set show_footer: false to hide these links without changing the header. For footer-only links, also set header_mode: none. For footer text and attribution, see Branding.

Header: inline¶

Place text links directly in the header instead of using a dropdown:

extra:
  site_navigation:
    header_mode: inline
    header_size: 3

The header has one presentation at a time: inline, dropdown (default), or none. Footer visibility is independent.

Inline links require catalog. Like the footer, a size of 3 displays the first two items plus the catalog; the default size of 1 shows only the catalog. Inline links hide on narrow screens and don't display item icons.

Header: dropdown¶

Use a toolbar button to open all configured links:

extra:
  site_navigation:
    header_mode: dropdown
    dropdown_label: Projects

The dropdown appears when items or catalog provides links; an empty configuration doesn't add a button. It shows every item, followed by the optional catalog, regardless of header_size or footer_size.

Hover previews the dropdown; moving into the menu keeps it open and leaving closes it. Click to pin it open. A second mouse click returns to hover preview, while touch and keyboard activation toggle it. Escape or an outside click dismisses it. Use Tab or arrow keys to navigate.

Item icons¶

Each item and the catalog can specify an icon path relative to docs_dir or an image URL. Artwork appears in the dropdown; omitted artwork gets a themed pixel fallback.

extra:
  site_navigation:
    items:
      - title: API reference
        url: https://example.com/api/
        icon: assets/api.svg
        icon_hover: assets/api.svg#icon-hover

icon_hover replaces the resting image on hover or focus and restarts on each entry. An SVG can use :target with a fragment to provide animation. Use same-origin assets or CORS-enabled URLs. Reduced-motion users retain the static image; loading failures also leave the resting icon unchanged.

Static images use a 24 × 24 px slot. Hover-enabled images use 24 × 44 px, including vertical breathing room; include that room in both SVG canvases.

Toolbar icons¶

Customize the button's artwork through theme.icon:

theme:
  name: pixel-lab
  icon:
    sites: assets/icons/sites.svg
    dropdown: assets/icons/chevron.svg

See Icons for image formats and paths.

Further customization¶

Style related-site links and the dropdown with these theme settings:

See Common attributes.