Utility Options
Options that are used for general configuration and utility purposes.
formatWithPrettier
Accepts a boolean value. Defaults to
false
.
This plugin generates well-formatted Markdown, however, integrating the popular formatting package Prettier can provide additional enhancements, such as:
- Formats code inside fenced blocks using the respective Prettier configuration for that language.
- Aligns markdown table cells.
- Removes unnecessary escape characters.
- Wraps long lines of text to fit within a configurable line width.
Please note that Prettier is not a dependency of this plugin and must be installed in your project for this option to work.
npm i prettier --save-dev
to use this option.
{
"formatWithPrettier": false
}
prettierConfigFile
Specify a custom Prettier configuration file location.
Defaults to
"undefined"
.
By default Prettier uses the options resolved from a discovered Prettier configuration file.
Use this option to specify a separate Prettier configuration file in a custom location.
Please note this option is only applicable when formatWithPrettier
is set to "true"
.
{
"prettierConfigFile": "./path/to/.prettierrc.json"
}
sanitizeComments
Accepts a boolean value. Defaults to
false
.
Please note this options does not affect the rendering of inline code or code blocks (using single/triple backticks).
By default all comments written inside JsDoc comments will be passed to the output as written, and parsers will interpret un-escaped angle brackets as HTML/JSX tags..
This option will escape angle brackets <
>
and curly braces {
}
written inside JsDoc comments.
This option would typically be used when source code comes from an external source exposing the following potential issues:
- Comments contain raw tags that should be interpreted as code examples.
- Comments contain invalid syntax that (in the case of MDX) will cause breaking parsing errors.
- Although most parsers use XSS filters, this option provides an additional layer of XSS security.
{
"sanitizeComments": false
}
publicPath
Accepts a string value. Defaults to
"undefined"
.
If undefined all urls will be relative.
{
"publicPath": "http://abc.com"
}
anchorPrefix
Custom anchor prefix when anchoring to in-page symbols.
Accepts a string value. Defaults to
"undefined"
.
This option should be used when parsers require a custom anchor prefix.
{
"anchorPrefix": "markdown-header"
}
useHTMLEncodedBrackets
Accepts a boolean value. Defaults to
false
.
By default, opening and closing angle brackets (<
and >
) are escaped using backslashes, and most modern Markdown processors handle them consistently.
However, using HTML entities (<
and >
) might be preferable to avoid any inconsistencies with some Markdown processors.
{
"useHTMLEncodedBrackets": false
}
useHTMLAnchors
Accepts a boolean value. Defaults to
false
.
By default markdown parsers normally assign header IDs to headings automatically. This is required when cross linking to symbols within a page. This option should be used when parsers that do not automatically assign header IDs.
Note that HTML anchors will be added to linkable symbols listed in table rows as there is no alternative way to anchor to these items.
{
"useHTMLAnchors": false
}
preserveAnchorCasing
Preserve anchor casing when generating link to symbols.
Accepts a boolean value. Defaults to
false
.
By default references to symbol anchor links are lowercased.
This option can be used for engines that require the preservation of anchor link casing.
{
"preserveAnchorCasing": false
}
pageTitleTemplates
Accepts a key/value object.
Customizes the page titles for index, module, and member pages in the documentation.
The option is provided as an object with keys corresponding to the page type.
The Values of each key can be either:
- A function accepting input arguments.
- A strings supporting placeholders.
Available placeholders / arguments:
{projectName}
- the project’s name resolved by TypeDoc.{version}
- the project version resolved by TypeDoc (when includeVersion istrue
).{kind}
- the reflection kind of the item.{group}
- the group title that the item belongs to.
Available keys:
- The
index
key (main documentation index page) accepts theprojectName
andversion
placeholder/args. - The
module
key (module and namespace pages) accepts thekind
andname
placeholder/args. - The
member
key (individual module member pages) accepts thekind
,name
, andgroup
placeholder/args.
pageTitleTemplates: {
index: (args) => `${args.projectName}: ${args.version}`,
module: (args) => args.name,
member: (args) => `${args.kind}: ${args.name}`,
}
{
"pageTitleTemplates": {
"index": "{projectName} {version}",
"member": "{kind}: {name}",
"module": "{name}"
}
}