0
# API Documenter
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @microsoft/api-documenter
7
- **Package Type**: npm  
8
- **Language**: TypeScript
9
- **Installation**: `npm install @microsoft/api-documenter`
10

11
## Core Imports
12

13
**Plugin Development:**
14

15
```typescript
16
import {
17
  MarkdownDocumenterFeature,
18
  MarkdownDocumenterAccessor,
19
  IApiDocumenterPluginManifest,
20
  IFeatureDefinition
21
} from "@microsoft/api-documenter";
22
```
23

24
**Direct Library Usage:**
25

26
```typescript 
27
import { ApiDocumenterCommandLine } from "@microsoft/api-documenter/lib/cli/ApiDocumenterCommandLine";
28
import { MarkdownDocumenter } from "@microsoft/api-documenter/lib/documenters/MarkdownDocumenter";
29
```
30

31
## Basic Usage
32

33
**Command Line Usage:**
34

35
```bash
36
# Generate markdown documentation
37
api-documenter markdown --input-folder ./temp --output-folder ./docs
38

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

42
# Experimental config-driven generation
43
api-documenter generate --input-folder ./temp --output-folder ./docs
44
```
45

46
**Plugin Development:**
47

48
```typescript
49
import { 
50
  MarkdownDocumenterFeature,
51
  IApiDocumenterPluginManifest,
52
  IMarkdownDocumenterFeatureOnBeforeWritePageArgs
53
} from "@microsoft/api-documenter";
54

55
class CustomMarkdownFeature extends MarkdownDocumenterFeature {
56
  public onBeforeWritePage(eventArgs: IMarkdownDocumenterFeatureOnBeforeWritePageArgs): void {
57
    // Customize page content before writing
58
    eventArgs.pageContent = eventArgs.pageContent.replace(
59
      /## Remarks/g, 
60
      "## 📝 Important Notes"
61
    );
62
  }
63
}
64

65
export const apiDocumenterPluginManifest: IApiDocumenterPluginManifest = {
66
  manifestVersion: 1000,
67
  features: [
68
    {
69
      featureName: 'custom-markdown',
70
      kind: 'MarkdownDocumenterFeature',
71
      subclass: CustomMarkdownFeature
72
    }
73
  ]
74
};
75
```
76

77
## Architecture
78

79
API Documenter is built around several key components:
80

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

87
## Capabilities
88

89
### Command Line Interface
90

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

93
```bash { .api }
94
# Primary CLI actions
95
api-documenter markdown --input-folder <path> --output-folder <path>
96
api-documenter yaml --input-folder <path> --output-folder <path> [--office] [--new-docfx-namespaces]
97
api-documenter generate --input-folder <path> --output-folder <path>
98
```
99

100
[Command Line Interface](./cli.md)
101

102
### Plugin Development System
103

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

106
```typescript { .api }
107
interface IApiDocumenterPluginManifest {
108
  manifestVersion: 1000;
109
  features: IFeatureDefinition[];
110
}
111

112
interface IFeatureDefinition {
113
  featureName: string;
114
  kind: 'MarkdownDocumenterFeature';
115
  subclass: { new (initialization: PluginFeatureInitialization): MarkdownDocumenterFeature };
116
}
117

118
class MarkdownDocumenterFeature extends PluginFeature {
119
  onInitialized(): void;
120
  onBeforeWritePage(eventArgs: IMarkdownDocumenterFeatureOnBeforeWritePageArgs): void;
121
  onFinished(eventArgs: IMarkdownDocumenterFeatureOnFinishedArgs): void;
122
}
123
```
124

125
[Plugin Development](./plugin-system.md)
126

127
### Documentation Generators
128

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

131
```typescript { .api }
132
class MarkdownDocumenter {
133
  constructor(options: IMarkdownDocumenterOptions);
134
  generateFiles(): void;
135
}
136

137
class YamlDocumenter {
138
  constructor(options: IYamlDocumenterOptions);  
139
  generateFiles(): void;
140
}
141

142
interface IMarkdownDocumenterOptions {
143
  apiModel: ApiModel;
144
  documenterConfig?: DocumenterConfig;
145
  outputFolder: string;
146
}
147
```
148

149
[Documentation Generators](./documenters.md)
150

151
### Custom Doc Nodes
152

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

155
```typescript { .api }
156
enum CustomDocNodeKind {
157
  EmphasisSpan = 'EmphasisSpan';
158
  Heading = 'Heading';
159
  NoteBox = 'NoteBox';
160
  Table = 'Table';
161
  TableCell = 'TableCell';
162
  TableRow = 'TableRow';
163
}
164

165
class DocHeading extends DocNode {
166
  readonly title: string;
167
  readonly level: number;
168
  constructor(parameters: IDocHeadingParameters);
169
}
170

171
class DocTable extends DocNode {
172
  constructor(parameters: IDocTableParameters);
173
  createAndAddRow(): DocTableRow;
174
}
175
```
176

177
[Custom Doc Nodes](./custom-nodes.md)
178

179
### YAML Type Definitions
180

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

183
```typescript { .api }
184
type YamlFormat = 'udp' | 'sdp';
185

186
interface IYamlApiFile {
187
  items: IYamlItem[];
188
  references?: IYamlReference[];
189
  metadata?: object;
190
}
191

192
interface IYamlItem {
193
  uid: string;
194
  name: string;
195
  type: YamlTypeId;
196
  summary?: string;
197
  syntax?: IYamlSyntax;
198
}
199
```
200

201
[YAML Type Definitions](./yaml-types.md)
202

203
## Types
204

205
```typescript { .api }
206
interface IMarkdownDocumenterFeatureOnBeforeWritePageArgs {
207
  readonly apiItem: ApiItem;
208
  pageContent: string;
209
  readonly outputFilename: string;
210
}
211

212
interface IMarkdownDocumenterFeatureOnFinishedArgs {}
213

214
class MarkdownDocumenterFeatureContext {
215
  readonly apiModel: ApiModel;
216
  readonly outputFolder: string;
217
  readonly documenter: MarkdownDocumenterAccessor;
218
}
219

220
class MarkdownDocumenterAccessor {
221
  getLinkForApiItem(apiItem: ApiItem): string | undefined;
222
}
223

224
class PluginFeatureInitialization {
225
  constructor();
226
}
227

228
abstract class PluginFeature {
229
  context: PluginFeatureContext;
230
  constructor(initialization: PluginFeatureInitialization);
231
  onInitialized(): void;
232
}
233

234
class PluginFeatureContext {}
235

236
/**
237
 * Configuration file interface for API Documenter
238
 */
239
interface IConfigFile {
240
  /**
241
   * Specifies the output target ('docfx' or 'markdown')
242
   */
243
  outputTarget: 'docfx' | 'markdown';
244
  
245
  /**
246
   * Newline character setting ('crlf', 'lf', or 'os')
247
   */
248
  newlineKind?: 'crlf' | 'lf' | 'os';
249
  
250
  /**
251
   * Enable new DocFX namespace support
252
   */
253
  newDocfxNamespaces?: boolean;
254
  
255
  /**
256
   * Plugin configurations
257
   */
258
  plugins?: IConfigPlugin[];
259
  
260
  /**
261
   * Table of contents configuration
262
   */
263
  tableOfContents?: IConfigTableOfContents;
264
  
265
  /**
266
   * Show inherited members on API item pages
267
   */
268
  showInheritedMembers?: boolean;
269
}
270

271
/**
272
 * Plugin configuration interface
273
 */
274
interface IConfigPlugin {
275
  /**
276
   * NPM package name of the plugin
277
   */
278
  packageName: string;
279
  
280
  /**
281
   * List of enabled feature names
282
   */
283
  enabledFeatureNames: string[];
284
}
285

286
/**
287
 * Table of contents configuration interface
288
 */
289
interface IConfigTableOfContents {
290
  /**
291
   * Table of contents structure configuration
292
   */
293
  tocConfig: IYamlTocFile;
294
  
295
  /**
296
   * Category name for uncategorized API items
297
   */
298
  catchAllCategory?: string;
299
  
300
  /**
301
   * Enable categorization by API item name
302
   */
303
  categorizeByName?: boolean;
304
  
305
  /**
306
   * Inline tag for categorizing API items
307
   */
308
  categoryInlineTag?: string;
309
  
310
  /**
311
   * Node names that should be treated as category nodes
312
   */
313
  nonEmptyCategoryNodeNames?: string[];
314
}
315
```