Navigation Features¶

Copy page

Copy Markdown link View as Markdown Open in Mistral Le Chat Open in ChatGPT Open in Claude

Create beautiful, hierarchical navigation with sidebar and topbar support.

Sidebar Navigation¶

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¶

• Top-level items: * [Title](link.html) (no indentation)
• Child items: * [Title](link.html) (2 spaces)
• No nesting beyond 2 levels (keep it simple)
• Links auto-convert: .md → .html in rendered output

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.

Placeholders¶

Topbar items support special placeholders. Use double braces so that single braces like {logo} display as literal text in documentation:

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)

Search Bar Placement¶

When MCP search is enabled, place the search bar exactly where you want it using the {{search}} placeholder in any topbar section (left, middle, or right).

Re{{search}} the {{search}} tag — defaults can be set right in the tag. See all options below.

Syntax¶

All Parameters¶

All Options — Examples¶

Default (no params):

* {{search}}

Icon options:

* {{search:icon=lucide-search}}     <!-- default magnifying glass (built-in) -->
* {{search:icon=i-lucide-star}}    <!-- any Lucide icon via Iconify CDN -->
* {{search:icon=i-lucide-search}}   <!-- same as lucide-search, from CDN -->
* {{search:icon=lucide-x}}         <!-- X icon -->
* {{search:icon=lucide-star}}      <!-- star icon (built-in) -->
* {{search:icon=assets/search.svg}} <!-- custom SVG from docs/assets/ -->

Mode options:

* {{search:mode=full}}    <!-- [ Search.... {icon} ] always visible (default) -->
* {{search:mode=button}}  <!-- icon only, tap to expand -->
* {{search:mode=input}}   <!-- input only, no icon -->

Placeholder:

* {{search:placeholder=Search...}}     <!-- default -->
* {{search:placeholder=Zoeken...}}     <!-- Dutch -->
* {{search:placeholder=Find a page...}}

Combined (all params):

* {{search:icon=lucide-search,mode=button,placeholder=Zoeken...}}
* {{search:mode=button,placeholder=Find...}}
* {{search:icon=assets/search.svg,placeholder=Search docs...}}

When {{search}} is present, the search bar renders at that position. When absent, it defaults to the far right of the right section.

Keyboard Shortcuts¶

Copy Page Dropdown¶

On every documentation page, a Copy page dropdown appears to the right of the page title (Nuxt UI-style). It provides:

The AI links use the raw markdown URL so assistants can fetch and read the page content. For self-hosted deployments, set BASE_URL in your environment so these links use your public URL:

BASE_URL=https://docs.example.com uv run python -m docs_server

Without BASE_URL, the server uses the request URL (e.g. http://localhost:8080), which works locally but may not be reachable by AI assistants when deployed.

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¶

Sidebar¶

✅ 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)¶

• Sidebar: Fixed left, always visible
• Topbar: Full width with all sections
• TOC: Fixed right (if content has headings)

Tablet (768px-1200px)¶

• Sidebar: Fixed left, collapsible
• Topbar: Full width
• TOC: Hidden

Mobile (<768px)¶

• Sidebar: Hidden by default, slide-in menu
• Topbar: Compact, hamburger menu
• TOC: Hidden

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¶

• Markdown Features - Content capabilities
• LLMs.txt Support - AI integration
• Examples - Real-world examples