Managing Document Collections

Learning Outcomes

By the end of this guide, you will be able to:

• Add new document collections to your Courseasaurus site
• Configure sidebars and navigation for collections
• Use AI to generate collection configurations
• Understand Docusaurus plugin architecture

Understanding Document Collections

A document collection in Docusaurus is a group of related markdown files that share:

• A common directory
• A unified sidebar navigation
• Consistent routing structure
• Shared metadata

Common collections in a Courseasaurus site:

• lecture-notes/ - Course lecture content
• labs/ - Lab assignments
• assignments/ - Homework and projects
• lecture-slides/ - RevealJS presentations
• docs/ - Documentation (like this manual!)

Why Add New Collections?

You might want to add collections for:

• Tutorials - Step-by-step guides
• Resources - Reference materials, cheat sheets
• Readings - Required or supplemental readings
• Case Studies - Real-world examples
• Team Projects - Separate from individual assignments
• Study Guides - Exam preparation materials

Adding a New Collection

Step 1: Create the Directory

Create a new directory in your project root:

mkdir resources

Add your first markdown file:

echo "# Resources\n\nWelcome to the resources collection!" > resources/intro.md

Step 2: Configure the Plugin

Edit docusaurus.config.ts to add the new collection:

plugins: [
  // ... existing plugins
  [
    '@docusaurus/plugin-content-docs',
    {
      id: 'resources',           // Unique identifier
      path: 'resources',         // Directory path
      routeBasePath: 'resources', // URL path
      sidebarPath: './sidebars.ts',
      // ... other options
    },
  ],
],

Key configuration options:

• id - Unique identifier for this collection
• path - Directory containing the markdown files
• routeBasePath - URL path (e.g., /resources/intro)
• sidebarPath - Path to sidebar configuration file
• editUrl - GitHub edit URL (optional)

Step 3: Add Sidebar Configuration

Edit sidebars.ts to add the sidebar for your new collection:

const sidebars: SidebarsConfig = {
  // ... existing sidebars
  
  resourcesSidebar: [
    {
      type: 'autogenerated',
      dirName: '.',  // Generate from 'resources' directory
    }
  ],
};

Sidebar generation options:

Option A: Autogenerated (recommended for most cases)

resourcesSidebar: [{type: 'autogenerated', dirName: '.'}]

• Automatically creates sidebar from directory structure
• Files sorted alphabetically
• Uses sidebar_position frontmatter for ordering

Option B: Manual (for custom organization)

resourcesSidebar: [
  'intro',
  {
    type: 'category',
    label: 'Programming Languages',
    items: ['python-guide', 'java-guide', 'javascript-guide'],
  },
  {
    type: 'category',
    label: 'Tools',
    items: ['git-cheatsheet', 'docker-guide'],
  },
]

Step 4: Add Navigation Link

Add a link to the navbar in docusaurus.config.ts:

themeConfig: {
  navbar: {
    items: [
      // ... existing items
      {
        to: '/resources',
        position: 'left',
        label: 'Resources',
      },
    ],
  },
}

Step 5: Test Your Configuration

npm start

Check:

• ✅ New collection appears in navbar
• ✅ Sidebar generates correctly
• ✅ Links work
• ✅ No build errors

Meta-Example: This Site's Sidebar Configuration

This Courseasaurus documentation site manages multiple collections. Here's the actual sidebars.ts:

const sidebars: SidebarsConfig = {
  // Lecture notes collection
  lectureNotesSidebar: [{type: 'autogenerated', dirName: '.'}],
  
  // Instructor manual (you're reading this!)
  docsSidebar: [{type: 'autogenerated', dirName: '.'}],
  
  // Labs collection
  labsSidebar: [{type: 'autogenerated', dirName: '.'}],
  
  // Assignments collection
  assignmentsSidebar: [{type: 'autogenerated', dirName: '.'}],
  
  // Lecture slides collection
  lectureSlidesSidebar: [{type: 'autogenerated', dirName: '.'}],
};

Each collection:

• Has its own sidebar
• Uses autogenerated navigation
• Maintains independent organization
• Can be developed separately

Organizing Files Within Collections

Using Frontmatter for Ordering

Control sidebar order with sidebar_position:

---
sidebar_position: 1
---

# Introduction to Resources

Lower numbers appear first.

Creating Subcategories

Organize with subdirectories:

resources/
├── intro.md
├── programming/
│   ├── python-guide.md
│   ├── java-guide.md
│   └── javascript-guide.md
└── tools/
    ├── git-cheatsheet.md
    └── docker-guide.md

Autogeneration creates categories automatically!

Control category labels with _category_.json:

{
  "label": "Programming Languages",
  "position": 2,
  "collapsed": false
}

Custom Sidebar Labels

Override default labels (from filename or title):

---
sidebar_label: "Python Quick Start"
---

# Comprehensive Guide to Python Programming

Sidebar shows "Python Quick Start" instead of the full title.

Advanced Configuration

Multiple Instances of Same Plugin

Each collection needs its own plugin instance:

plugins: [
  // Lecture notes
  [
    '@docusaurus/plugin-content-docs',
    {
      id: 'lecture-notes',
      path: 'lecture-notes',
      routeBasePath: 'lecture-notes',
      sidebarPath: './sidebars.ts',
    },
  ],
  // Labs
  [
    '@docusaurus/plugin-content-docs',
    {
      id: 'labs',
      path: 'labs',
      routeBasePath: 'labs',
      sidebarPath: './sidebars.ts',
    },
  ],
  // ... more collections
],

Versioning Collections

For courses taught multiple semesters:

{
  id: 'lecture-notes',
  path: 'lecture-notes',
  routeBasePath: 'lecture-notes',
  versions: {
    current: {
      label: 'Spring 2026',
    },
  },
}

Enable with: npm run docusaurus docs:version:lecture-notes 1.0

Custom Edit URLs

Link to GitHub for easy editing:

{
  id: 'resources',
  path: 'resources',
  routeBasePath: 'resources',
  editUrl: 'https://github.com/your-org/course-repo/edit/main/',
}

Using AI for Collection Setup

AI can help generate and apply configuration code for new collections by proposing direct edits to your config files.

Example Prompt:

"I want to add a 'tutorials' collection to my Docusaurus site. The directory is called 'tutorials' and I want it available at the /tutorials route. Propose the plugin configuration for docusaurus.config.ts, the sidebar entry for sidebars.ts, and a sample intro.md file. Follow AGENTS.md instructions for project consistency."

The AI will:

• Analyze your existing docusaurus.config.ts and sidebars.ts for context
• Propose additions via diffs for both files
• Suggest creating the tutorials/ directory and intro.md
• Ensure unique IDs and proper structure

AI Response Review Checklist:

When AI proposes configurations:

• ✅ Unique IDs: Each collection must have a unique id
• ✅ Correct paths: Paths match your actual directories
• ✅ No duplicates: Not duplicating existing collections
• ✅ Syntax: Valid TypeScript syntax
• ✅ Sidebar reference: References correct sidebar from sidebars.ts
• ✅ Diff accuracy: Verify the proposed insertions in context

Always Test the Build

After reviewing and accepting the AI's proposed changes:

1. Save the updated files
2. Run npm start
3. Fix any errors before finalizing
4. Test all navigation links

AI can make subtle syntax errors that break builds—always verify!

Good AI Prompts for Collections

Generating initial structure:

"Create a skeleton collection for 'study-guides' including a sample intro.md file with appropriate frontmatter. Propose the config updates for docusaurus.config.ts and sidebars.ts."

Understanding structure:

"Explain the difference between the id, path, and routeBasePath fields in Docusaurus plugin configuration, and propose an example for a new 'readings' collection."

Troubleshooting:

"My new 'resources' collection isn't appearing in the navbar. Here's the relevant part of my docusaurus.config.ts: [paste config]. Propose the fix via diff."

The AI coding assistant, per AGENTS.md, handles these setup tasks by providing precise, context-aware proposals.

Common Pitfalls

1. Forgetting the Plugin ID

// ❌ Wrong: Missing unique ID
plugins: [
  [
    '@docusaurus/plugin-content-docs',
    {
      path: 'resources',
      routeBasePath: 'resources',
    },
  ],
]

// ✅ Correct: Include unique ID
plugins: [
  [
    '@docusaurus/plugin-content-docs',
    {
      id: 'resources',  // Required!
      path: 'resources',
      routeBasePath: 'resources',
    },
  ],
]

2. Sidebar Name Mismatch

Sidebar name in sidebars.ts must match what the plugin expects:

// In sidebars.ts
const sidebars: SidebarsConfig = {
  resourcesSidebar: [...]  // Must be named correctly
};

Convention: {id}Sidebar or explicitly set in plugin config.

3. Wrong Directory Structure

// ❌ Wrong
src/
  resources/
    intro.md

// ✅ Correct
resources/
  intro.md

Collections should be in project root (or configured path), not in src/.

4. Broken Internal Links

When linking between collections:

<!-- ❌ Wrong -->
[See lecture notes](../lecture-notes/l1-intro.md)

<!-- ✅ Correct -->
[See lecture notes](/lecture-notes/l1-intro)

Use absolute paths without .md extension.

Validation Strategy

After adding a collection:

1. Build passes: npm run build completes without errors
2. Navigation works: Collection appears in navbar
3. Sidebar generates: All documents appear in sidebar
4. Links work: Internal links resolve correctly
5. Routing correct: URLs match expectations

When to Use AI vs. Manual Configuration

Use AI for:

• Generating initial configuration boilerplate via diffs
• Understanding configuration options
• Troubleshooting build errors
• Creating file templates and proposing insertions

Do manually:

• Deciding collection structure (pedagogical choice)
• Organizing content within collections (you know the flow)
• Testing and validation (must verify yourself)
• Final decision on what collections to create

Next Steps

Now that you can add collections:

1. Plan your structure: What collections does your course need? Ask AI for suggestions.
2. Start simple: Add one collection using AI proposals, test it, then add more
3. Manage schedules: Explore Schedule Management for the course calendar

---

Remember: Collections are organizational tools. Don't over-organize early. Start with basic collections (lecture notes, labs, assignments) and add specialized collections only when you have enough content to warrant them.

Meta: AI Usage in Collections Guide

• AI generated example configurations and prompts
• All code snippets manually verified against Docusaurus docs
• Structure decisions based on pedagogical best practices
• Review process ensured consistency with project rules in AGENTS.md