Skip to content
Last updated

Navigation elements

Redocly offers comprehensive navigation customization to help users easily discover and navigate through your documentation. From simple link organization to advanced multi-product sites, you can configure navigation elements to match your project's structure and branding needs.

Available navigation elements

Core navigation

  • Navbar - Top navigation bar with links, groups, and dropdowns
  • Sidebar - Left navigation panel (configure content with sidebars.yaml)
  • Footer - Bottom page footer with links and copyright information
  • Search - Site-wide search functionality with faceting capabilities

Page navigation

Advanced navigation

Quick start examples

Basic site navigation

For a simple documentation site with standard navigation:

redocly.yaml
navbar:
  items:
    - page: index.md
      label: Home
    - page: docs/getting-started.md
      label: Getting Started
    - page: api-reference.md
      label: API Reference

footer:
  copyrightText: "© 2024 Your Company. All rights reserved."
  items:
    - group: Documentation
      items:
        - page: docs/guides.md
          label: Guides
        - href: https://support.example.com
          label: Support
          external: true

search:
  engine: flexsearch

Multi-product site

For documentation covering multiple products or services:

redocly.yaml
products:
  - id: product-a
    name: Product A
    slug: /product-a/
  - id: product-b
    name: Product B
    slug: /product-b/

navbar:
  items:
    - group: Products
      items:
        - page: product-a/index.md
          label: Product A
        - page: product-b/index.md
          label: Product B
    - page: support.md
      label: Support

# Hide sidebar on landing pages
sidebar:
  hide: true

Enterprise search setup

For advanced search with faceting (Enterprise+ plans):

redocly.yaml
search:
  engine: typesense
  facets:
    - name: Category
      field: redocly_category
      type: multi-select
    - name: Product
      field: product
      type: multi-select
    - name: Version
      field: version
      type: tags

Landing page pattern

For sites with a dedicated landing page, typically hide the sidebar on the landing page by not including it in a sidebars.yaml file. If you don't have a sidebars.yaml file, you can exclude it in front matter.

In a Markdown file:

index.md
---
sidebar:
  hide: true
---

In a TSX file:

index.page.tsx
export const frontmatter = {
  sidebar: {
    hide: true
  }
};

Documentation section pattern

For traditional documentation with hierarchical navigation:

docs/
├──index.md              # Landing page
├──getting-started/
│   ├──index.md
│   ├──installation.md
│   └──sidebars.yaml     # Section-specific navigation
├──guides/
│   ├──index.md
│   ├──advanced.md
│   └──sidebars.yaml
└──sidebars.yaml         # Main navigation

API documentation pattern

For API-focused sites with reference and guides:

redocly.yaml
navbar:
  items:
    - page: index.md
      label: Overview
    - page: guides/index.md
      label: Guides
    - group: API Reference
      items:
        - page: users-api.yaml
          label: Users API
        - page: orders-api.yaml
          label: Orders API

catalogClassic:
  enabled: true
  title: API Catalog
  slug: /apis/

Configuration tips

Responsive navigation

All navigation elements are responsive by default. For mobile-optimized experiences:

  • Keep navbar items concise (5-7 top-level items max)
  • Use groups sparingly in navbar dropdowns
  • Consider shorter labels for mobile: label: API Ref instead of label: API Reference

Performance considerations

  • Search facets: More facets mean more processing - use only necessary facets
  • Sidebar depth: Deep nesting can impact performance and UX
  • External links: Use external: true for links opening in new tabs

Accessibility

  • Always provide meaningful label values for screen readers
  • Use descriptive link text instead of "click here" or "read more"
  • Maintain logical navigation hierarchy

Localization support

All navigation elements support localization through translation keys:

redocly.yaml
navbar:
  items:
    - page: index.md
      label: Home
      labelTranslationKey: nav.home

footer:
  items:
    - group: Legal
      groupTranslationKey: footer.legal

See the localization configuration for complete setup details.

Need help

 
Next page