Sidebar Configuration

---

docsgen generates MDX files with _category_.json sidecars that integrate with Docusaurus autogenerated sidebars. This guide covers different sidebar layouts, from simple single-sidebar setups to advanced configurations with separate API and docs sidebars.

---

Purpose

1. Autogenerated basics - Understand how _category_.json files drive sidebar structure.
2. Separate sidebars - Keep generated API docs in their own sidebar.
3. Mixed content - Combine hand-written guides and generated content in one sidebar.
4. Category control - Order and customize category folders in the sidebar.

---

How docsgen Integrates with Sidebars

When docsgen generates documentation, it writes _category_.json files in each category folder (Classes, Functions, Types, etc.). These files tell Docusaurus how to label and position the category in the sidebar:

{
  "position": 2
}

Each symbol's MDX file also includes sidebar_position in its frontmatter:

---
sidebar_position: 1
title: MyClass
sidebar_label: MyClass
---

When you use type: "autogenerated" in sidebars.ts, Docusaurus reads these files automatically and builds the sidebar tree.

---

Layout 1: Single Sidebar

The simplest setup puts everything in one autogenerated sidebar:

const sidebars = {
  docs: [
    {
      type: "autogenerated",
      dirName: ".",
    },
  ],
};

export default sidebars;

This includes both hand-written docs (guides, tutorials) and generated API docs in a single sidebar. The generated api/ folder appears as a category alongside your other doc folders.

When to use a single sidebar

• Small projects with a few exported symbols.
• Documentation where API reference and guides are tightly coupled.
• Projects where users navigate linearly from guides to API docs.

---

Layout 2: Separate API Sidebar

For larger projects, a dedicated API sidebar keeps generated content separate from hand-written docs:

const sidebars = {
  docs: [{ type: "autogenerated", dirName: "guides" }],
  api: [{ type: "autogenerated", dirName: "api" }],
};

export default sidebars;

This creates two independent sidebars:

• docs - Contains your hand-written guides from the docs/guides/ directory.
• api - Contains the generated API reference from the docs/api/ directory.

Users switch between sidebars using the navigation bar. Each sidebar has its own hierarchy and does not mix with the other.

When to use separate sidebars

• Projects with extensive API surfaces (many classes, functions, types).
• Documentation where guides and API reference serve different user needs.
• Monorepos with multiple packages generating many pages.

---

Layout 3: Mixed Content with Manual Sections

For precise control, combine autogenerated sections with manually defined entries:

const sidebars = {
  docs: [
    {
      type: "category",
      label: "Getting Started",
      items: [{ type: "autogenerated", dirName: "guides/getting-started" }],
    },
    {
      type: "category",
      label: "API Reference",
      items: [{ type: "autogenerated", dirName: "api" }],
    },
  ],
};

export default sidebars;

This puts guides and API reference into named categories within the same sidebar. The autogenerated items fill in the contents of each category.

---

Controlling Category Order

Use orderCategories in PackageOptions to set the position value in _category_.json files:

{
  packages: [
    {
      title: "core",
      dir: "../packages/core",
      entryPath: "src/index.ts",
      orderCategories: {
        Classes: 1,
        Functions: 2,
        Hooks: 3,
        Types: 4,
        Enums: 5,
        Variables: 6,
      },
    },
  ],
}

Lower numbers appear first in the sidebar. Without explicit ordering, Docusaurus sorts categories alphabetically.

---

Adding Custom Categories

Use additionalCategories to create category folders that do not come from TypeDoc:

{
  additionalCategories: [
    {
      name: "Guides",
      category: { label: "Guides", position: 0 },
    },
    {
      name: "Examples",
      category: { label: "Examples", position: 99 },
    },
  ],
}

This creates the folders with _category_.json files in the generated output. You can then place hand-written MDX files inside them, and they will appear in the sidebar at the specified position.

---

Monorepo Sidebar Configuration

For monorepos with multiple packages, each package becomes a subfolder under the API directory. The autogenerated sidebar creates a nested structure:

const sidebars = {
  api: [{ type: "autogenerated", dirName: "api" }],
};

This produces:

API
  Overview                    # Monorepo index (if addMonorepoPage: true)
  core/
    Overview                  # Package README (if addPackagePage: true)
    Classes/
      Client
      Request
    Functions/
      createClient
    Types/
      ClientOptions
  react/
    Overview
    Hooks/
      useClient
      useFetch
    Types/
      ...

Per-Package Sidebars

If you want each package in its own sidebar (for example, with a package switcher), you can configure separate sidebar entries:

const sidebars = {
  core: [{ type: "autogenerated", dirName: "api/core" }],
  react: [{ type: "autogenerated", dirName: "api/react" }],
  cli: [{ type: "autogenerated", dirName: "api/cli" }],
};

---

Package README as Index Page

When addPackagePage is true (the default), docsgen generates an index.mdx for each package from its README file. This page appears as the first item in the package's sidebar section, labeled "Overview".

To disable this for a specific package:

{
  packages: [
    {
      title: "internal-utils",
      dir: "../packages/internal-utils",
      entryPath: "src/index.ts",
      hasPackagePage: false,
    },
  ],
}

---

Combining with the Importer

The sidebar configuration works independently from the importer remark plugin. You can have:

• Generated API pages in the api sidebar (from the plugin)
• Hand-written guides in the docs sidebar (with @import directives pulling data from the API output)

Both use the same generated docs.json and options.json files. The sidebar configuration only controls where the files appear in navigation.

---

Summary

Use type: "autogenerated" sidebars with dirName pointing to your generated output directory. Choose between a single sidebar, separate API sidebar, or mixed layout depending on your project size. Control category order with orderCategories and add custom sections with additionalCategories. For monorepos, each package automatically gets its own subfolder in the sidebar. See Setup for the full integration guide.