tessl/npm-typedoc-plugin-markdown

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

TypeDoc Plugin Markdown

Name: tessl/npm-typedoc-plugin-markdown
Author: tessl

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];
}