Improve sidebar navigation category titles

[bhouston]

Improve Sidebar Navigation Category Titles

Description

Currently, the expandable topics in the left-hand navigation bar display raw directory names ("getting-started" and "usage") rather than proper formatted titles. Additionally, there's confusion with having both a "Usage" page and a "usage" category in the sidebar.

Current Behavior

• Sidebar categories display lowercase, hyphenated directory names ("getting-started", "usage")
• There's redundancy with both "usage" (category) and "Usage" (page) appearing in the sidebar
• The formatting doesn't match the professional appearance of the rest of the site

Desired Behavior

• Sidebar categories should have proper titles (e.g., "Getting Started", "Usage")
• Consider consolidating the "Usage" page and "usage" category for better navigation
• Maintain consistent capitalization and formatting across the navigation

Possible Solutions

1. Use category metadata in sidebars.ts: Replace auto-generated sidebar with explicit configuration that includes proper labels
2. Use category.json files: Add metadata files to each directory to specify display names
3. Restructure documentation: Consider reorganizing content to eliminate redundancy

Technical Notes

Docusaurus offers multiple ways to customize category labels:

• Using _category_.json files in each directory
• Configuring explicit sidebar items in sidebars.ts with proper labels
• Using frontmatter in an index.md file in each category

Impact

Improving the sidebar navigation will enhance user experience by providing clearer, more professional navigation labels and reducing confusion from redundant items.

[bhouston]

After researching Docusaurus best practices, I'd like to share some findings that could help with implementing this improvement:

Recommended Approaches for Customizing Sidebar Categories

Option 1: Use _category_.json files (simplest approach)

Add a _category_.json file in each category directory to customize its display name:

docs/
├── getting-started/
│   ├── _category_.json  <- Add this file
│   ├── macOS.md
│   └── ...
└── usage/
    ├── _category_.json  <- Add this file
    └── ...

Example _category_.json content:

{
  "label": "Getting Started",
  "position": 2,
  "link": {
    "type": "generated-index",
    "description": "Getting started with MyCoder installation and setup"
  }
}

Option 2: Define explicit sidebar in sidebars.ts

Replace auto-generated sidebar with explicit configuration:

// sidebars.ts
const sidebars = {
  docs: [
    'intro',
    {
      type: 'category',
      label: 'Getting Started',
      items: [
        'getting-started',
        'getting-started/macos',
        'getting-started/linux',
        'getting-started/windows',
      ],
    },
    {
      type: 'category',
      label: 'Usage Guide',
      items: [
        'usage',
        'usage/configuration',
        'usage/github-mode',
        'usage/performance-profiling',
      ],
    },
    'deployment',
  ],
};

Option 3: Create category index pages

Add an index.md file in each category with frontmatter to define the category:

---
sidebar_label: 'Getting Started'
sidebar_position: 2
---

# Getting Started with MyCoder

This section covers installation instructions for different platforms...

Best Practices for Sidebar Organization

1. Use Title Case for Labels: "Getting Started" instead of "getting-started"
2. Limit Nesting: Keep to 2-3 levels maximum
3. Group Related Content: Organize logically by user tasks
4. Consider Collapsible Categories: Use collapsible: true and collapsed: false for important sections
5. Consistent Naming: Use similar patterns across categories

The _category_.json approach is likely the simplest solution that requires minimal changes to the existing structure while providing proper category labels.

[bhouston]

Resolved.