To customize JSDoc's behavior, you can provide a configuration file to JSDoc in one of the following formats:
To run JSDoc with a configuration file, use the -c command-line option (for example, jsdoc -c /path/to/conf.json or jsdoc -c /path/to/conf.js).
The following examples show a simple configuration file that enables JSDoc's Markdown plugin. JSDoc's configuration options are explained in detail in the following sections.
{
"plugins": ["plugins/markdown"]
}
'use strict';
module.exports = {
plugins: ['plugins/markdown']
};
For a more comprehensive example of a JSON configuration file, see the file conf.json.EXAMPLE.
If you do not specify a configuration file, JSDoc uses the following configuration options:
{
"plugins": [],
"recurseDepth": 10,
"source": {
"includePattern": ".+\\.js(doc|x)?$",
"excludePattern": "(^|\\/|\\\\)_"
},
"sourceType": "module",
"tags": {
"allowUnknownTags": true,
"dictionaries": ["jsdoc","closure"]
},
"templates": {
"cleverLinks": false,
"monospaceLinks": false
}
}
This means:
plugins).-r command-line flag, JSDoc will search for files 10 levels deep (recurseDepth)..js, .jsdoc, and .jsx will be processed (source.includePattern).source.excludePattern).sourceType).tags.allowUnknownTags).tags.dictionaries).{@link} tags are rendered in plain text (templates.cleverLinks, templates.monospaceLinks).These options and others are explained in the following sections.
To enable plugins, add their paths (relative to the JSDoc folder) into the plugins array.
For example, the following JSON configuration file will enable the Markdown plugin, which converts Markdown-formatted text to HTML, and the "summarize" plugin, which autogenerates a summary for each doclet:
{
"plugins": [
"plugins/markdown",
"plugins/summarize"
]
}
See the plugin reference for further information, and look in JSDoc's plugins directory for the plugins built into JSDoc.
You can configure the Markdown plugin by adding a markdown object to your configuration file. See Configuring the Markdown Plugin for details.
The recurseDepth option controls how many levels deep JSDoc will recursively search for source files and tutorials. This option is available in JSDoc 3.5.0 and later. This option is used only if you also specify the -r command-line flag, which tells JSDoc to recursively search for input files.
{
"recurseDepth": 10
}
The source set of options, in combination with paths given to JSDoc on the command line, determines the set of input files that JSDoc uses to generate documentation.
{
"source": {
"include": [ /* array of paths to files to generate documentation for */ ],
"exclude": [ /* array of paths to exclude */ ],
"includePattern": ".+\\.js(doc|x)?$",
"excludePattern": "(^|\\/|\\\\)_"
}
}
source.include: An optional array of paths that contain files for which JSDoc should generate documentation. The paths given to JSDoc on the command line are combined with these paths. You can use the -r command-line option to recurse into subdirectories.source.exclude: An optional array of paths that JSDoc should ignore. In JSDoc 3.3.0 and later, this array may include subdirectories of the paths in source.include.source.includePattern: An optional string, interpreted as a regular expression. If present, all filenames must match this regular expression to be processed by JSDoc. By default, this option is set to ".+\.js(doc|x)?$", meaning that only files with the extensions .js, .jsdoc, and .jsx will be processed.source.excludePattern: An optional string, interpreted as a regular expression. If present, any file matching this regular expression will be ignored. By default, this option is set so that files beginning with an underscore (or anything under a directory beginning with an underscore) is ignored. These options are interpreted in the following order:
source.include.source.includePattern is present, the filename must match it, or it is ignored.source.excludePattern is present, any filename matching this regular expression is ignored.source.exclude, it is ignored.All remaining files after these four steps are processed by JSDoc.
As an example, suppose you have the following file structure:
myProject/ |- a.js |- b.js |- c.js |- _private | |- a.js |- lib/ |- a.js |- ignore.js |- d.txt
In addition, suppose your conf.json file looks like this example:
{
"source": {
"include": ["myProject/a.js", "myProject/lib", "myProject/_private"],
"exclude": ["myProject/lib/ignore.js"],
"includePattern": ".+\\.js(doc|x)?$",
"excludePattern": "(^|\\/|\\\\)_"
}
}
If you run jsdoc myProject/c.js -c /path/to/my/conf.json -r from the file containing the myProject folder, JSDoc will generate documentation for the following files:
myProject/a.js myProject/c.js myProject/lib/a.js Here's why:
source.include and the paths given on the command line, JSDoc starts off with these files: myProject/c.js (from the command line)myProject/a.js (from source.include)myProject/lib/a.js, myProject/lib/ignore.js, myProject/lib/d.txt (from source.include and using the -r option)myProject/_private/a.js (from source.include)source.includePattern, leaving us with all of the above files except myProject/lib/d.txt, which does not end in .js, .jsdoc, or .jsx.source.excludePattern, which removes myProject/_private/a.js.source.exclude, which removes myProject/lib/ignore.js.The sourceType option affects how JSDoc parses your JavaScript files. This option is available in JSDoc 3.5.0 and later. This option accepts the following values:
module (default): Use this value for most types of JavaScript files.script: Use this value if JSDoc logs errors such as Delete of an unqualified identifier in
strict mode when it parses your code.{
"sourceType": "module"
}
You can put many of JSDoc's command-line options into the configuration file instead of specifying them on the command line. To do this, add the long names of the relevant options into an opts section of the configuration file, with the value set to the option's value.
{
"opts": {
"template": "templates/default", // same as -t templates/default
"encoding": "utf8", // same as -e utf8
"destination": "./out/", // same as -d ./out/
"recurse": true, // same as -r
"tutorials": "path/to/tutorials", // same as -u path/to/tutorials
}
}
By using the source.include and opts options, you can put almost all of the arguments to JSDoc in a configuration file, so that the command line reduces to:
jsdoc -c /path/to/conf.json
When options are specified on the command line and in the configuration file, the command line takes precedence.
The options in tags control which JSDoc tags are allowed and how each tag is interpreted.
{
"tags": {
"allowUnknownTags": true,
"dictionaries": ["jsdoc","closure"]
}
}
The tags.allowUnknownTags property affects how JSDoc handles unrecognized tags. If you set this option to false, and JSDoc finds a tag that it does not recognize (for example, @foo), JSDoc logs a warning. By default, this option is set to true. In JSDoc 3.4.1 and later, you can also set this property to an array of tag names that JSDoc should allow (for example, ["foo","bar"]).
The tags.dictionaries property controls which tags JSDoc recognizes, as well as how JSDoc interprets the tags that it recognizes. In JSDoc 3.3.0 and later, there are two built-in tag dictionaries:
jsdoc: Core JSDoc tags.closure: Closure Compiler tags.By default, both dictionaries are enabled. Also, by default, the jsdoc dictionary is listed first; as a result, if the jsdoc dictionary handles a tag differently than the closure dictionary, the jsdoc version of the tag takes precedence.
If you are using JSDoc with a Closure Compiler project, and you want to avoid using tags that Closure Compiler does not recognize, change the tags.dictionaries setting to ["closure"]. You can also change this setting to ["closure","jsdoc"] if you want to allow core JSDoc tags, but you want to ensure that Closure Compiler-specific tags are interpreted as Closure Compiler would interpret them.
The options in templates affect the appearance and content of generated documentation. Third-party templates may not implement all of these options. See Configuring JSDoc's Default Template for additional options that the default template supports.
{
"templates": {
"cleverLinks": false,
"monospaceLinks": false
}
}
If templates.monospaceLinks is true, all link text from the inline {@link} tag will be rendered in monospace.
If templates.cleverLinks is true, {@link asdf} will be rendered in normal font if asdf is a URL, and monospace otherwise. For example, {@link http://github.com} will render in plain text, but {@link MyNamespace.myFunction} will be in monospace.
If templates.cleverLinks is true, templates.monospaceLinks is ignored.
© 2011–2017 the contributors to the JSDoc 3 documentation project
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
http://usejsdoc.org/about-configuring-jsdoc.html