0
# Documentation Generators
1

2
Direct library access to API Documenter's documentation generation classes for programmatic use. These classes provide the core functionality for generating documentation from API Extractor models without using the CLI interface.
3

4
## Capabilities
5

6
### MarkdownDocumenter
7

8
Core markdown documentation generator that processes API models and outputs markdown files.
9

10
```typescript { .api }
11
class MarkdownDocumenter {
12
  /**
13
   * Creates a new MarkdownDocumenter instance
14
   * @param options - Configuration options for the documenter
15
   */
16
  constructor(options: IMarkdownDocumenterOptions);
17
  
18
  /**
19
   * Generates all markdown documentation files
20
   */
21
  generateFiles(): void;
22
}
23

24
interface IMarkdownDocumenterOptions {
25
  /**
26
   * The API model containing the API items to document
27
   */
28
  apiModel: ApiModel;
29
  
30
  /**
31
   * Optional configuration for customizing output
32
   */
33
  documenterConfig: DocumenterConfig | undefined;
34
  
35
  /**
36
   * Output folder path where markdown files will be written
37
   */
38
  outputFolder: string;
39
}
40
```
41

42
**Usage Example:**
43

44
```typescript
45
import { ApiModel } from "@microsoft/api-extractor-model";
46
import { MarkdownDocumenter, IMarkdownDocumenterOptions } from "@microsoft/api-documenter/lib/documenters/MarkdownDocumenter";
47
import { DocumenterConfig } from "@microsoft/api-documenter/lib/documenters/DocumenterConfig";
48

49
// Load API model from API Extractor files
50
const apiModel = new ApiModel();
51
apiModel.loadPackage('./temp/my-package.api.json');
52

53
// Generate markdown documentation
54
const markdownDocumenter = new MarkdownDocumenter({
55
  apiModel,
56
  outputFolder: './docs'
57
});
58

59
markdownDocumenter.generateFiles();
60
```
61

62
### YamlDocumenter
63

64
Base YAML documentation generator for creating DocFX-compatible YAML files.
65

66
```typescript { .api }
67
class YamlDocumenter {
68
  /**
69
   * Creates a new YamlDocumenter instance
70
   * @param apiModel - The API model containing the API items to document
71
   * @param newDocfxNamespaces - Optional flag to enable new DocFX namespace support
72
   * @param yamlFormat - Optional YAML format ('udp' or 'sdp', defaults to 'sdp')
73
   */
74
  constructor(
75
    apiModel: ApiModel,
76
    newDocfxNamespaces?: boolean,
77
    yamlFormat?: YamlFormat
78
  );
79
  
80
  /**
81
   * Generates all YAML documentation files
82
   * @param outputFolder - Output folder path where YAML files will be written
83
   */
84
  generateFiles(outputFolder: string): void;
85
}
86

87
type YamlFormat = 'udp' | 'sdp';
88
```
89

90
### OfficeYamlDocumenter
91

92
Specialized YAML documenter for Office Add-ins with Office-specific features and formatting.
93

94
```typescript { .api }
95
class OfficeYamlDocumenter extends YamlDocumenter {
96
  /**
97
   * Creates a new OfficeYamlDocumenter instance
98
   * @param apiModel - The API model containing the API items to document
99
   * @param inputFolder - Input folder path containing snippets and other resources
100
   * @param newDocfxNamespaces - Optional flag to enable new DocFX namespace support
101
   */
102
  constructor(
103
    apiModel: ApiModel,
104
    inputFolder: string,
105
    newDocfxNamespaces?: boolean
106
  );
107
}
108
```
109

110
**Usage Example:**
111

112
```typescript
113
import { ApiModel } from "@microsoft/api-extractor-model";
114
import { OfficeYamlDocumenter } from "@microsoft/api-documenter/lib/documenters/OfficeYamlDocumenter";
115

116
const apiModel = new ApiModel();
117
apiModel.loadPackage('./temp/office-addin.api.json');
118

119
const yamlDocumenter = new OfficeYamlDocumenter(
120
  apiModel,
121
  './input', // folder containing snippets.yaml
122
  false // newDocfxNamespaces
123
);
124

125
yamlDocumenter.generateFiles('./yaml-docs');
126
```
127

128
### ExperimentalYamlDocumenter
129

130
Experimental YAML documenter with configuration file support for advanced customization.
131

132
```typescript { .api }
133
class ExperimentalYamlDocumenter extends YamlDocumenter {
134
  /**
135
   * Creates a new ExperimentalYamlDocumenter instance
136
   * @param apiModel - The API model containing the API items to document
137
   * @param newDocfxNamespaces - Optional flag to enable new DocFX namespace support
138
   * @param yamlFormat - Optional YAML format ('udp' or 'sdp', defaults to 'sdp')
139
   */
140
  constructor(
141
    apiModel: ApiModel,
142
    newDocfxNamespaces?: boolean,
143
    yamlFormat?: YamlFormat
144
  );
145
}
146
```
147

148
### DocumenterConfig
149

150
Configuration loader and validator for documenter settings.
151

152
```typescript { .api }
153
class DocumenterConfig {
154
  /**
155
   * Loads configuration from api-documenter.json file
156
   * @param configFilePath - Path to the configuration file
157
   * @returns Loaded configuration object
158
   */
159
  static loadFile(configFilePath: string): DocumenterConfig;
160
  
161
  /**
162
   * Configuration settings loaded from file
163
   */
164
  readonly configFile: IConfigFile;
165
}
166

167
interface IConfigFile {
168
  /**
169
   * Configuration format version
170
   */
171
  configFormatVersion: string;
172
  
173
  /**
174
   * Output targets configuration
175
   */
176
  outputTargets?: IConfigOutputTarget[];
177
  
178
  /**
179
   * Newline character setting
180
   */
181
  newlineKind?: 'crlf' | 'lf';
182
  
183
  /**
184
   * Plugin configurations
185
   */
186
  plugins?: IConfigPlugin[];
187
  
188
  /**
189
   * Table of contents configuration
190
   */
191
  tableOfContents?: IConfigTableOfContents;
192
}
193

194
interface IConfigPlugin {
195
  /**
196
   * NPM package name of the plugin
197
   */
198
  packageName: string;
199
  
200
  /**
201
   * Whether the plugin is enabled
202
   */
203
  enabled: boolean;
204
  
205
  /**
206
   * Plugin-specific options
207
   */
208
  options?: Record<string, any>;
209
}
210

211
interface IConfigTableOfContents {
212
  /**
213
   * Category name for uncategorized API items
214
   */
215
  catchAllCategory?: string;
216
}
217
```
218

219
**Configuration Example:**
220

221
```typescript
222
import { DocumenterConfig, IConfigFile, IConfigPlugin, IConfigTableOfContents } from "@microsoft/api-documenter/lib/documenters/DocumenterConfig";
223

224
// Load configuration from file
225
const config = DocumenterConfig.loadFile('./api-documenter.json');
226

227
// Use config with documenter
228
const markdownDocumenter = new MarkdownDocumenter({
229
  apiModel,
230
  documenterConfig: config,
231
  outputFolder: './docs'
232
});
233
```
234

235
## Advanced Usage
236

237
### Custom Markdown Processing
238

239
```typescript
240
import { ApiModel } from "@microsoft/api-extractor-model";
241
import { 
242
  MarkdownDocumenter,
243
  CustomMarkdownEmitter 
244
} from "@microsoft/api-documenter/lib/documenters/MarkdownDocumenter";
245
import { 
246
  CustomDocNodes 
247
} from "@microsoft/api-documenter/lib/nodes/CustomDocNodes";
248
import { DocHeading } from "@microsoft/api-documenter/lib/nodes/DocHeading";
249

250
// Create custom markdown emitter with enhanced formatting
251
class EnhancedMarkdownEmitter extends CustomMarkdownEmitter {
252
  protected writeHeading(docHeading: DocHeading): void {
253
    // Custom heading formatting
254
    const level = Math.min(docHeading.level, 6);
255
    this.writeNewline();
256
    this.writePlainText('#'.repeat(level) + ' ' + docHeading.title);
257
    this.writeNewline();
258
  }
259
}
260

261
// Use custom emitter with documenter
262
const apiModel = new ApiModel();
263
const documenter = new MarkdownDocumenter({
264
  apiModel,
265
  outputFolder: './docs'
266
});
267
```
268

269
### Batch Processing Multiple Packages
270

271
```typescript
272
import { ApiModel } from "@microsoft/api-extractor-model";
273
import { MarkdownDocumenter, IMarkdownDocumenterOptions } from "@microsoft/api-documenter/lib/documenters/MarkdownDocumenter";
274
import * as path from "path";
275

276
// Process multiple API packages
277
const packages = [
278
  './temp/package-a.api.json',
279
  './temp/package-b.api.json',
280
  './temp/package-c.api.json'
281
];
282

283
const apiModel = new ApiModel();
284

285
// Load all packages into single model
286
for (const packagePath of packages) {
287
  apiModel.loadPackage(packagePath);
288
}
289

290
// Generate combined documentation
291
const documenter = new MarkdownDocumenter({
292
  apiModel,
293
  outputFolder: './combined-docs'
294
});
295

296
documenter.generateFiles();
297
```
298

299
### YAML Format Selection
300

301
```typescript
302
import { YamlFormat } from "@microsoft/api-documenter/lib/documenters/YamlDocumenter";
303

304
// Available YAML formats
305
type YamlFormat = 'udp' | 'sdp';
306

307
// UDP format: Legacy Universal DocFX Platform format
308
// SDP format: Structured Data Platform format (default, recommended)
309
```
310

311
## Utility Classes
312

313
### IndentedWriter
314

315
Text writer utility with configurable indentation for generating formatted output.
316

317
```typescript { .api }
318
class IndentedWriter {
319
  /**
320
   * Creates a new IndentedWriter instance
321
   * @param builder - StringBuilder to write to
322
   * @param defaultIndentPrefix - Default indentation string (default: two spaces)
323
   */
324
  constructor(builder: StringBuilder, defaultIndentPrefix?: string);
325
  
326
  /**
327
   * Writes text without indentation
328
   * @param text - Text to write
329
   */
330
  write(text: string): void;
331
  
332
  /**
333
   * Writes text with current indentation
334
   * @param text - Text to write
335
   */
336
  writeLine(text?: string): void;
337
  
338
  /**
339
   * Increases indentation level
340
   */
341
  increaseIndent(): void;
342
  
343
  /**
344
   * Decreases indentation level
345
   */
346
  decreaseIndent(): void;
347
}
348
```
349

350
### Utilities
351

352
Static utility methods for documentation generation.
353

354
```typescript { .api }
355
class Utilities {
356
  /**
357
   * Generates a safe filename from an API item display name
358
   * @param name - The display name to convert
359
   * @returns Safe filename string
360
   */
361
  static getSafeFilenameForName(name: string): string;
362
  
363
  /**
364
   * Concatenates signature parts into a readable format
365
   * @param parts - Array of signature parts
366
   * @returns Formatted signature string
367
   */
368
  static getConciseSignature(parts: string[]): string;
369
}
370
```
371

372
## Error Handling
373

374
The documenter classes handle various error conditions:
375

376
- **Invalid API Models**: Clear error messages when API models are corrupted or incomplete
377
- **File System Errors**: Detailed information about write permission and disk space issues
378
- **Configuration Errors**: Validation messages for malformed configuration files
379
- **Plugin Loading Errors**: Specific error information when plugins fail to initialize
380
- **Template Processing Errors**: Context-aware messages when template processing fails