Navigation Features

Create beautiful, hierarchical navigation with sidebar and topbar support.

The sidebar provides the main documentation structure with collapsible groups.

Structure Format

Create sidebar.md with this format:

# Navigation

* [Home](index.html)
* [Getting Started](getting-started.html)
* [User Guide](user-guide.html)
  * [Installation](user-guide/install.html)
  * [Configuration](user-guide/config.html)
  * [Troubleshooting](user-guide/troubleshoot.html)
* [API Reference](api.html)
  * [REST API](api/rest.html)
  * [GraphQL](api/graphql.html)

Rules

Types

The sidebar automatically detects two types:

  1. Standalone Links - No children, clickable
  2. Groups - Has children, header + children both clickable

Topbar Navigation

The topbar provides quick access to key pages and external links.

Structure Format

Create topbar.md with sections:

# Top Bar

## left
* [📚 Docs](index.html)
* [🚀 Quick Start](quick-start.html)

## middle
* Version 2.0

## right
* [GitHub](https://github.com/project)
* [Discord](https://discord.gg/project)

Sections

Left Section - Main navigation 

## left
* [Home](index.html)
* [Docs](docs.html)

Middle Section - Breadcrumbs, version info (optional) 

## middle
* v2.0.0
* [Changelog](changelog.html)

Right Section - External links, social 

## right
* [GitHub](https://github.com/project)
* [Twitter](https://twitter.com/project)

Active State Highlighting

Both sidebar and topbar automatically highlight the current page.

In sidebar: - Active page gets blue background - Orange left border accent - Bold text

In topbar: - Active link gets blue background - Subtle color change

Logo Support

Add a logo to the topbar left section:

## left
* {logo} | [Home](index.html)
* [Docs](docs.html)

Place your logo at docs/assets/logo.svg

Examples

Minimal Sidebar

# Navigation

* [Home](index.html)
* [About](about.html)
* [Contact](contact.html)

Complex Sidebar

# Documentation

* [Home](index.html)
* [Quick Start](quick-start.html)
* [Features](features.html)
  * [Markdown Support](features/markdown.html)
  * [Navigation](features/navigation.html)
  * [LLMs.txt](features/llms-txt.html)
  * [Caching](features/caching.html)
* [Deployment](deployment.html)
  * [Docker](deployment/docker.html)
  * [Kubernetes](deployment/k8s.html)
  * [Cloud](deployment/cloud.html)
* [API Reference](api.html)
  * [Endpoints](api/endpoints.html)
  * [Authentication](api/auth.html)
  * [Rate Limiting](api/rate-limit.html)
* [Contributing](contributing.html)
  * [Code of Conduct](contributing/coc.html)
  * [Development Setup](contributing/setup.html)
  * [Pull Request Process](contributing/pr-process.html)

Simple Topbar

# Top Bar

## left
* [Docs](index.html)

## right
* [GitHub](https://github.com/project)

Full Topbar

# Top Navigation

## left
* {logo} | [Docs Home](index.html)
* [Quick Start](quick-start.html)
* [API](api.html)

## middle
* v2.1.0
* [Release Notes](changelog.html)

## right
* [GitHub](https://github.com/project)
* [Issues](https://github.com/project/issues)
* [Discord](https://discord.gg/project)
* [Twitter](https://twitter.com/project)

Best Practices

✅ DO: - Keep hierarchy shallow (max 2 levels) - Use clear, descriptive titles - Group related content - Order by user journey - Limit to 10-15 top-level items

❌ DON'T: - Over-nest (3+ levels) - Use generic titles ("Misc", "Other") - List every single page - Alphabetize blindly - Create huge lists

Topbar

✅ DO: - Keep it minimal (3-5 items per section) - Put important links in left - Use icons/emojis for visual interest - Link to external resources in right - Version info in middle

❌ DON'T: - Overload with links - Duplicate sidebar content - Use only text (boring!) - Hide important pages - Ignore mobile users

Responsive Behavior

Desktop (>768px)

Tablet (768px-1200px)

Mobile (<768px)

Styling

Colors

Navigation uses the theme colors:

--accent-primary: #f26a28;  /* Accent color */
--color-primary: #3b82f6;   /* Active links */
--color-gray-700: #374151;  /* Normal text */
--color-gray-50: #f9fafb;   /* Hover background */

Customization

To customize, modify templates.py:

# Change accent color
.nav-group-header.active {
    border-left: 3px solid #your-color;
}

# Change hover color
.nav-group-link:hover {
    background-color: #your-color;
}

Next Steps