CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-microsoft--api-documenter

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

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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[];
}
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@microsoft/api-documenter@7.26.x
Publish Source
CLI
Badge
tessl/npm-microsoft--api-documenter badge