Sidebar Auto-Generation

This guide explains how to use the sidebar auto-generation feature to automatically create sidebar navigation based on your content structure.

Overview

The sidebar auto-generation feature allows you to:

1. Automatically generate sidebar navigation based on your content files
2. Define categories and their order using frontmatter
3. Control the order of items within categories
4. Customize sidebar display without manually updating configuration files

Enabling Auto-Generation

To enable sidebar auto-generation, set the useAutoSidebar option to true in your docs.config.ts file:

// apps/sample-docs/src/config/docs.config.ts
const docsConfig = {
  // ... other options
  
  // Enable auto sidebar generation
  useAutoSidebar: true,
  
  // ... other options
};

Frontmatter Configuration

To control how your content appears in the sidebar, use these frontmatter properties:

---
title: "Your Document Title"
description: "Document description"
category: "guide"  # Category name (optional, defaults to path-based category)
categoryOrder: 1   # Order of the category in the sidebar (optional)
order: 2           # Order within the category (optional)
---

Properties

How It Works

The sidebar generation process follows these steps:

1. Collects all content files for the current language and version
2. Groups them by category (from frontmatter or file path)
3. Sorts categories based on categoryOrder
4. Sorts documents within each category based on order
5. Generates the sidebar structure with proper titles and links

Path-Based Categories

If you don’t specify a category in the frontmatter, the system will use the path-based category. For example:

• A file at src/content/docs/en/v1/guide/getting-started.mdx will be categorized as “guide”
• A file at src/content/docs/en/v1/api/reference.mdx will be categorized as “api”

Category Titles

Category titles are determined in the following order:

1. Translation key matching docs.{category} (e.g., docs.guide → “Guide”)
2. If no translation is found, the category name is capitalized (e.g., “guide” → “Guide”)

Example

Here’s a complete example of a document frontmatter:

---
title: "Getting Started"
description: "Learn how to get started with our platform"
category: "guide"
categoryOrder: 1
order: 1
pubDate: 2025-01-01
updatedDate: 2025-01-01
author: "Docs Team"
next:
  text: "Installation"
  link: "/en/v1/guide/installation"
---

This will place the document in the “Guide” category (which will be ordered first in the sidebar), and it will be the first item within that category.