rspress-navigation

Generate RSPress Navigation Structure

Generates progressive navigation structure (_meta.json files) for RSPress documentation sites.

Overview

This skill creates hierarchical navigation by:

1. Analyzing existing documentation structure
2. Organizing content by user journey
3. Creating _meta.json files
4. Setting collapsible sections
5. Ordering content progressively (basic → advanced)
6. Generating breadcrumb paths

Quick Start

Generate navigation for entire module:

/rspress-navigation effect-type-registry

Generate navigation for specific section:

/rspress-navigation rspress-plugin-api-extractor --section=guides

Preview structure without writing:

/rspress-navigation website --dry-run

How It Works

1. Parse Parameters

• module: Module name from design.config.json [REQUIRED]
• --section: Specific section (concepts, guides, examples) (optional)
• --strategy: Organization strategy (journey, alphabetical, category) (optional)
• --dry-run: Preview without writing (optional)

2. Load Module Configuration

Reads design.config.json to find:

• Site docs path
• Module structure
• Configured sections

3. Scan Documentation Structure

Finds all documentation files:

• Landing page (index.mdx)
• Concept pages (concepts/*.mdx)
• Guide pages (guides/*.mdx)
• Example pages (examples/*.mdx)
• API docs (api/*.md - excluded from user navigation)

4. Extract Page Metadata

For each page, reads:

• Frontmatter title
• File name
• Heading structure
• Dependencies (prerequisites)
• Complexity indicators

5. Determine Organization Strategy

User Journey (default):

• Order by learning progression
• Beginner content first
• Advanced content last
• Related pages grouped

Alphabetical:

• Sort by title A-Z
• Simple, predictable
• Good for reference sections

Category:

• Group by topic/feature
• Collapsible categories
• Related content together

6. Generate Top-Level Navigation

Creates {siteDocs}/_meta.json:

{
  "index": {
    "title": "Overview",
    "type": "page"
  },
  "concepts": {
    "title": "Concepts",
    "type": "dir",
    "collapsible": true,
    "collapsed": false
  },
  "guides": {
    "title": "Guides",
    "type": "dir",
    "collapsible": true,
    "collapsed": false
  },
  "examples": {
    "title": "Examples",
    "type": "dir",
    "collapsible": true,
    "collapsed": true
  },
  "api": {
    "title": "API Reference",
    "type": "dir",
    "collapsible": true,
    "collapsed": true
  }
}

7. Generate Section Navigation

Creates {siteDocs}/{section}/_meta.json for each section:

{
  "index": {
    "title": "Overview"
  },
  "getting-started": {
    "title": "Getting Started"
  },
  "advanced-usage": {
    "title": "Advanced Usage"
  }
}

8. Set Collapsible Behavior

Determines which sections should be:

• Expanded by default: Core concepts, getting started
• Collapsed by default: Advanced topics, API reference
• Always visible: Critical pages

9. Validate Navigation

Checks:

• All _meta.json files are valid JSON
• All referenced files exist
• No orphaned pages (files not in navigation)
• No circular references
• Breadcrumb paths work

10. Generate Navigation Report

Creates report with:

• Navigation structure visualization
• Orphaned pages
• Missing titles
• Recommended improvements

Organization Strategies

User Journey Strategy

Organizes content for progressive learning:

1. Overview (what and why)
2. Getting Started (first steps)
3. Basic Concepts (foundations)
4. How-To Guides (common tasks)
5. Advanced Concepts (deeper understanding)
6. Examples (real-world scenarios)
7. API Reference (detailed specs)

Alphabetical Strategy

Simple A-Z ordering:

• Predictable navigation
• Easy to find specific topics
• No semantic grouping

Category Strategy

Groups by topic or feature:

• Related content together
• Collapsible categories
• Feature-based navigation

Navigation Best Practices

Hierarchy:

• Max 3 levels deep
• Landing page at root
• Sections for major topics
• Individual pages within sections

Ordering:

• Basic before advanced
• Prerequisites before dependents
• Frequently used before rarely used
• Concepts before implementation

Titles:

• Clear and descriptive
• Consistent naming
• Action-oriented for guides ("How to...")
• Noun-based for concepts

Collapsibility:

• Core content expanded by default
• Advanced content collapsed
• API reference collapsed
• Examples collapsed unless featured

Supporting Documentation

• instructions.md - Detailed navigation generation process
• examples.md - Sample navigation structures

Success Criteria

• ✅ All _meta.json files generated
• ✅ Valid JSON structure
• ✅ All pages included in navigation
• ✅ Logical ordering applied
• ✅ Collapsible sections configured
• ✅ No orphaned pages

Integration Points

• Uses .claude/design/design.config.json
• Scans files in {siteDocs} directory
• Reads frontmatter from MDX files
• Excludes auto-generated API docs from organization

Related Skills

• /rspress-guide - Generate documentation pages
• /rspress-page - Scaffold individual pages
• /rspress-nav - Configure top-level navigation
• /rspress-review - Review navigation structure