or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdcustom-nodes.mddocumenters.mdindex.mdplugin-system.mdyaml-types.md
tile.json

tessl/npm-microsoft--api-documenter

Reads API Extractor JSON files and generates API documentation in various output formats

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@microsoft/api-documenter@7.26.x

To install, run

npx @tessl/cli install tessl/npm-microsoft--api-documenter@7.26.0

index.mddocs/

API Documenter

API Documenter is a versatile tool that generates comprehensive API documentation from TypeScript projects by processing *.api.json files produced by API Extractor. It provides both a command-line interface for generating documentation and a plugin API for customizing the output, making it essential for creating professional API reference websites and documentation portals.

Package Information

  • Package Name: @microsoft/api-documenter
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @microsoft/api-documenter

Core Imports

Plugin Development:

import {
  MarkdownDocumenterFeature,
  MarkdownDocumenterAccessor,
  IApiDocumenterPluginManifest,
  IFeatureDefinition
} from "@microsoft/api-documenter";

Direct Library Usage:

import { ApiDocumenterCommandLine } from "@microsoft/api-documenter/lib/cli/ApiDocumenterCommandLine";
import { MarkdownDocumenter } from "@microsoft/api-documenter/lib/documenters/MarkdownDocumenter";

Basic Usage

Command Line Usage:

# Generate markdown documentation
api-documenter markdown --input-folder ./temp --output-folder ./docs

# Generate YAML documentation for DocFX
api-documenter yaml --input-folder ./temp --output-folder ./yaml-docs --new-docfx-namespaces

# Experimental config-driven generation
api-documenter generate --input-folder ./temp --output-folder ./docs

Plugin Development:

import { 
  MarkdownDocumenterFeature,
  IApiDocumenterPluginManifest,
  IMarkdownDocumenterFeatureOnBeforeWritePageArgs
} from "@microsoft/api-documenter";

class CustomMarkdownFeature extends MarkdownDocumenterFeature {
  public onBeforeWritePage(eventArgs: IMarkdownDocumenterFeatureOnBeforeWritePageArgs): void {
    // Customize page content before writing
    eventArgs.pageContent = eventArgs.pageContent.replace(
      /## Remarks/g, 
      "## 📝 Important Notes"
    );
  }
}

export const apiDocumenterPluginManifest: IApiDocumenterPluginManifest = {
  manifestVersion: 1000,
  features: [
    {
      featureName: 'custom-markdown',
      kind: 'MarkdownDocumenterFeature',
      subclass: CustomMarkdownFeature
    }
  ]
};

Architecture

API Documenter is built around several key components:

  • CLI Interface: Command-line actions for different output formats (markdown, yaml, config-driven)
  • Documenter Classes: Core documentation generators (MarkdownDocumenter, YamlDocumenter, etc.)
  • Plugin System: Extensible architecture for customizing documentation output
  • Custom Doc Nodes: Enhanced TSDoc node system for rich documentation markup
  • YAML Generators: Specialized generators for DocFX and Office Add-ins documentation

Capabilities

Command Line Interface

Complete command-line tool for generating API documentation from API Extractor files. Supports markdown, YAML, and experimental config-driven generation modes.

# Primary CLI actions
api-documenter markdown --input-folder <path> --output-folder <path>
api-documenter yaml --input-folder <path> --output-folder <path> [--office] [--new-docfx-namespaces]
api-documenter generate --input-folder <path> --output-folder <path>

Command Line Interface

Plugin Development System

Extensible plugin architecture for customizing markdown documentation generation. Enables custom page processing, content modification, and integration with external tools.

interface IApiDocumenterPluginManifest {
  manifestVersion: 1000;
  features: IFeatureDefinition[];
}

interface IFeatureDefinition {
  featureName: string;
  kind: 'MarkdownDocumenterFeature';
  subclass: { new (initialization: PluginFeatureInitialization): MarkdownDocumenterFeature };
}

class MarkdownDocumenterFeature extends PluginFeature {
  onInitialized(): void;
  onBeforeWritePage(eventArgs: IMarkdownDocumenterFeatureOnBeforeWritePageArgs): void;
  onFinished(eventArgs: IMarkdownDocumenterFeatureOnFinishedArgs): void;
}

Plugin Development

Documentation Generators

Direct library access to documentation generation classes for programmatic use. Includes markdown and YAML generators with configuration support.

class MarkdownDocumenter {
  constructor(options: IMarkdownDocumenterOptions);
  generateFiles(): void;
}

class YamlDocumenter {
  constructor(options: IYamlDocumenterOptions);  
  generateFiles(): void;
}

interface IMarkdownDocumenterOptions {
  apiModel: ApiModel;
  documenterConfig?: DocumenterConfig;
  outputFolder: string;
}

Documentation Generators

Custom Doc Nodes

Enhanced TSDoc node system with specialized elements for rich documentation markup including tables, headings, and custom formatting.

enum CustomDocNodeKind {
  EmphasisSpan = 'EmphasisSpan';
  Heading = 'Heading';
  NoteBox = 'NoteBox';
  Table = 'Table';
  TableCell = 'TableCell';
  TableRow = 'TableRow';
}

class DocHeading extends DocNode {
  readonly title: string;
  readonly level: number;
  constructor(parameters: IDocHeadingParameters);
}

class DocTable extends DocNode {
  constructor(parameters: IDocTableParameters);
  createAndAddRow(): DocTableRow;
}

Custom Doc Nodes

YAML Type Definitions

Comprehensive type system for generating YAML documentation compatible with DocFX and Office Add-ins platforms.

type YamlFormat = 'udp' | 'sdp';

interface IYamlApiFile {
  items: IYamlItem[];
  references?: IYamlReference[];
  metadata?: object;
}

interface IYamlItem {
  uid: string;
  name: string;
  type: YamlTypeId;
  summary?: string;
  syntax?: IYamlSyntax;
}

YAML Type Definitions

Types

interface IMarkdownDocumenterFeatureOnBeforeWritePageArgs {
  readonly apiItem: ApiItem;
  pageContent: string;
  readonly outputFilename: string;
}

interface IMarkdownDocumenterFeatureOnFinishedArgs {}

class MarkdownDocumenterFeatureContext {
  readonly apiModel: ApiModel;
  readonly outputFolder: string;
  readonly documenter: MarkdownDocumenterAccessor;
}

class MarkdownDocumenterAccessor {
  getLinkForApiItem(apiItem: ApiItem): string | undefined;
}

class PluginFeatureInitialization {
  constructor();
}

abstract class PluginFeature {
  context: PluginFeatureContext;
  constructor(initialization: PluginFeatureInitialization);
  onInitialized(): void;
}

class PluginFeatureContext {}

/**
 * Configuration file interface for API Documenter
 */
interface IConfigFile {
  /**
   * Specifies the output target ('docfx' or 'markdown')
   */
  outputTarget: 'docfx' | 'markdown';
  
  /**
   * Newline character setting ('crlf', 'lf', or 'os')
   */
  newlineKind?: 'crlf' | 'lf' | 'os';
  
  /**
   * Enable new DocFX namespace support
   */
  newDocfxNamespaces?: boolean;
  
  /**
   * Plugin configurations
   */
  plugins?: IConfigPlugin[];
  
  /**
   * Table of contents configuration
   */
  tableOfContents?: IConfigTableOfContents;
  
  /**
   * Show inherited members on API item pages
   */
  showInheritedMembers?: boolean;
}

/**
 * Plugin configuration interface
 */
interface IConfigPlugin {
  /**
   * NPM package name of the plugin
   */
  packageName: string;
  
  /**
   * List of enabled feature names
   */
  enabledFeatureNames: string[];
}

/**
 * Table of contents configuration interface
 */
interface IConfigTableOfContents {
  /**
   * Table of contents structure configuration
   */
  tocConfig: IYamlTocFile;
  
  /**
   * Category name for uncategorized API items
   */
  catchAllCategory?: string;
  
  /**
   * Enable categorization by API item name
   */
  categorizeByName?: boolean;
  
  /**
   * Inline tag for categorizing API items
   */
  categoryInlineTag?: string;
  
  /**
   * Node names that should be treated as category nodes
   */
  nonEmptyCategoryNodeNames?: string[];
}