0
# Configuration
1

2
JSDoc's configuration system provides flexible control over documentation generation through JSON configuration files, command-line options, and environment settings.
3

4
## Capabilities
5

6
### Config Class
7

8
Core configuration management class for loading and merging settings.
9

10
```javascript { .api }
11
class Config {
12
  /**
13
   * Create configuration instance
14
   * @param jsonOrObject - Configuration JSON string, object, or undefined
15
   */
16
  constructor(jsonOrObject?: string | object);
17

18
  /**
19
   * Get merged configuration with defaults
20
   * @returns Complete configuration object
21
   */
22
  get(): ConfigObject;
23
}
24
```
25

26
### Configuration Structure
27

28
Complete configuration object interface with all available options.
29

30
```javascript { .api }
31
interface ConfigObject {
32
  /** Plugin module paths to load */
33
  plugins: string[];
34
  
35
  /** Maximum recursion depth for directory scanning */
36
  recurseDepth: number;
37
  
38
  /** Source file configuration */
39
  source: {
40
    /** Regex pattern for files to include */
41
    includePattern: string;
42
    /** Regex pattern for files to exclude */
43
    excludePattern: string;
44
    /** Array of specific paths to include */
45
    include?: string[];
46
    /** Array of specific paths to exclude */
47
    exclude?: string[];
48
  };
49
  
50
  /** Source code type: 'module' or 'script' */
51
  sourceType: string;
52
  
53
  /** JSDoc tag configuration */
54
  tags: {
55
    /** Allow unknown tags without errors */
56
    allowUnknownTags: boolean;
57
    /** Tag dictionaries to use */
58
    dictionaries: string[];
59
  };
60
  
61
  /** Template configuration */
62
  templates: {
63
    /** Use monospace font for links */
64
    monospaceLinks: boolean;
65
    /** Use intelligent link text */
66
    cleverLinks: boolean;
67
    /** Additional template-specific options */
68
    [key: string]: any;
69
  };
70
  
71
  /** Command-line options */
72
  opts?: {
73
    /** Output destination directory */
74
    destination?: string;
75
    /** File encoding */
76
    encoding?: string;
77
    /** Configuration file path */
78
    configure?: string;
79
    /** Template directory path */
80
    template?: string;
81
    /** Include private members */
82
    private?: boolean;
83
    /** README file path */
84
    readme?: string;
85
    /** Package.json file path */
86
    package?: string;
87
    /** Enable debug logging */
88
    debug?: boolean;
89
    /** Enable verbose logging */
90
    verbose?: boolean;
91
    /** Recursive directory scanning */
92
    recurse?: boolean;
93
    /** Tutorial directory path */
94
    tutorials?: string;
95
    /** Access levels to include */
96
    access?: string | string[];
97
    /** Treat warnings as errors */
98
    pedantic?: boolean;
99
    /** Additional query parameters */
100
    query?: object;
101
  };
102
}
103
```
104

105
## Configuration Files
106

107
### Basic Configuration
108

109
```json
110
{
111
  "source": {
112
    "include": ["./src/"],
113
    "includePattern": "\\.(js|jsx)$",
114
    "exclude": ["node_modules/"],
115
    "excludePattern": "(node_modules/|docs/)"
116
  },
117
  "opts": {
118
    "destination": "./docs/",
119
    "recurse": true
120
  },
121
  "plugins": ["plugins/markdown"]
122
}
123
```
124

125
### Advanced Configuration
126

127
```json
128
{
129
  "tags": {
130
    "allowUnknownTags": true,
131
    "dictionaries": ["jsdoc", "closure"]
132
  },
133
  "source": {
134
    "include": ["./lib", "./src"],
135
    "includePattern": "\\.(js|jsx|ts|tsx)$",
136
    "exclude": ["node_modules/", "test/", "spec/"],
137
    "excludePattern": "((node_modules/|docs/)|\\.(test|spec)\\.js$)"
138
  },
139
  "plugins": [
140
    "plugins/markdown",
141
    "plugins/overloadHelper",
142
    "plugins/summarize",
143
    "./custom-plugins/version-plugin"
144
  ],
145
  "recurseDepth": 10,
146
  "sourceType": "module",
147
  "opts": {
148
    "destination": "./public/docs/",
149
    "encoding": "utf8",
150
    "private": false,
151
    "recurse": true,
152
    "template": "./templates/custom",
153
    "tutorials": "./tutorials",
154
    "readme": "./README.md",
155
    "package": "./package.json",
156
    "access": ["public", "protected"],
157
    "debug": false,
158
    "verbose": false,
159
    "pedantic": false
160
  },
161
  "templates": {
162
    "cleverLinks": false,
163
    "monospaceLinks": false,
164
    "dateFormat": "MMMM Do YYYY",
165
    "outputSourceFiles": true,
166
    "systemName": "My API Documentation",
167
    "footer": "Generated by JSDoc",
168
    "copyright": "Copyright © 2023 My Company",
169
    "includeDate": true,
170
    "navType": "vertical",
171
    "theme": "default",
172
    "linenums": true,
173
    "collapseSymbols": false
174
  }
175
}
176
```
177

178
### Plugin Configuration
179

180
```json
181
{
182
  "plugins": ["plugins/markdown"],
183
  "markdown": {
184
    "hardwrap": true,
185
    "idInHeadings": true
186
  },
187
  "templates": {
188
    "applicationName": "My API",
189
    "disqus": "my-disqus-shortname",
190
    "googleAnalytics": "UA-12345678-1",
191
    "openGraph": {
192
      "title": "My API Documentation",
193
      "type": "website",
194
      "image": "http://example.com/image.png",
195
      "site_name": "My API Docs"
196
    },
197
    "meta": {
198
      "title": "My API Documentation",
199
      "description": "Complete API reference",
200
      "keyword": "api, documentation, javascript"
201
    },
202
    "linenums": true
203
  }
204
}
205
```
206

207
## Environment Configuration
208

209
### Environment Variables
210

211
```javascript { .api }
212
// Environment object structure
213
const env = {
214
  /** Runtime information */
215
  run: {
216
    start: Date;
217
    finish: Date | null;
218
  };
219
  
220
  /** Command-line arguments */
221
  args: string[];
222
  
223
  /** Loaded configuration */
224
  conf: ConfigObject;
225
  
226
  /** JSDoc installation directory */
227
  dirname: string;
228
  
229
  /** Working directory when JSDoc started */
230
  pwd: string;
231
  
232
  /** Parsed command-line options */
233
  opts: ConfigObject['opts'];
234
  
235
  /** Source files to process */
236
  sourceFiles: string[];
237
  
238
  /** Version information */
239
  version: {
240
    number: string;
241
    revision: string;
242
  };
243
};
244
```
245

246
### Accessing Environment
247

248
```javascript
249
const env = require('jsdoc/env');
250

251
// Check if debug mode is enabled
252
if (env.opts.debug) {
253
  console.log('Debug mode enabled');
254
}
255

256
// Get output destination
257
const outputDir = env.opts.destination || './out/';
258

259
// Check configuration
260
if (env.conf.plugins.includes('plugins/markdown')) {
261
  console.log('Markdown plugin enabled');
262
}
263
```
264

265
## Configuration Loading
266

267
### Default Configuration
268

269
JSDoc uses these defaults when no configuration is provided:
270

271
```javascript
272
const defaults = {
273
  plugins: [],
274
  recurseDepth: 10,
275
  source: {
276
    includePattern: '.+\\.js(doc|x)?$',
277
    excludePattern: ''
278
  },
279
  sourceType: 'module',
280
  tags: {
281
    allowUnknownTags: true,
282
    dictionaries: ['jsdoc', 'closure']
283
  },
284
  templates: {
285
    monospaceLinks: false,
286
    cleverLinks: false
287
  }
288
};
289
```
290

291
### Configuration Merging
292

293
Configuration is merged in this order (later values override earlier):
294

295
1. Built-in defaults
296
2. Configuration file settings
297
3. Command-line options
298

299
```javascript
300
// Example of configuration merging
301
const baseConfig = {
302
  source: { includePattern: '\\.js$' },
303
  opts: { destination: './out/' }
304
};
305

306
const userConfig = {
307
  source: { excludePattern: 'test/' },
308
  opts: { destination: './docs/' }
309
};
310

311
// Result after merging:
312
const finalConfig = {
313
  source: {
314
    includePattern: '\\.js$',      // from base
315
    excludePattern: 'test/'        // from user
316
  },
317
  opts: {
318
    destination: './docs/'         // user overrides base
319
  }
320
};
321
```
322

323
### Configuration File Discovery
324

325
JSDoc looks for configuration files in this order:
326

327
1. File specified with `-c` or `--configure` option
328
2. `conf.json` in JSDoc installation directory
329
3. `conf.json.EXAMPLE` as fallback
330

331
```javascript
332
// Configuration loading process
333
const Config = require('jsdoc/config');
334
const path = require('jsdoc/path');
335

336
let configPath = env.opts.configure || path.join(env.dirname, 'conf.json');
337

338
try {
339
  const configContent = fs.readFileSync(configPath, 'utf8');
340
  const config = new Config(configContent);
341
  env.conf = config.get();
342
} catch (error) {
343
  // Fall back to default configuration
344
  env.conf = new Config().get();
345
}
346
```
347

348
## Source File Configuration
349

350
### Include/Exclude Patterns
351

352
```json
353
{
354
  "source": {
355
    "include": ["./src", "./lib"],
356
    "exclude": ["./src/legacy", "./lib/vendor"],
357
    "includePattern": "\\.(js|jsx|ts|tsx)$",
358
    "excludePattern": "((node_modules/|docs/)|\\.(test|spec|min)\\.js$)"
359
  }
360
}
361
```
362

363
### Pattern Examples
364

365
```javascript
366
// Common include patterns
367
{
368
  "includePattern": "\\.js$",           // JavaScript files only
369
  "includePattern": "\\.(js|jsx)$",     // JavaScript and JSX
370
  "includePattern": "\\.(js|ts)$",      // JavaScript and TypeScript
371
  "includePattern": "\\.js(doc|x)?$"    // JS, JSX, and JSDoc files
372
}
373

374
// Common exclude patterns
375
{
376
  "excludePattern": "node_modules/",           // Exclude dependencies
377
  "excludePattern": "\\.(test|spec)\\.js$",   // Exclude test files
378
  "excludePattern": "\\.min\\.js$",           // Exclude minified files
379
  "excludePattern": "(test/|spec/|build/)"    // Multiple directories
380
}
381
```
382

383
## Template Configuration Options
384

385
### Built-in Template Options
386

387
```json
388
{
389
  "templates": {
390
    "cleverLinks": false,        // Automatic link text generation
391
    "monospaceLinks": false,     // Monospace font for links
392
    "dateFormat": "ddd MMM Do YYYY",
393
    "outputSourceFiles": true,   // Include source file links
394
    "outputSourcePath": true,    // Show source paths
395
    "systemName": "My API",      // Site title
396
    "footer": "Custom footer",   // Footer text
397
    "copyright": "© 2023",       // Copyright notice
398
    "includeDate": true,         // Include generation date
399
    "navType": "vertical",       // Navigation style
400
    "theme": "cerulean",         // Color theme
401
    "linenums": false,           // Line numbers in code
402
    "collapseSymbols": false,    // Collapsible sections
403
    "inverseNav": false,         // Inverse navigation colors
404
    "protocol": "html://",       // Link protocol
405
    "methodHeadingReturns": false // Show returns in headings
406
  }
407
}
408
```
409

410
### Custom Template Configuration
411

412
```json
413
{
414
  "templates": {
415
    "custom": {
416
      "brandColor": "#2196F3",
417
      "logoUrl": "./assets/logo.png",
418
      "showInheritedInNav": true,
419
      "showAccessFilter": true,
420
      "analytics": {
421
        "ua": "UA-12345678-1",
422
        "domain": "mydocs.com"
423
      },
424
      "social": {
425
        "github": "username/repo",
426
        "twitter": "@username"
427
      }
428
    }
429
  }
430
}
431
```
432

433
## Usage Examples
434

435
### Loading Configuration Programmatically
436

437
```javascript
438
const Config = require('jsdoc/config');
439
const fs = require('fs');
440

441
// Load from JSON file
442
const configContent = fs.readFileSync('jsdoc.conf.json', 'utf8');
443
const config = new Config(configContent);
444
const settings = config.get();
445

446
// Load from object
447
const configObject = {
448
  source: { includePattern: '\\.js$' },
449
  opts: { destination: './docs/' }
450
};
451
const config2 = new Config(configObject);
452
const settings2 = config2.get();
453

454
// Use defaults
455
const config3 = new Config();
456
const defaults = config3.get();
457
```
458

459
### Environment-based Configuration
460

461
```javascript
462
// config-loader.js
463
const env = process.env.NODE_ENV || 'development';
464

465
const configs = {
466
  development: {
467
    opts: {
468
      destination: './dev-docs/',
469
      debug: true,
470
      verbose: true
471
    }
472
  },
473
  production: {
474
    opts: {
475
      destination: './public/docs/',
476
      debug: false,
477
      verbose: false
478
    },
479
    templates: {
480
      includeDate: true,
481
      copyright: `© ${new Date().getFullYear()} My Company`
482
    }
483
  }
484
};
485

486
module.exports = configs[env];
487
```
488

489
### Dynamic Configuration
490

491
```javascript
492
// dynamic-config.js
493
const pkg = require('./package.json');
494

495
module.exports = {
496
  source: {
497
    include: ['./src'],
498
    includePattern: '\\.js$'
499
  },
500
  opts: {
501
    destination: './docs/',
502
    readme: './README.md',
503
    package: './package.json'
504
  },
505
  templates: {
506
    systemName: pkg.name,
507
    footer: `${pkg.name} v${pkg.version}`,
508
    copyright: `© ${new Date().getFullYear()} ${pkg.author}`
509
  }
510
};
511
```
512

513
### Conditional Plugin Loading
514

515
```javascript
516
// conditional-plugins.js
517
const plugins = ['plugins/markdown'];
518

519
// Add development plugins
520
if (process.env.NODE_ENV === 'development') {
521
  plugins.push('plugins/eventDumper');
522
}
523

524
// Add custom plugins if they exist
525
try {
526
  require.resolve('./custom-plugin');
527
  plugins.push('./custom-plugin');
528
} catch (e) {
529
  // Plugin not available
530
}
531

532
module.exports = {
533
  plugins: plugins,
534
  // ... other configuration
535
};
536
```
537

538
## Configuration Validation
539

540
### Validating Configuration
541

542
```javascript
543
function validateConfig(config) {
544
  const errors = [];
545
  
546
  // Validate required fields
547
  if (!config.source) {
548
    errors.push('Missing source configuration');
549
  }
550
  
551
  // Validate patterns
552
  if (config.source.includePattern) {
553
    try {
554
      new RegExp(config.source.includePattern);
555
    } catch (e) {
556
      errors.push(`Invalid includePattern: ${e.message}`);
557
    }
558
  }
559
  
560
  // Validate plugins
561
  if (config.plugins) {
562
    config.plugins.forEach(plugin => {
563
      try {
564
        require.resolve(plugin);
565
      } catch (e) {
566
        errors.push(`Plugin not found: ${plugin}`);
567
      }
568
    });
569
  }
570
  
571
  return errors;
572
}
573

574
// Usage
575
const config = new Config(configContent);
576
const settings = config.get();
577
const errors = validateConfig(settings);
578

579
if (errors.length > 0) {
580
  console.error('Configuration errors:', errors);
581
  process.exit(1);
582
}
583
```