VitePress Sidebar - Hybrid Auto-Generation Approach

Overview

The VitePress sidebar configuration now uses a hybrid approach that combines:

• Manual curation for high-level structure, ordering, and special sections
• Automatic generation for subdirectories to reduce maintenance burden

This gives us the best of both worlds: ✅ Control over navigation structure and presentation ✅ Automatic discovery of new documentation files ✅ Consistent formatting and titling ✅ Reduced manual maintenance

How It Works

Auto-Generation Helper: sidebar.mjs

The /docs/.vitepress/sidebar.mjs file provides utility functions:

1. autoGenerateSidebarItems(dir, options) - Generates sidebar items from markdown files in a directory
2. autoGenerateNestedSidebar(dir, options) - Generates nested sidebar from directory structure
3. formatTitle(fileName) - Converts filenames to human-readable titles

Configuration: config.mjs

The main configuration file imports these helpers and uses them selectively:

import { autoGenerateSidebarItems } from './sidebar.mjs'

// Manual top-level structure
sidebar: [
  {
    text: '⚙️ Engineering',
    items: [
      {
        text: '🏗️ Architecture',
        collapsed: false,
        // Auto-generate from /docs/engineering/architecture/*.md
        items: autoGenerateSidebarItems('engineering/architecture')
      }
    ]
  }
]

What's Auto-Generated

The following sections are automatically generated from directory contents:

Engineering Subdirectories

• ✅ Architecture (engineering/architecture/)
• ✅ Deployment (engineering/deployment/)
• ✅ Security (engineering/security/)
• ✅ Mobile (engineering/mobile/)
• ✅ Testing (engineering/testing/)
• ✅ Guides (engineering/guides/)

Feature Subdirectories

• ✅ Safety Mechanics (features/safety/)
• ✅ Frens System (features/frens/)
• ✅ Profile System (features/profile/)
• ✅ Wave-to-Meet (features/wave/)
• ✅ Lantern Hub (features/lantern-hub/)

Other Sections

• ✅ Storybook (storybook/)
• ✅ Governance (governance/)
• ✅ Security (security/)
• ✅ Development Log (worklog/)
• ✅ Audits (audit/)

What's Still Manual

The following remain manually curated:

Top-Level Structure

• Section ordering (Getting Started → Engineering → Features → etc.)
• Section titles and emoji icons
• Collapsed/expanded states
• Root-level files (ABOUT, CONTRIBUTING, TODO)

Special Sections

• Getting Started - Carefully curated onboarding flow
• Features (root) - Top-level feature overview files
• Business - Strategic documents
• Economics - Financial models
• Design - Design system docs
• Development - Contributing, TODO, sitemap

Adding New Documentation

For Auto-Generated Sections

Simply add a markdown file to the appropriate directory:

# Add a new architecture doc
touch docs/engineering/architecture/NEW_CONCEPT.md

# It will automatically appear in the sidebar on next build!

Custom Sorting

Some sections have custom sort orders defined:

autoGenerateSidebarItems('engineering/architecture', {
  sortFn: (a, b) => {
    // SCAFFOLD first, then alphabetical
    if (a === 'SCAFFOLD.md') return -1
    if (b === 'SCAFFOLD.md') return 1
    return a.localeCompare(b)
  }
})

Excluding Files

You can exclude specific files from auto-generation:

autoGenerateSidebarItems('governance', {
  excludeFiles: ['SECURITY.md'] // Goes in different section
})

Title Formatting Rules

The formatTitle() function automatically:

1. Removes common prefixes/suffixes:

   • QUICK_START_* → "Quick Start: *"
   • *_GUIDE → "* Guide"
   • *_REF → "* Reference"
   • *_SUMMARY → "* Summary"

2. Converts underscores/hyphens to spaces:

   • ZERO_KNOWLEDGE_ENCRYPTION → "Zero Knowledge Encryption"

3. Capitalizes words intelligently:

   • Keeps acronyms uppercase: API, PWA, IP, SOS, etc.
   • Title-cases other words

Examples

Input Filename → Output Title

• SCAFFOLD.md → "Scaffold"
• QUICK_START_DOCS.md → "Quick Start: Docs"
• ZERO_KNOWLEDGE_ENCRYPTION.md → "Zero Knowledge Encryption"
• DEPLOYMENT_GUIDE.md → "Deployment Guide"
• FRENS_QUICK_REF.md → "Frens Quick Reference"
• PWA_SETUP.md → "PWA Setup"

When to Extend Auto-Generation

Consider adding more auto-generation when:

1. A section has 5+ files - Manual maintenance becomes tedious
2. Files follow naming conventions - Auto-formatting works well
3. Ordering isn't critical - Alphabetical or simple sort is fine
4. New files added frequently - Reduces update friction

When to Keep Manual

Keep manual configuration when:

1. Order matters significantly - Like Getting Started flow
2. Custom grouping needed - Special subsections or categories
3. Few files (< 5) - Manual is simpler
4. Special formatting - Unique icons, descriptions, or metadata

Maintenance

To add a new auto-generated section:

1. Edit docs/.vitepress/config.mjs
2. Replace manual items: [...] with items: autoGenerateSidebarItems('path/to/dir')
3. Add custom sortFn if needed
4. Test with npm run docs:build

To customize title formatting:

1. Edit docs/.vitepress/sidebar.mjs
2. Update formatTitle() function
3. Add new patterns or exceptions as needed

Benefits of This Approach

✅ Reduced maintenance: New files automatically appear ✅ Consistency: All titles formatted the same way ✅ Flexibility: Can still manually curate important sections ✅ Discoverability: Nothing gets forgotten in subdirectories ✅ Future-proof: Easy to extend or modify automation

Future Enhancements

Potential improvements:

• [ ] Auto-generate from frontmatter titles (if present in markdown)
• [ ] Support for multi-level nesting (currently 2 levels max)
• [ ] Tag-based filtering and grouping
• [ ] Automatic "New!" badges for recent files
• [ ] Integration with search for better cross-referencing

---

Last Updated: 2026-01-10 Approach: Hybrid Manual + Auto-Generated Maintenance Burden: Low 🎉