@docsgen/docusaurus

Docusaurus plugin that integrates docsgen into your site's build lifecycle. Install, configure, build.

Documentation | Quick Start | Guides

About

@docsgen/docusaurus is a Docusaurus plugin that hooks into the site's build lifecycle to automatically generate API documentation from your TypeScript source. It calls @docsgen/core under the hood and includes smart caching so generation only runs when needed, not on every hot reload.

Key Capabilities

• Zero-config integration - Register as a standard Docusaurus plugin and API docs appear on your next build
• Automatic lifecycle - Runs TypeDoc parsing and MDX generation during Docusaurus loadContent, before the site renders
• Smart caching - Uses a TTL-based instance file to avoid re-running expensive TypeDoc parsing on every dev server reload (throttled to once per minute per plugin instance)
• Multi-instance - Run multiple plugin instances with different id values to generate separate API sections for different packages or entry points
• Full @docsgen/core power - All configuration options, page templates, and customization from @docsgen/core are available through the plugin options

Quick Start

1. Install

npm install @docsgen/core @docsgen/docusaurus

2. Add the plugin

In your docusaurus.config.ts:

import plugin from "@docsgen/docusaurus";

const config = {
  plugins: [
    [
      "@docsgen/docusaurus",
      {
        id: "api",
        outDir: "docs/api",
        packages: [
          {
            title: "my-library",
            dir: "../packages/my-library",
            entryPath: "src/index.ts",
            tsconfigDir: "../packages/my-library",
          },
        ],
      },
    ],
  ],
};

3. Configure sidebars

Use Docusaurus autogenerated sidebars for the API section:

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

export default sidebars;

4. Build

npm run build

Structured MDX pages for every class, function, type, and enum appear in docs/api/, organized by category and always matching your source.

Monorepo Setup

Document multiple packages in a single Docusaurus site:

const config = {
  plugins: [
    [
      "@docsgen/docusaurus",
      {
        id: "api",
        outDir: "docs/api",
        addMonorepoPage: true,
        addPackagePage: true,
        packages: [
          {
            title: "@my-scope/core",
            dir: "../packages/core",
            entryPath: "src/index.ts",
          },
          {
            title: "@my-scope/react",
            dir: "../packages/react",
            entryPath: "src/index.ts",
          },
          {
            title: "@my-scope/utils",
            dir: "../packages/utils",
            entryPath: ["src/strings.ts", "src/numbers.ts"],
          },
        ],
      },
    ],
  ],
};

Add the Importer

Embed live API fragments in hand-written guides using the importer remark plugin from @docsgen/core:

import { importer } from "@docsgen/core";

const config = {
  presets: [
    [
      "classic",
      {
        docs: {
          remarkPlugins: [
            importer({
              packageRoute: "api",
              apiDir: "docs/api",
            }),
          ],
        },
      },
    ],
  ],
};

Then in any MDX file:

(@import my-library MyClass type=methods&display=table)

See the Importer guide for the full reference.

Configuration

All options from @docsgen/core are passed through the plugin. See the Configuration reference for the complete list.

| Option | Type | Required | Description | | ----------------- | ------------------------- | -------- | ------------------------------------ | | id | string | Yes | Unique plugin instance identifier | | outDir | string | Yes | Output directory for generated files | | packages | PackageOptions[] | Yes | Array of packages to document | | generateMdx | boolean | No | Generate MDX files (default: true) | | typeDocOptions | Partial<TypeDocOptions> | No | TypeDoc configuration overrides | | watch | boolean | No | Enable watch mode for development | | addMonorepoPage | boolean | No | Generate monorepo index page | | addPackagePage | boolean | No | Generate per-package index pages | | logLevel | LogLevel | No | Logging verbosity | | pages | PagesOptions | No | Per-kind page template overrides |

Peer Dependencies

• @docsgen/core
• @docusaurus/plugin-content-docs >= 2.0.0
• @docusaurus/types >= 2.0.0
• react >= 16.8.0
• react-dom >= 16.8.0

Documentation

• Getting Started
• Quick Start
• Configuration
• Importer
• Customization
• Guides

License

Apache-2.0