or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration-options.mdevents-hooks.mdindex.mdplugin-bootstrap.mdrouting-system.mdtheme-system.md
tile.json

tessl/npm-typedoc-plugin-markdown

A plugin for TypeDoc that enables TypeScript API documentation to be generated in Markdown.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/typedoc-plugin-markdown@4.8.x

To install, run

npx @tessl/cli install tessl/npm-typedoc-plugin-markdown@4.8.0

index.mddocs/

TypeDoc Plugin Markdown

TypeDoc Plugin Markdown is a plugin for TypeDoc that enables TypeScript API documentation to be generated in Markdown format. It extends TypeDoc's functionality by providing custom themes and output formats specifically designed for Markdown-based documentation systems, allowing developers to generate comprehensive API documentation from TypeScript source code while outputting clean, structured Markdown files.

Package Information

  • Package Name: typedoc-plugin-markdown
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install typedoc-plugin-markdown

Core Imports

The plugin is primarily used via TypeDoc's plugin system, but also exports public API components for customization:

// Main plugin function (for programmatic use)
import { load } from "typedoc-plugin-markdown";

// Public API components for customization
import { 
  MarkdownTheme, 
  MarkdownThemeContext,
  MarkdownPageEvent,
  MarkdownRendererEvent,
  MemberRouter,
  ModuleRouter
} from "typedoc-plugin-markdown";

Most commonly, the plugin is used via TypeDoc configuration without direct imports:

{
  "plugin": ["typedoc-plugin-markdown"],
  "markdown": "./docs"
}

Basic Usage

CLI Usage (Most Common):

# Install TypeDoc and the plugin
npm install --save-dev typedoc typedoc-plugin-markdown

# Generate markdown documentation
npx typedoc --plugin typedoc-plugin-markdown --markdown ./docs src/**/*.ts

Configuration File Usage:

// typedoc.json
{
  "plugin": ["typedoc-plugin-markdown"],
  "markdown": "./docs",
  "entryPoints": ["src/**/*.ts"],
  "fileExtension": ".md",
  "useCodeBlocks": true
}

Programmatic Usage:

import { Application } from "typedoc";
import { load } from "typedoc-plugin-markdown";

// Bootstrap the plugin with TypeDoc
const app = new Application();
load(app);

// Configure for markdown output
app.options.setValue('plugin', ['typedoc-plugin-markdown']);
app.options.setValue('markdown', './docs');

// Generate documentation
const project = app.converter.convert([
  app.expandInputFiles(['src/**/*.ts'])
]);

if (project) {
  await app.generateDocs(project, './docs');
}

Architecture

TypeDoc Plugin Markdown is built around several key components:

  • Plugin Bootstrap: The load() function integrates with TypeDoc's plugin system, adding markdown-specific options and output handlers
  • Theme System: MarkdownTheme and MarkdownThemeContext control how TypeDoc models are mapped to files and rendered as markdown
  • Router System: Multiple router implementations (MemberRouter, ModuleRouter) provide different file organization strategies
  • Event System: MarkdownPageEvent and MarkdownRendererEvent enable hooking into the rendering lifecycle
  • Customization Framework: Comprehensive options system with 66+ configuration settings for controlling output format and behavior

Capabilities

Plugin Bootstrap

Core plugin initialization that integrates with TypeDoc's application lifecycle, adding markdown output capabilities and configuration options.

/**
 * The function that is called by TypeDoc to bootstrap the plugin.
 * Exposes additional TypeDoc options and makes adjustments for markdown output.
 */
function load(app: Application): void;

Plugin Bootstrap

Theme System

Custom theme implementation that controls how TypeDoc models are rendered as markdown files, with complete customization support and navigation building.

class MarkdownTheme extends Theme {
  constructor(renderer: Renderer);
  render(page: MarkdownPageEvent): string;
  getNavigation(project: ProjectReflection): NavigationItem[];
}

class MarkdownThemeContext {
  readonly theme: MarkdownTheme;
  readonly page: MarkdownPageEvent<Reflection>;
  readonly options: Options;
  templates: any;
  partials: any;
  helpers: any;
}

class NavigationBuilder {
  constructor(router: Router, theme: MarkdownTheme, project: ProjectReflection);
  getNavigation(): NavigationItem[];
}

Theme System

Routing and File Organization

Multiple router implementations providing different strategies for organizing generated documentation files, built on the MarkdownRouter base class.

abstract class MarkdownRouter extends BaseRouter {
  abstract buildChildPages(reflection: Reflection, outPages: PageDefinition[]): void;
  abstract getIdealBaseName(reflection: Reflection): string;
  buildPages(project: ProjectReflection): PageDefinition[];
  getAnchor(target: RouterTarget): string;
}

class MemberRouter extends MarkdownRouter {
  buildChildPages(reflection: Reflection, outPages: PageDefinition[]): void;
  getIdealBaseName(reflection: Reflection): string;
}

class ModuleRouter extends MarkdownRouter {
  buildChildPages(reflection: Reflection, outPages: PageDefinition[]): void;
  getIdealBaseName(reflection: Reflection): string;
}

Routing System

Events and Lifecycle Hooks

Event system for hooking into the markdown generation lifecycle, enabling customization at various rendering stages.

class MarkdownPageEvent<out Model extends RouterTarget = RouterTarget> {
  readonly model: Model;
  project: ProjectReflection;
  filename: string;
  url: string;
  contents: string;
  static readonly BEGIN = 'beginPage';
  static readonly END = 'endPage';
}

class MarkdownRendererEvent {
  readonly project: ProjectReflection;
  readonly outputDirectory: string;
  pages: PageDefinition[];
  navigation?: NavigationItem[];
  static readonly BEGIN = 'beginRender';
  static readonly END = 'endRender';
}

Events and Hooks

Configuration Options

Comprehensive configuration system with 66+ options for customizing markdown output, file organization, and formatting.

interface PluginOptions {
  anchorPrefix?: string;
  fileExtension?: string;
  entryFileName?: string;
  modulesFileName?: string;
  flattenOutputFiles?: boolean;
  hidePageHeader?: boolean;
  hidePageTitle?: boolean;
  hideBreadcrumbs?: boolean;
  mergeReadme?: boolean;
  useCodeBlocks?: boolean;
  useHTMLAnchors?: boolean;
  membersWithOwnFile?: Array<string>;
  indexFormat?: 'list' | 'table' | 'htmlTable';
  interfacePropertiesFormat?: 'list' | 'table' | 'htmlTable';
  classPropertiesFormat?: 'list' | 'table' | 'htmlTable';
  enumMembersFormat?: 'list' | 'table' | 'htmlTable';
  parametersFormat?: 'list' | 'table' | 'htmlTable';
  // ... 50+ more configuration options
}

Configuration Options

Types

Core Application Types

interface MarkdownApplication extends Application {
  renderer: MarkdownRenderer & Renderer;
}

interface MarkdownRenderer extends Renderer {
  markdownHooks: EventHooks<MarkdownRendererHooks, string>;
  preRenderAsyncJobs: Array<(output: MarkdownRendererEvent) => Promise<void>>;
  postRenderAsyncJobs: Array<(output: MarkdownRendererEvent) => Promise<void>>;
  packagesMeta: Record<string, PackageMetaData>;
}

Navigation and Theme Types

interface NavigationItem {
  title: string;
  path?: string | null;
  kind?: ReflectionKind;
  isDeprecated?: boolean;
  children?: NavigationItem[];
}

interface PackageMetaData {
  description: string;
  options: Options;
}

type RenderTemplate<T> = (data: T) => string;
type MemberSection = ReflectionGroup | ReflectionCategory;

Hook System Types

interface MarkdownRendererHooks {
  ['page.begin']: [MarkdownThemeContext];
  ['page.end']: [MarkdownThemeContext];
  ['content.begin']: [MarkdownThemeContext];
  ['index.page.begin']: [MarkdownThemeContext];
  ['index.page.end']: [MarkdownThemeContext];
}