Skip to content
ArdoArdo

TypeDoc Integration

Generate API reference pages from the TypeScript source your users already depend on.

TypeDoc Integration

For React libraries and design systems, prose is only half the documentation. Users also need to inspect props, functions, types, and exports. Ardo's built-in TypeDoc integration generates linked API reference pages from your TypeScript source during the docs build.

Quick Start

1. Configure TypeDoc

Add the typedoc configuration to your vite.config.ts:

import { defineConfig } from "vite"
import { ardo } from "ardo/vite"

export default defineConfig({
  plugins: [
    ardo({
      title: "My Library",

      typedoc: {
        enabled: true,
        entryPoints: ["../src/index.ts"],
        tsconfig: "../tsconfig.json",
        out: "api",
      },
    }),
  ],
})

The TypeDoc plugin is automatically included when typedoc config is provided.

2. Run the Build

The API documentation will be automatically generated when you build your site:

pnpm build

Configuration Options

entryPoints

  • Type: string[]
  • Required: Yes

The entry points for TypeDoc to process. These are typically your library's main export files.

typedoc: {
  entryPoints: ['./src/index.ts', './src/utils/index.ts'],
}

tsconfig

  • Type: string

Path to your tsconfig.json file.

typedoc: {
  tsconfig: './tsconfig.json',
}

out

  • Type: string
  • Default: 'api-reference'

Output directory for generated markdown files (relative to srcDir).

typedoc: {
  out: 'reference/api',
}

Filtering Options

Control what gets documented:

typedoc: {
  excludeExternals: true,    // Exclude external modules
  excludePrivate: true,      // Exclude private members
  excludeProtected: false,   // Include protected members
  excludeInternal: true,     // Exclude @internal members
  exclude: ['**/*.test.ts'], // Exclude patterns
}

Sorting

Control the order of documented members:

typedoc: {
  sort: ['source-order'],
  // Or: ['alphabetical', 'required-first', 'visibility']
}

Customize how the API docs appear in the sidebar:

typedoc: {
  sidebar: {
    title: 'API Reference',
    position: 100,
    collapsed: false,
  },
}

Markdown Options

Control the generated markdown:

typedoc: {
  markdown: {
    breadcrumbs: true,
    hierarchy: true,
    sourceLinks: true,
    sourceBaseUrl: 'https://github.com/user/repo/blob/main',
    codeBlocks: true,
  },
}

To enable links to your source code on GitHub, configure the sourceBaseUrl:

typedoc: {
  markdown: {
    sourceLinks: true,
    sourceBaseUrl: 'https://github.com/your-username/your-repo/blob/main',
  },
}

Watch Mode

Enable watch mode for development to regenerate docs when source files change:

typedoc: {
  watch: true,
}

Generated Output

TypeDoc generates markdown files that include:

  • Module/Namespace pages - Overview of exports
  • Class pages - Properties, methods, constructors
  • Interface pages - Properties with types
  • Type alias pages - Type definitions
  • Function pages - Signatures, parameters, return types
  • Enum pages - Member values

Example Output

For a function like:

/**
 * Greets a user by name.
 *
 * @param name - The name of the user
 * @returns A greeting message
 *
 * @example
 * ```ts
 * greet('World') // 'Hello, World!'
 * ```
 */
export function greet(name: string): string {
  return `Hello, ${name}!`
}

TypeDoc generates:

# Function: greet

Greets a user by name.

## Signature

function greet(name: string): string

### Parameters

| Name | Type     | Description          |
| ---- | -------- | -------------------- |
| name | `string` | The name of the user |

### Returns

`string`

A greeting message

## Examples

greet('World') // 'Hello, World!'

Full Example

Here's a complete configuration example:

import { defineConfig } from "vite"
import { ardo } from "ardo/vite"

export default defineConfig({
  plugins: [
    ardo({
      title: "My Library Docs",
      description: "Documentation for my awesome library",

      typedoc: {
        enabled: true,
        entryPoints: ["../packages/my-lib/src/index.ts"],
        tsconfig: "../packages/my-lib/tsconfig.json",
        out: "api",

        excludePrivate: true,
        excludeInternal: true,
        sort: ["source-order"],

        sidebar: {
          title: "API Reference",
          position: 50,
        },

        markdown: {
          breadcrumbs: true,
          hierarchy: true,
          sourceLinks: true,
          sourceBaseUrl: "https://github.com/my-org/my-lib/blob/main/packages/my-lib",
        },
      },
    }),
  ],
})

Programmatic Usage

You can also use the TypeDoc generator programmatically:

import { generateApiDocs } from "ardo/typedoc"

const docs = await generateApiDocs(
  {
    enabled: true,
    entryPoints: ["./src/index.ts"],
    tsconfig: "./tsconfig.json",
  },
  "./docs/content"
)

console.log(`Generated ${docs.length} documentation pages`)