CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-docusaurus-plugin-typedoc

A Docusaurus plugin to integrate TypeDoc with the Docusaurus CLI for generating API documentation.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

index.mddocs/

Docusaurus Plugin TypeDoc

A Docusaurus plugin that integrates TypeDoc with the Docusaurus CLI to automatically generate and include TypeScript API documentation in Docusaurus sites. The plugin uses typedoc-plugin-markdown to generate markdown-formatted API documentation that integrates seamlessly with Docusaurus build processes.

Package Information

  • Package Name: docusaurus-plugin-typedoc
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install docusaurus-plugin-typedoc
  • Peer Dependencies: typedoc-plugin-markdown (>=4.8.0)

Core Imports

import docusaurusPluginTypedoc from "docusaurus-plugin-typedoc";
import { PluginOptions } from "docusaurus-plugin-typedoc";

For CommonJS:

const docusaurusPluginTypedoc = require("docusaurus-plugin-typedoc");

Basic Usage

Add the plugin to your docusaurus.config.js:

module.exports = {
  plugins: [
    [
      'docusaurus-plugin-typedoc',
      {
        entryPoints: ['./src/index.ts'],
        tsconfig: './tsconfig.json',
        out: './docs/api',
        cleanOutputDir: true,
        disableSources: true,
        hidePageHeader: true,
        hideBreadcrumbs: true,
      }
    ]
  ]
};

Or with multiple API documentation instances:

module.exports = {
  plugins: [
    [
      'docusaurus-plugin-typedoc', 
      {
        id: 'api-core',
        entryPoints: ['./src/core/index.ts'],
        out: './docs/api-core',
        tsconfig: './tsconfig.json',
      }
    ],
    [
      'docusaurus-plugin-typedoc',
      {
        id: 'api-utils', 
        entryPoints: ['./src/utils/index.ts'],
        out: './docs/api-utils',
        tsconfig: './tsconfig.json',
      }
    ]
  ]
};

Architecture

The plugin architecture consists of:

  • Plugin Function: Main Docusaurus plugin that integrates with the build lifecycle
  • CLI Extension: Adds generate-typedoc command for standalone documentation generation
  • TypeDoc Bootstrap: Handles TypeDoc application setup with plugin-specific options
  • Options Processing: Merges user options with Docusaurus preset defaults
  • File Management: Creates output directories and manages documentation generation

Capabilities

Plugin Function

The main plugin export that integrates TypeDoc generation with Docusaurus.

/**
 * Main Docusaurus plugin function for TypeDoc integration
 * @param context - Docusaurus load context containing site configuration
 * @param opts - Plugin options merged with TypeDoc options
 * @returns Promise resolving to Docusaurus plugin object
 */
export default function pluginDocusaurus(
  context: LoadContext,
  opts: Partial<PluginOptions & TypeDocOptions>
): Promise<{
  name: string;
  extendCli(cli: Cli): void;
}>;

Plugin Options

Configuration interface extending TypeDoc plugin options for Docusaurus integration.

/**
 * Plugin configuration options interface
 * Extends both typedoc-plugin-markdown and typedoc-docusaurus-theme options
 */
export interface PluginOptions 
  extends TypedocPluginMarkdownOptions, TypedocDocusaurusThemeOptions {}

/** Common options from typedoc-plugin-markdown */
interface TypedocPluginMarkdownOptions {
  /** Output file extension (default: '.md') */
  fileExtension?: string;
  /** Hide page header */
  hidePageHeader?: boolean;
  /** Hide breadcrumb navigation */
  hideBreadcrumbs?: boolean;
  /** Hide page title */
  hidePageTitle?: boolean;
  /** Flatten output files to single directory */
  flattenOutputFiles?: boolean;
  /** Entry file name */
  entryFileName?: string;
  /** Modules file name */
  modulesFileName?: string;
  /** Format for class properties */
  classPropertiesFormat?: 'list' | 'table' | 'htmlTable';
  /** Format for interface properties */
  interfacePropertiesFormat?: 'list' | 'table' | 'htmlTable';
  /** Format for enumeration members */
  enumMembersFormat?: 'list' | 'table' | 'htmlTable';
  /** Format for parameters */
  parametersFormat?: 'list' | 'table' | 'htmlTable';
  /** Format for type aliases */
  typeAliasPropertiesFormat?: 'list' | 'table' | 'htmlTable';
  /** Public path for URLs */
  publicPath?: string;
  /** Exclude scopes in paths */
  excludeScopesInPaths?: boolean;
  /** Use code blocks for signatures */
  useCodeBlocks?: boolean;
  /** Expand parameters in signatures */
  expandParameters?: boolean;
  /** Expand objects in declarations */
  expandObjects?: boolean;
  /** Clean output directory before generation */
  cleanOutputDir?: boolean;
  /** Custom anchor prefix */
  anchorPrefix?: string;
  /** Merge readme with index */
  mergeReadme?: boolean;
  /** Members with own files */
  membersWithOwnFile?: ('Enum' | 'Variable' | 'Function' | 'Class' | 'Interface' | 'TypeAlias')[];
}

/** Options from typedoc-docusaurus-theme */
interface TypedocDocusaurusThemeOptions {
  /** The value of the Docusaurus docs.path config option */  
  docsPath?: string;
  /** The value of the Docusaurus numberPrefixParser option */
  numberPrefixParser?: boolean;
  /** Configures the autogenerated sidebar */
  sidebar?: Sidebar;
}

Types

LoadContext

Docusaurus load context interface providing site configuration and directory information.

interface LoadContext {
  /** Root directory of the Docusaurus site */
  siteDir: string;
  /** Site configuration object */
  siteConfig: {
    /** Array of configured plugins */
    plugins?: any[];
    /** Array of configured presets */
    presets?: any[];
  };
}

Cli

Command-line interface builder for extending Docusaurus CLI.

interface Cli {
  /** Add a new command to the CLI */
  command(name: string): Cli;
  /** Set description for the current command */
  description(desc: string): Cli;
  /** Add an option flag to the current command */
  option(flag: string, desc?: string): Cli;
  /** Set the action function for the current command */
  action(fn: (...args: any[]) => void): void;
}

TypeDoc Options

Common TypeDoc configuration options used by the plugin.

interface TypeDocOptions {
  /** TypeScript configuration file path */
  tsconfig?: string;
  /** Entry points for TypeDoc analysis */
  entryPoints?: string[];
  /** Output directory for generated documentation */
  out?: string;
  /** TypeDoc plugins to load */
  plugin?: string[];
  /** Whether to watch for file changes */
  watch?: boolean;
  /** Clean output directory before generation */
  cleanOutputDir?: boolean;
  /** Disable source code links */
  disableSources?: boolean;
  /** Hide page headers in generated docs */
  hidePageHeader?: boolean;
  /** Hide breadcrumb navigation */
  hideBreadcrumbs?: boolean;
  /** TypeDoc logging level */
  logLevel?: 'Verbose' | 'Info' | 'Warn' | 'Error';
  /** Readme handling mode */
  readme?: 'none' | string;
}

Sidebar

Sidebar configuration interface for Docusaurus theme options.

interface Sidebar {
  /** Enable automatic sidebar configuration */
  autoConfiguration: boolean;
  /** Use pretty formatting in sidebar */
  pretty: boolean;
  /** Include TypeScript-specific configuration */
  typescript: boolean;
  /** CSS class name for deprecated items */
  deprecatedItemClassName: string;
}

CLI Command

The plugin adds a generate-typedoc command to the Docusaurus CLI:

npx docusaurus generate-typedoc

This command generates TypeDoc documentation independently of the Docusaurus build process, using the same configuration from your docusaurus.config.js plugins array.

Default Configuration

The plugin applies these default configurations:

  • Output Directory: ./docs/api
  • Docs Path: Extracted from Docusaurus docs preset configuration
  • Number Prefix Parser: Inherited from docs preset settings (default: true)
  • Required Plugins: typedoc-plugin-markdown and typedoc-docusaurus-theme are automatically included

Install with Tessl CLI

npx tessl i tessl/npm-docusaurus-plugin-typedoc

docs

index.md

tile.json