Libx Sample Documentation

Sidebar Auto-generation

This guide explains how the sidebar navigation is generated automatically based on the content structure.

Overview

Sidebar auto-generation enables you to:

  1. Generate sidebar navigation from content files automatically
  2. Use directories and file names to define categories and ordering
  3. Customize sidebar output without editing configuration files manually
  4. Maintain consistent navigation across languages and versions

How It Works

File-based Generation

The sidebar follows these rules:

apps/sample-docs/src/content/docs/[version]/[lang]/
├── 01-guide/
│   ├── 01-getting-started.mdx
│   ├── 02-creating-documents.mdx
│   └── 03-editing-documents.mdx
├── 02-components/
│   ├── 01-overview.mdx
│   ├── 02-icons.mdx
│   └── 03-tabs.mdx
└── 03-advanced/
    ├── 01-customization.mdx
    └── 02-automation.mdx

Naming Rules

Directories

  • Numeric prefixes: 01-guide, 02-components
    control category order
  • Kebab-case names: advanced-topics, getting-started
    keep slugs readable

Files

  • Numeric prefixes: 01-basics.mdx, 02-installation.mdx
    control document order
  • Descriptive names: creating-documents.mdx, sidebar-generation.mdx

Generated Structure

Category Titles

Directory names map to categories automatically:

DirectoryCategory Title
01-guideGuide
02-componentsComponents
03-advancedAdvanced
04-referenceReference

Document Titles

Document titles come from the title field in frontmatter:

---
title: "Creating Documents"
description: "Learn how to create new documentation files"
---

URLs

URLs are derived from the file path:

File: apps/sample-docs/src/content/docs/v2/en/01-guide/02-creating-documents.mdx
URL:  /docs/sample-docs/en/v2/01-guide/02-creating-documents

Sample Output

English Sidebar

[
  {
    "title": "Guide",
    "items": [
      { "title": "Getting Started", "href": "/docs/sample-docs/en/v2/01-guide/01-getting-started" },
      { "title": "Creating Documents", "href": "/docs/sample-docs/en/v2/01-guide/02-creating-documents" },
      { "title": "Editing Documents", "href": "/docs/sample-docs/en/v2/01-guide/03-editing-documents" }
    ]
  },
  {
    "title": "Components",
    "items": [
      { "title": "Overview", "href": "/docs/sample-docs/en/v2/02-components/01-overview" },
      { "title": "Icon Component", "href": "/docs/sample-docs/en/v2/02-components/02-icons" }
    ]
  }
]

Japanese Sidebar

[
  {
    "title": "ガイド",
    "items": [
      { "title": "ドキュメント作成の基本", "href": "/docs/sample-docs/v2/ja/01-guide/01-getting-started" },
      { "title": "ドキュメントの作成", "href": "/docs/sample-docs/v2/ja/01-guide/02-creating-documents" },
      { "title": "ドキュメントの編集", "href": "/docs/sample-docs/v2/ja/01-guide/03-editing-documents" }
    ]
  },
  {
    "title": "コンポーネント",
    "items": [
      { "title": "コンポーネント概要", "href": "/docs/sample-docs/v2/ja/02-components/01-overview" },
      { "title": "アイコンコンポーネント", "href": "/docs/sample-docs/v2/ja/02-components/02-icons" }
    ]
  }
]

Generation Process

1. File Scan

Run the sidebar builder during development or build:

pnpm build:sidebar

2. Structure Analysis

  • Parse directory structure
  • Read numeric prefixes for ordering
  • Extract titles from frontmatter

3. JSON Output

A JSON file is generated per language and version:

apps/sample-docs/public/sidebar/
├── sidebar-en-v1.json
├── sidebar-en-v2.json
├── sidebar-ja-v1.json
└── sidebar-ja-v2.json

4. Distribution

Files are copied to the production output:

dist/docs/sample-docs/pages/public/sidebar/

Customization

Category Translations

Configure translations in scripts/build-sidebar.js:

const categoryTranslations = {
  guide: { en: 'Guide', ja: 'ガイド' },
  components: { en: 'Components', ja: 'コンポーネント' },
  advanced: { en: 'Advanced', ja: '高度' },
  reference: { en: 'Reference', ja: 'リファレンス' }
};

Adjusting Order

Rename directories or files to update ordering:

# Change order
mv 02-components 03-components
mv 03-advanced 02-advanced

# Regenerate sidebar
pnpm build:sidebar

Excluding Files

Skip files via patterns:

const excludePatterns = [
  /draft-/,
  /\.draft\.mdx$/,
  /private/
];

Troubleshooting

Cause: Sidebar JSON not generated
Fix:

pnpm build:sidebar
pnpm build

Incorrect Order

Cause: Numeric prefixes out of sync
Fix:

ls -la apps/sample-docs/src/content/docs/v2/en/01-guide/
mv 03-file.mdx 02-file.mdx

Cause: Paths generated incorrectly
Fix:

cat apps/sample-docs/public/sidebar/sidebar-en-v2.json
cat apps/sample-docs/astro.config.mjs

Advanced Techniques

Dynamic Sidebar

Fetch sidebar data at runtime:

async function updateSidebar() {
  const response = await fetch('/sidebar/sidebar-en-v2.json');
  const sidebarData = await response.json();
  // Update UI
}

Persisting State

Store sidebar preferences:

localStorage.setItem('sidebar-expanded', JSON.stringify({
  guide: true,
  components: false
}));

Best Practices

Organize Files

  • Keep naming consistent
  • Order content according to learning paths
  • Group related topics within the same category

Maintain Regularly

  • Review structures periodically
  • Verify sidebar links after major edits
  • Observe usability feedback from readers

Next Steps

After understanding sidebar automation: