Lantern

Appearance

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:

javascript
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:

bash
# 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:

javascript
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:

javascript
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 🎉

Built with VitePress

Copyright © 2026 Lantern