These options control how TypeDoc parses comments.

commentStyle

$ typedoc --commentStyle block
Copy

Determines what comment types TypeDoc will use. Note: Writing non-JSDoc comments will cause poorer intellisense in VSCode and is therefore generally not recommended.

Value	Behavior
jsdoc (default)	Use block comments starting with /**
block	Use all block comments
line	Use // comments
all	Use both block and line comments

useTsLinkResolution

$ typedoc --useTsLinkResolution false
Copy

Indicates that {@link} tags should be resolved with TypeScript's parsing rules. This is on by default.

preserveLinkText

$ typedoc --preserveLinkText false
Copy

Indicates whether or not {@link} tags should include just the name of the target reflection, or the original link text. This is on by default.

jsDocCompatibility

CLI:

$ typedoc --jsDocCompatibility false
$ typedoc --jsDocCompatibility.defaultTag false
Copy

typedoc.json (defaults):

{
    "jsDocCompatibility": {
        "exampleTag": true,
        "defaultTag": true,
        "inheritDocTag": true,
        "ignoreUnescapedBraces": true
    }
}
Copy

JSDoc specifies that the @example and @default tags indicate that the following content should be parsed as code. This conflicts with the TSDoc standard. With this option on, TypeDoc will attempt to infer from the tag content whether it should be parsed as code by checking if the tag content contains a code block.

TSDoc specifies that @inheritdoc should be spelled with a capitalized D, @inheritDoc. If inheritDocTag is set to false, TypeDoc will produce a warning when rewriting @inheritdoc to @inheritDoc.

TSDoc specifies that braces ({}) must be escaped within comments to avoid ambiguity between the start of an inline tag and a brace to be included in the rendered text. TypeDoc's ignoreUnescapedBraces option determines if warnings are emitted if a brace is found within regular comment text without being escaped.

suppressCommentWarningsInDeclarationFiles

$ typedoc --suppressCommentWarningsInDeclarationFiles
Copy

Prevents warnings due to unspecified tags from being reported in comments within .d.ts files.

blockTags

// typedoc.json
{
    "blockTags": ["@param", "@returns"]
}
Copy

This specifies all of the block tags that TypeDoc considers to be valid.

TypeDoc will warn when it finds an unknown tag. If you need to add a custom one, you can extend the defaults by using a JavaScript configuration file:

import { OptionDefaults } from "typedoc";

/** @type {Partial<import('typedoc').TypeDocOptions>} */
const config = {
    // Other config here.
    // ...

    blockTags: [...OptionDefaults.blockTags, "@foo"],
};

export default config;
Copy

Note that this option will be set by tsdoc.json, if present. (Using a tsdoc.json file is an alternate way to add a custom tag.)

Also see inlineTags and modifierTags.

inlineTags

// typedoc.json
{
    "inlineTags": ["@link"]
}
Copy

This specifics all of the inline tags that TypeDoc considers to be valid.

TypeDoc will warn when it finds a non-valid tag. If you need to add a custom one, you can extend the defaults by using a JavaScript configuration file:

import { OptionDefaults } from "typedoc";

/** @type {Partial<import('typedoc').TypeDocOptions>} */
const config = {
    // Other config here.
    // ...

    inlineTags: [...OptionDefaults.inlineTags, "@foo"],
};

export default config;
Copy

Note that this option will be set by tsdoc.json, if present. (Using a tsdoc.json file is an alternate way to add a custom tag.)

Also see blockTags and modifierTags.

modifierTags

// typedoc.json
{
    "modifierTags": ["@hidden", "@packageDocumentation"]
}
Copy

This specifics all of the modifier tags that TypeDoc considers to be valid.

TypeDoc will warn when it finds a non-valid tag. If you need to add a custom one, you can extend the defaults by using a JavaScript configuration file:

import { OptionDefaults } from "typedoc";

/** @type {Partial<import('typedoc').TypeDocOptions>} */
const config = {
    // Other config here.
    // ...

    modifierTags: [...OptionDefaults.modifierTags, "@foo"],
};

export default config;
Copy

Note that this option will be set by tsdoc.json, if present. (Using a tsdoc.json file is an alternate way to add a custom tag.)

Also see blockTags and inlineTags.

cascadedModifierTags

// typedoc.json
{
    "modifierTags": ["@alpha", "@beta", "@experimental"]
}
Copy

Specifies modifier tags which should be copied to all children of the parent reflection.

Note: @deprecated is a block tag, not a modifier tag, so should not be specified here.

excludeTags

$ typedoc --excludeTags apidefine
Copy

Specify tags that should be removed from doc comments when parsing. Useful if your project uses apiDoc for documenting RESTful web APIs.

notRenderedTags

$ typedoc --notRenderedTags beta
Copy

Specify tags which should be preserved in the doc comments, but not rendered when creating output. This is intended to support tags which carry some meaning about how to render a member or instructions for TypeDoc to do something after a package has been deserialized from JSON in packages mode.

externalSymbolLinkMappings

// typedoc.json
{
    // format: { [packageName: string]: { [exportName: string]: string } }
    "externalSymbolLinkMappings": {
        // {@link typescript!Partial} will use this link as well as
        // type Foo = Partial<Bar>
        "typescript": {
            "Partial": "https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype"
        }
    }
}
Copy

Can be used to specify locations of externally defined types. If the external library uses namespaces, qualify the name with . as a separator. These definitions will be used for both types linked to by the user via a {@link} tag and in code.

TypeDoc assumes that if a symbol was referenced from a package, it was exported from that package. This will be true for most native TypeScript packages, but packages which rely on @types will be linked according to the @types package, not the original module name. If both are intended to be supported, both packages must be listed.

// typedoc.json
{
    "externalSymbolLinkMappings": {
        // used by `class Foo extends Component {}`
        "@types/react": {
            "Component": "https://reactjs.org/docs/react-component.html"
        },
        // used by {@link react!Component}
        "react": {
            "Component": "https://reactjs.org/docs/react-component.html"
        }
    }
}
Copy

Global external types are supported, but may have surprising behavior. Types which are defined in the TypeScript lib files (including Array, Promise, ...) will be detected as belonging to the typescript package rather than the special global package reserved for global types.

// typedoc.json
{
    "externalSymbolLinkMappings": {
        // used by {@link !Promise}
        "global": {
            "Promise": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise"
        },
        // used by type Foo = Promise<string>
        "typescript": {
            "Promise": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise"
        }
    }
}
Copy