TypeDoc VitePress Theme

TypeDoc VitePress Theme is a specialized TypeDoc theme that extends typedoc-plugin-markdown to generate Markdown output specifically formatted for VitePress static site generators. It serves as a bridge between TypeDoc's API documentation generation capabilities and VitePress's Markdown-based documentation system, enabling developers to automatically generate comprehensive API documentation that seamlessly integrates with VitePress sites.

Package Information

• Package Name: typedoc-vitepress-theme
• Package Type: npm
• Language: TypeScript
• Installation: npm install typedoc-vitepress-theme
• Peer Dependencies: typedoc-plugin-markdown >=4.4.0

Core Imports

import { load } from "typedoc-vitepress-theme";

For CommonJS:

const { load } = require("typedoc-vitepress-theme");

Basic Usage

import { MarkdownApplication } from "typedoc-plugin-markdown";
import { load } from "typedoc-vitepress-theme";

// Load the plugin into a TypeDoc application
const app = new MarkdownApplication();
load(app);

// Plugin automatically configures options and event handlers
// No additional setup required

Architecture

The TypeDoc VitePress Theme is built around several key components:

• Plugin Loader: Main load function that registers the theme with TypeDoc
• Options System: Configurable options for VitePress integration and sidebar generation
• Sidebar Generation: Multiple format support (VitePress, VuePress 1.x, VuePress 2.x)
• URL Processing: Anchor slug formatting and link processing for VitePress compatibility
• Event Handling: Post-processing of generated markdown for VitePress optimization

Capabilities

Plugin Loading

Main entry point function that registers the theme with a TypeDoc markdown application instance.

/**
 * Load the VitePress theme plugin into a TypeDoc markdown application
 * @param app - TypeDoc markdown application instance
 */
function load(app: MarkdownApplication): void;

Required Import:

import { MarkdownApplication } from "typedoc-plugin-markdown";

The load function performs the following operations when called:

1. Registers Plugin Options: Adds configuration options for VitePress integration

   • docsRoot: Path to VitePress project root directory
   • sidebar: Configuration for autogenerated VitePress sidebar

2. Sets Default Presets: Applies optimal TypeDoc settings for VitePress:

   • hidePageHeader: true - Removes page headers from generated markdown
   • entryFileName: "index.md" - Uses index.md as entry file name
   • out: "./api" - Sets default output directory

3. Configures Event Handlers: Sets up post-processing for VitePress compatibility:

   • Processes internal links to ensure proper anchor formatting
   • Applies VitePress-compatible URL slugification to anchor links

4. Enables Sidebar Generation: Automatically generates sidebar configuration files:

   • Creates typedoc-sidebar.json with navigation structure
   • Supports multiple formats: VitePress, VuePress 1.x, VuePress 2.x
   • Configurable output formatting and collapsible behavior

Types

The plugin defines the following TypeScript interfaces for configuration:

interface PluginOptions {
  /**
   * The path to the VitePress project root.
   */
  docsRoot: string;
  
  /**
   * Configures the autogenerated VitePress sidebar.
   */
  sidebar: Sidebar;
}

interface Sidebar {
  /** Enable/disable automatic sidebar generation */
  autoConfiguration: boolean;
  /** Sidebar format - "vitepress", "vuepress1", or "vuepress2" */
  format: string;
  /** Pretty format the sidebar JSON output */
  pretty: boolean;
  /** Determines if sidebar items with children are collapsed by default */
  collapsed: boolean;
}

Configuration Options

The plugin automatically registers the following TypeDoc options that can be configured in your typedoc.json:

docsRoot Option

Specifies the path to the VitePress project root directory. Required when TypeDoc runs from outside the VitePress project root.

{
  "docsRoot": "./docs"
}

Use Case Example:

├── package.json
├── typedoc.json          # TypeDoc runs from here
└── docs/                 # VitePress root (set as docsRoot)
    ├── .vitepress/
    └── api/              # TypeDoc output directory
        └── index.md

sidebar Option

Configures the autogenerated VitePress sidebar with the following properties:

• autoConfiguration (boolean): Enable/disable automatic sidebar generation (default: true)
• format (string): Sidebar format - "vitepress", "vuepress1", or "vuepress2" (default: "vitepress")
• pretty (boolean): Pretty format the sidebar JSON output (default: false)
• collapsed (boolean): Determines if sidebar items with children are collapsed by default (default: true)

{
  "sidebar": {
    "autoConfiguration": true,
    "format": "vitepress",
    "pretty": true,
    "collapsed": false
  }
}

Configuration Examples

Basic VitePress Configuration

{
  "out": "./docs/api",
  "docsRoot": "./docs"
}

Custom Sidebar Configuration

{
  "out": "./docs/api",
  "docsRoot": "./docs", 
  "sidebar": {
    "autoConfiguration": true,
    "format": "vitepress",
    "pretty": true,
    "collapsed": false
  }
}

VuePress Compatibility

For VuePress 2.x projects:

{
  "out": "./docs/api",
  "docsRoot": "./docs",
  "sidebar": {
    "autoConfiguration": true,
    "format": "vuepress2",
    "pretty": true,
    "collapsed": true
  }
}

For VuePress 1.x projects:

{
  "out": "./docs/api", 
  "docsRoot": "./docs",
  "sidebar": {
    "autoConfiguration": true,
    "format": "vuepress1",
    "pretty": true,
    "collapsed": true
  }
}

Integration Notes

File Structure Requirements

When using the plugin, ensure your project structure accommodates the VitePress configuration:

├── package.json
├── typedoc.json
└── docs/
    ├── .vitepress/
    └── api/           # Generated by TypeDoc
        ├── index.md
        └── typedoc-sidebar.json

Generated Files

The plugin automatically generates:

• API Documentation: Markdown files compatible with VitePress
• Sidebar Configuration: typedoc-sidebar.json file containing navigation structure
• Optimized Links: Processed internal links with proper anchor formatting

Usage in TypeDoc Configuration

Complete example of using the plugin in a TypeDoc configuration:

{
  "entryPoints": ["./src/index.ts"],
  "out": "./docs/api",
  "docsRoot": "./docs",
  "plugin": ["typedoc-plugin-markdown", "typedoc-vitepress-theme"],
  "sidebar": {
    "autoConfiguration": true,
    "format": "vitepress",
    "pretty": true,
    "collapsed": false
  }
}

VitePress Integration

To integrate the generated documentation into your VitePress site:

1. Install the plugin: npm install typedoc-vitepress-theme
2. Configure TypeDoc: Add the plugin to your typedoc.json
3. Run TypeDoc: Generate the API documentation
4. Include in VitePress: Reference the generated typedoc-sidebar.json in your VitePress configuration

Example VitePress config integration:

import sidebarConfig from './api/typedoc-sidebar.json';

export default {
  themeConfig: {
    sidebar: {
      '/api/': sidebarConfig
    }
  }
}