Codex

Configuring Search and Navigation

1 min read

A documentation site is only as useful as its navigation. This guide walks through configuring the three key discovery mechanisms: full-text search, sidebar navigation, and breadcrumbs.

Search is enabled by default but can be customized. The search index rebuilds automatically when content is published or updated.

search:
  enabled: true
  index: auto        # Rebuilds on publish
  fields:
    - title          # Weighted 3x
    - content        # Weighted 1x
    - tags           # Weighted 2x
  min_length: 2      # Minimum query length
  max_results: 20    # Results per page

The fields array controls which content is indexed and how results are ranked. Title matches rank highest by default, followed by tags, then body content. Adjust the weights if your documentation relies heavily on code examples — in that case, content weight should be higher.

The sidebar renders a hierarchical navigation tree based on your tag structure. Each top-level tag becomes a section, and posts within that tag become items.

navigation:
  sidebar:
    - label: Getting Started
      items:
        - Installation
        - Authentication
        - Quick Start Guide
    - label: API Reference
      items:
        - Endpoints
        - Webhooks
        - Error Codes
    - label: Guides
      collapsed: true    # Collapsed by default
      items:
        - Migration Guide
        - Best Practices
        - Troubleshooting

Ordering: Items within each section are ordered by publish date (newest first) by default. To control order explicitly, use the post sort_order field in the Ghost editor.

Collapsed sections: Set collapsed: true on sections that contain many items. Users can expand them on click. The current page's section automatically expands.

Breadcrumbs show the user's location in the documentation hierarchy. They are generated from the tag structure and post title.

breadcrumbs:
  enabled: true
  separator: "/"
  include_home: true
  max_depth: 3       # Truncate deep nesting

The max_depth setting prevents breadcrumbs from becoming unwieldy on deeply nested content. When depth exceeds the limit, intermediate levels are replaced with an ellipsis.

Testing Your Configuration

After updating the configuration, verify the following:

The sidebar automatically adapts to screen size. On mobile, it collapses into a hamburger menu. On tablets, it becomes a collapsible panel. On desktop, it remains fixed in the left column.