0
# Configuration System
1

2
Comprehensive configuration management supporting multiple option sources, type-safe declarations, validation, and flexible option readers for all TypeDoc settings.
3

4
## Capabilities
5

6
### Options Container
7

8
Main container for all TypeDoc configuration options with type-safe access and validation.
9

10
```typescript { .api }
11
/**
12
 * Container for all TypeDoc configuration options with type-safe access
13
 */
14
class Options extends EventDispatcher<OptionsEvents, EventsWithArgument> {
15
  /**
16
   * Add a new option declaration
17
   * @param declaration - Option declaration to add
18
   */
19
  addDeclaration(declaration: DeclarationOption): void;
20
  
21
  /**
22
   * Get the value of a configuration option
23
   * @param name - Option name
24
   * @returns Current option value
25
   */
26
  getValue<K extends keyof TypeDocOptions>(name: K): TypeDocOptions[K];
27
  
28
  /**
29
   * Set the value of a configuration option
30
   * @param name - Option name  
31
   * @param value - New option value
32
   */
33
  setValue<K extends keyof TypeDocOptions>(name: K, value: TypeDocOptions[K]): void;
34
  
35
  /**
36
   * Check if an option has been explicitly set
37
   * @param name - Option name
38
   * @returns True if option was set by user
39
   */
40
  isSet(name: keyof TypeDocOptions): boolean;
41
  
42
  /**
43
   * Read configuration from all registered readers
44
   * @param logger - Logger for error reporting
45
   */
46
  read(logger: Logger): void;
47
  
48
  /**
49
   * Get all option declarations
50
   * @returns Array of all registered option declarations
51
   */
52
  getDeclarations(): DeclarationOption[];
53
  
54
  /**
55
   * Get declaration for specific option
56
   * @param name - Option name
57
   * @returns Option declaration or undefined
58
   */
59
  getDeclaration(name: string): DeclarationOption | undefined;
60
  
61
  /**
62
   * Add an option reader
63
   * @param reader - Reader to add
64
   */
65
  addReader(reader: OptionsReader): void;
66
  
67
  /**
68
   * Remove an option reader
69
   * @param reader - Reader to remove
70
   */
71
  removeReader(reader: OptionsReader): void;
72
  
73
  /**
74
   * Freeze the options container (prevent further changes)
75
   */
76
  freeze(): void;
77
}
78
```
79

80
**Usage Examples:**
81

82
```typescript
83
import { Application, Options, ParameterType } from "typedoc";
84

85
const app = await Application.bootstrap();
86
const options = app.options;
87

88
// Get option values
89
const entryPoints = options.getValue("entryPoints");
90
const outputDir = options.getValue("out");
91
const theme = options.getValue("theme");
92

93
// Set option values
94
options.setValue("out", "dist/docs");
95
options.setValue("theme", "default");
96
options.setValue("excludeExternals", true);
97

98
// Check if option was set
99
if (options.isSet("json")) {
100
  console.log("JSON output was explicitly configured");
101
}
102

103
// Add custom option declaration
104
options.addDeclaration({
105
  name: "customPlugin",
106
  help: "Enable custom plugin functionality",
107
  type: ParameterType.Boolean,
108
  defaultValue: false,
109
});
110

111
// Read all configuration sources
112
options.read(app.logger);
113
```
114

115
### Option Readers
116

117
Components that read configuration from various sources like CLI arguments, config files, and package.json.
118

119
```typescript { .api }
120
/**
121
 * Base interface for option readers
122
 */
123
interface OptionsReader {
124
  /** Reader priority (higher numbers read later) */
125
  readonly priority: number;
126
  /** Whether reader should process unknown options */
127
  readonly unknownOptionNames?: string[];
128
  
129
  /**
130
   * Read options from source
131
   * @param container - Options container to populate
132
   * @param logger - Logger for error reporting
133
   * @param cwd - Current working directory
134
   */
135
  read(container: Options, logger: Logger, cwd: string): void;
136
}
137

138
/**
139
 * Reads options from command line arguments
140
 */
141
class ArgumentsReader implements OptionsReader {
142
  readonly priority: number;
143
  
144
  /**
145
   * Create arguments reader
146
   * @param priority - Reader priority
147
   */
148
  constructor(priority: number);
149
  
150
  /**
151
   * Ignore errors during reading (for secondary passes)
152
   * @returns New reader that ignores errors
153
   */
154
  ignoreErrors(): ArgumentsReader;
155
  
156
  read(container: Options, logger: Logger, cwd: string): void;
157
}
158

159
/**
160
 * Reads options from TypeDoc configuration files
161
 */
162
class TypeDocReader implements OptionsReader {
163
  readonly priority: number;
164
  
165
  read(container: Options, logger: Logger, cwd: string): void;
166
}
167

168
/**
169
 * Reads options from package.json typedocOptions field
170
 */
171
class PackageJsonReader implements OptionsReader {
172
  readonly priority: number;
173
  
174
  read(container: Options, logger: Logger, cwd: string): void;
175
}
176

177
/**
178
 * Reads options from tsconfig.json typedocOptions field
179
 */
180
class TSConfigReader implements OptionsReader {
181
  readonly priority: number;
182
  
183
  read(container: Options, logger: Logger, cwd: string): void;
184
}
185
```
186

187
**Usage Examples:**
188

189
```typescript
190
import { 
191
  Application, 
192
  ArgumentsReader, 
193
  TypeDocReader, 
194
  TSConfigReader, 
195
  PackageJsonReader 
196
} from "typedoc";
197

198
// Bootstrap with custom reader configuration
199
const app = await Application.bootstrapWithPlugins({
200
  entryPoints: ["src/index.ts"],
201
}, [
202
  new ArgumentsReader(0),           // CLI args (highest priority)
203
  new TypeDocReader(),              // typedoc.json/js
204
  new PackageJsonReader(),          // package.json typedocOptions
205
  new TSConfigReader(),             // tsconfig.json typedocOptions
206
  new ArgumentsReader(300).ignoreErrors(), // CLI args again (for overrides)
207
]);
208

209
// Create custom reader
210
class CustomConfigReader implements OptionsReader {
211
  readonly priority = 200;
212
  
213
  read(container: Options, logger: Logger, cwd: string): void {
214
    // Read from custom configuration source
215
    const customConfig = loadCustomConfig(cwd);
216
    
217
    for (const [key, value] of Object.entries(customConfig)) {
218
      if (container.getDeclaration(key)) {
219
        container.setValue(key as any, value);
220
      }
221
    }
222
  }
223
}
224

225
// Add custom reader
226
app.options.addReader(new CustomConfigReader());
227
```
228

229
### Option Declarations
230

231
Type-safe option declarations that define available configuration parameters with validation and defaults.
232

233
```typescript { .api }
234
/**
235
 * Base option declaration
236
 */
237
interface DeclarationOptionBase {
238
  /** Option name */
239
  name: string;
240
  /** Help text describing the option */
241
  help: string;
242
  /** Option type */
243
  type: ParameterType;
244
  /** Default value */
245
  defaultValue?: unknown;
246
  /** Validation function */
247
  validate?: (value: unknown) => void;
248
  /** Configuration file key (if different from name) */
249
  configFileKey?: string;
250
}
251

252
/**
253
 * String option declaration
254
 */
255
interface StringDeclarationOption extends DeclarationOptionBase {
256
  type: ParameterType.String;
257
  defaultValue?: string;
258
  /** Validation function for strings */
259
  validate?: (value: string) => void;
260
}
261

262
/**
263
 * Number option declaration
264
 */
265
interface NumberDeclarationOption extends DeclarationOptionBase {
266
  type: ParameterType.Number;
267
  defaultValue?: number;
268
  /** Validation function for numbers */
269
  validate?: (value: number) => void;
270
}
271

272
/**
273
 * Boolean option declaration
274
 */
275
interface BooleanDeclarationOption extends DeclarationOptionBase {
276
  type: ParameterType.Boolean;
277
  defaultValue?: boolean;
278
  /** Validation function for booleans */
279
  validate?: (value: boolean) => void;
280
}
281

282
/**
283
 * Array option declaration
284
 */
285
interface ArrayDeclarationOption extends DeclarationOptionBase {
286
  type: ParameterType.Array;
287
  defaultValue?: string[];
288
  /** Validation function for arrays */
289
  validate?: (value: string[]) => void;
290
}
291

292
/**
293
 * Path option declaration
294
 */
295
interface PathDeclarationOption extends DeclarationOptionBase {
296
  type: ParameterType.Path;
297
  defaultValue?: string;
298
  /** Whether this is an output shortcut */
299
  outputShortcut?: boolean;
300
  /** Validation function for paths */
301
  validate?: (value: string) => void;
302
}
303

304
/**
305
 * Map option declaration (key-value pairs)
306
 */
307
interface MapDeclarationOption extends DeclarationOptionBase {
308
  type: ParameterType.Map;
309
  defaultValue?: Record<string, string>;
310
  /** Map key validation */
311
  mapKeyValidation?: (key: string) => void;
312
  /** Map value validation */
313
  mapValueValidation?: (value: string) => void;
314
}
315

316
/**
317
 * Flags option declaration (bit flags)
318
 */
319
interface FlagsDeclarationOption<T extends Record<string, number>> extends DeclarationOptionBase {
320
  type: ParameterType.Flags;
321
  /** Available flag values */
322
  flags: T;
323
  defaultValue?: number;
324
  /** Validation function for flags */
325
  validate?: (value: number) => void;
326
}
327

328
/**
329
 * Mixed type option (union of multiple types)
330
 */
331
interface MixedDeclarationOption extends DeclarationOptionBase {
332
  type: ParameterType.Mixed;
333
  /** Validation function for mixed types */
334
  validate?: (value: unknown) => void;
335
}
336

337
/**
338
 * Object option declaration
339
 */
340
interface ObjectDeclarationOption extends DeclarationOptionBase {
341
  type: ParameterType.Object;
342
  defaultValue?: Record<string, unknown>;
343
  /** Validation function for objects */
344
  validate?: (value: Record<string, unknown>) => void;
345
}
346
```
347

348
### TypeDoc Options Interface
349

350
Complete interface defining all available TypeDoc configuration options.
351

352
```typescript { .api }
353
/**
354
 * Complete TypeDoc options interface
355
 */
356
interface TypeDocOptions {
357
  // Input Options
358
  entryPoints: string[];
359
  entryPointStrategy: EntryPointStrategy;
360
  exclude: string[];
361
  externalPattern: string[];
362
  excludeExternals: boolean;
363
  excludeNotDocumented: boolean;
364
  excludeInternal: boolean;
365
  excludePrivate: boolean;
366
  excludeProtected: boolean;
367
  excludeReferences: boolean;
368
  
369
  // Output Options  
370
  out: string;
371
  json: string;
372
  pretty: boolean;
373
  emit: EmitStrategy;
374
  theme: string;
375
  router: string;
376
  lightHighlightTheme: string;
377
  darkHighlightTheme: string;
378
  highlightLanguages: string[];
379
  customCss: string;
380
  customJs: string;
381
  markdownItOptions: object;
382
  
383
  // Comments Options
384
  commentStyle: CommentStyle;
385
  blockTags: `@${string}`[];
386
  inlineTags: `@${string}`[];
387
  modifierTags: `@${string}`[];
388
  excludeTags: `@${string}`[];
389
  
390
  // Organization Options
391
  categorizeByGroup: boolean;
392
  defaultCategory: string;
393
  categoryOrder: string[];
394
  groupOrder: string[];
395
  sort: SortStrategy[];
396
  kindSortOrder: ReflectionKind[];
397
  
398
  // Validation Options
399
  treatWarningsAsErrors: boolean;
400
  intentionallyNotExported: string[];
401
  validation: ValidationOptions;
402
  
403
  // Other Options
404
  name: string;
405
  includeVersion: boolean;
406
  disableSources: boolean;
407
  sourceLinkTemplate: string;
408
  gitRevision: string;
409
  gitRemote: string;
410
  githubPages: boolean;
411
  basePath: string;
412
  media: string;
413
  includes: string;
414
  
415
  // Watch Options  
416
  watch: boolean;
417
  preserveWatchOutput: boolean;
418
  
419
  // Plugin Options
420
  plugin: string[];
421
  
422
  // Advanced Options
423
  skipErrorChecking: boolean;
424
  compilerOptions: object;
425
  tsconfig: string;
426
  options: string;
427
  showConfig: boolean;
428
  logLevel: LogLevel;
429
  listInvalidSymbolLinks: boolean;
430
  
431
  // Package Options (for monorepos)
432
  packageOptions: object;
433
  entryPointPackages: string[];
434
}
435
```
436

437
### Configuration Enums
438

439
Enums for configuration parameter types and values.
440

441
```typescript { .api }
442
/**
443
 * Types of configuration parameters
444
 */
445
enum ParameterType {
446
  String = "string",
447
  Number = "number", 
448
  Boolean = "boolean",
449
  Map = "map",
450
  Mixed = "mixed",
451
  Array = "array",
452
  PathArray = "pathArray",
453
  ModuleArray = "moduleArray", 
454
  GlobArray = "globArray",
455
  Object = "object",
456
  Flags = "flags",
457
  Path = "path",
458
  Module = "module",
459
  Glob = "glob",
460
}
461

462
/**
463
 * Parameter display hints for help generation
464
 */
465
enum ParameterHint {
466
  File = "file",
467
  Directory = "directory",
468
}
469

470
/**
471
 * Comment parsing styles
472
 */
473
enum CommentStyle {
474
  JSDoc = "jsdoc",
475
  Block = "block",
476
  Line = "line", 
477
  All = "all",
478
}
479

480
/**
481
 * Documentation emission strategies
482
 */
483
enum EmitStrategy {
484
  both = "both",   // Emit both docs and JS
485
  docs = "docs",   // Emit docs only (default)
486
  none = "none",   // No emission, validation only
487
}
488

489
/**
490
 * Entry point resolution strategies
491
 */
492
enum EntryPointStrategy {
493
  Resolve = "resolve",   // Resolve entry points (default)
494
  Expand = "expand",     // Expand directories
495
  Packages = "packages", // Package-based (monorepos)
496
  Merge = "merge",       // Merge all into single module
497
}
498
```
499

500
### Option Defaults
501

502
Default values and presets for common configuration scenarios.
503

504
```typescript { .api }
505
/**
506
 * Default option values
507
 */
508
namespace OptionDefaults {
509
  /** Default entry point strategy */
510
  const entryPointStrategy: EntryPointStrategy;
511
  
512
  /** Default comment style */
513
  const commentStyle: CommentStyle;
514
  
515
  /** Default theme name */
516
  const theme: string;
517
  
518
  /** Default sort strategies */
519
  const sort: SortStrategy[];
520
  
521
  /** Default block tags */
522
  const blockTags: `@${string}`[];
523
  
524
  /** Default inline tags */
525
  const inlineTags: `@${string}`[];
526
  
527
  /** Default modifier tags */
528
  const modifierTags: `@${string}`[];
529
}
530
```
531

532
### Validation Options
533

534
Configuration for documentation validation and quality checks.
535

536
```typescript { .api }
537
/**
538
 * Validation configuration options
539
 */
540
interface ValidationOptions {
541
  /** Validate that documented types are not missing exports */
542
  notExported: boolean;
543
  /** Validate internal consistency of documentation */
544
  invalidLink: boolean;
545
  /** Validate that documented symbols have comments */
546
  notDocumented: boolean;
547
}
548

549
/**
550
 * Manually validated option type for complex validations
551
 */
552
type ManuallyValidatedOption<T> = {
553
  /** The actual option value */
554
  value: T;
555
  /** Whether the value has been manually validated */
556
  validated: boolean;
557
};
558
```
559

560
## Usage Patterns
561

562
### Configuration File Loading
563

564
```typescript
565
import { Application, TypeDocReader } from "typedoc";
566

567
// Load from typedoc.json
568
const reader = new TypeDocReader();
569
const options = new Options();
570
reader.read(options, logger, process.cwd());
571

572
// Custom configuration loading
573
class CustomConfigLoader {
574
  static async loadConfig(configPath: string): Promise<Partial<TypeDocOptions>> {
575
    const configFile = await readFile(configPath, 'utf8');
576
    return JSON.parse(configFile);
577
  }
578
}
579
```
580

581
### Dynamic Option Management  
582

583
```typescript
584
import { Options, ParameterType } from "typedoc";
585

586
const options = new Options();
587

588
// Add custom options at runtime
589
options.addDeclaration({
590
  name: "customOutputFormat",
591
  help: "Specify custom output format",
592
  type: ParameterType.String,
593
  defaultValue: "html",
594
  validate: (value: string) => {
595
    if (!["html", "json", "xml"].includes(value)) {
596
      throw new Error("Invalid output format");
597
    }
598
  }
599
});
600

601
// Listen for option changes
602
options.on("optionSet", (name, value) => {
603
  console.log(`Option ${name} set to:`, value);
604
});
605
```
606

607
## Error Handling
608

609
The configuration system handles various error conditions:
610

611
- **File Not Found**: Missing configuration files, invalid paths
612
- **Parse Errors**: Malformed JSON/JS config files, syntax errors  
613
- **Validation Errors**: Invalid option values, type mismatches, constraint violations
614
- **Reader Conflicts**: Conflicting values from multiple sources, priority resolution
615
- **Unknown Options**: Unrecognized option names, typos, deprecated options
616

617
All configuration errors are reported through the logger with detailed context about the source and nature of the error.