import { Callout, FileTree } from "nextra/components";
These options should be used in conjunction with the core [TypeDoc options](/docs/using-typedoc).Determines how output files are generated.
Accepts either
"members"
or"modules"
. Defaults to"members"
.
TypeDoc creates documentation according to exports derived from the given entryPointsStrategy
configuration.
This option does not alter the way TypeDoc interprets the entryPointsStrategy
but rather provides some flexibility as to how output files are generated.
It is also possible to further refine what members are exported to individual files with the membersWithOwnFile
option.
The following keys are available:
members
Generates an individual file for each exported module member. This is the standard behaviour of the HTML theme and the plugin default.
modules
Generates a single file for every Module or Namespace where all members are hoisted to a single module file. This creates a flat navigation structure and reduces the amount of files generated.
{
"outputFileStrategy": "members"
}
Determines which members are exported to their own file when `outputFileStrategy` equals `members`.
Accepts an array of the following values
"Enum"
"Variable"
"Function"
"Class"
"Interface"
"TypeAlias"
.
This option is useful when only specific types of members should be exported to a single file.
Ignored when outputFileStrategy
is equal to "modules"
{
"membersWithOwnFile": ["Class", "Enum", "Interface"]
}
Flatten output files to a single directory.
Accepts a boolean value. Defaults to
false
.
By default output files are generated in a directory structure that mirrors the project's module hierarchy including folders for member kinds eg classes
, enums
, functions
etc.
This option will flatten the output files to a single directory as follows:
Default output:
Flattened output:
{
"flattenOutputFiles": false
}
Specify the file extension for generated output files.
Accepts a string value. Defaults to
".md"
.
Typically markdown files are recognised by the .md
or .markdown
file extensions..mdx
maybe required for compatibility with certain markdown parsers.
{
"fileExtension": ".mdx"
}
The file name of the entry page.
Accepts a string value. Defaults to
"README"
.
The entry page is the root page of the documentation, equivalent to index.html
for web pages.
README
is recognised when browsing folders on repos and Wikis and is the plugin default. index
might be more suitable for static site generators.
The content of this file will be resolved in the following order:
- The value of the
entryModule
option (if defined). - The resolved Readme file (skipped if the
readme
option is set tonone
). - The documentation index page.
{
"entryFileName": "index"
}
The name of a module that should act as the root page for the documentation.
Accepts a string value. Defaults to
"undefined"
.
This option can be used when the root page of the documentation should be a specific module (typically a module named index
).
The module name should be specified (NOT the reference to the file name).
Please note a separate modules index page will not be generated, therefore would work better if navigation is present.
{
"entryModule": "index"
}
Merges the resolved readme into the project index page.
Accepts a boolean value. Defaults to
false
.
By default when a readme file is resolved, a separate readme page is created. This option appends the index page to the readme so only a single root page is generated.
This option has no effect when readme
is set to "none"
.
{
"mergeReadme": false
}
Exclude writing @ scope directories in paths.
Accepts a boolean value. Defaults to
false
.
By default directories are split by scopes when generating file paths.
This option will remove reference to @scope
in the path when generating files and directories. It does not effect the name of the package or module in the output.
The following will be the directory structure for packages named @scope/package-1
and @scope/package-2
:
false
(default):
{" "} <FileTree.Folder name="@scope" defaultOpen> <FileTree.Folder name="package-1" /> <FileTree.Folder name="package-2" /> </FileTree.Folder>
true
:
Ignored if flattenOutputFiles
is set to true
.
{
"excludeScopesInPaths": false
}
Do not print page header.
Accepts a boolean value. Defaults to
false
.
{
"hidePageHeader": false
}
Do not print page title.
Accepts a boolean value. Defaults to
false
.
{
"hidePageTitle": false
}
Do not print breadcrumbs.
Accepts a boolean value. Defaults to
false
.
{
"hideBreadcrumbs": false
}
Excludes grouping by kind so all members are rendered and sorted at the same level.
Accepts a boolean value. Defaults to
false
.
By default members are grouped by kind (eg Classes, Functions etc).
This creates a flat structure where all members are displayed at the same heading level.
{
"excludeGroups": false
}
Wraps signatures and declarations in code blocks.
Accepts a boolean value. Defaults to
false
.
This option can be used to improve readability and aesthetics when defining signatures and declarations.
Please note that when this option is set to true
it is not possible to link to other references.
As a work around the @link
tag can be be used to manually reference types.
{
"useCodeBlocks": false
}
Expand objects inside declarations.
Accepts a boolean value. Defaults to
false
.
By default objects inside declarations are collapsed to preserve space and improve readability.
This option should be set when a full object representation is preferred.
Default
object
Expanded
{ "x"
: string
}
{
"expandObjects": false
}
Expand parameters in signature parentheses to display type information.
Accepts a boolean value. Defaults to
false
.
By default parameters in signature definitions only display the parameter name so the output is more concise.
This option should be set when a full type representation is preferred.
Default
someFunction(param1, param2)
Expanded
someFunction(param1: string, param2: boolean)
{
"expandParameters": false
}
Specify the render style of parameter and type parameter groups.
Accepts either
"list"
or"table"
. Defaults to"list"
.
This option either renders parameters for functions and class methods as a list or in tabular format.
{
"parametersFormat": "list"
}
Specify the render style of property groups for interfaces and classes.
Accepts either
"list"
or"table"
. Defaults to"list"
.
This option either renders properties for classes and interfaces as a list or in tabular format.
{
"propertiesFormat": "list"
}
Specify the render style of enumeration members.
Accepts either
"list"
or"table"
. Defaults to"list"
.
This option either renders members of enums as a list or in tabular format.
{
"enumMembersFormat": "list"
}
Specify the render style for type declaration members.
Accepts either
"list"
or"table"
. Defaults to"list"
.
This option either renders type declarations as a list or in tabular format.
{
"typeDeclarationFormat": "list"
}
Specify the render format for index items.
Accepts either
"list"
or"table"
. Defaults to"list"
.
This option renders index items either as a simple list or in a table with a description column exposing the comment summary.
For a packages index page (when --entryPointStrategy
equals packages
), the package.json description will be displayed with an additional "Version" column (when --includeVersion
equals true).
{
"indexFormat": "list"
}
Provides a mechanism to change the content of text used in documentation.
Accepts a key/value object.
This option enables changing static text rendered to the documentation. Useful if an alternative English phrase is preferred or to translate English text to another language. This option does not attempt to address translating text within code comments.
Placeholders
Default values within curly braces {}
indicates a placeholder of dynamic text.
The {version}
placeholder requires the TypeDoc option includeVersion
to be true.
Keys
Keys are categorised with the following namespace conventions:
header.*
defines text in the page header (if displayed).breadcrumbs.*
defines breadcrumbs in page header (if displayed).title.*
defines text in main page titles.label.*
other text in page content, including content headings and table headers.kind.*
defines text mappings to TypeDoc'sReflectionKind
definitions.
Only keys that require translation need to be added to the object.
{
"textContentMappings": {
"header.title": "{projectName} {version}",
"header.readme": "Readme",
"header.docs": "Docs",
"breadcrumbs.home": "{projectName} {version}",
"title.indexPage": "{projectName} {version}",
"title.modulePage": "{name}",
"title.memberPage": "{kind}: {name}",
"label.apiIndex": "API Index",
"label.defaultValue": "Default value",
"label.description": "Description",
"label.extendedBy": "Extended by",
"label.extends": "Extends",
"label.flags": "Flags",
"label.globals": "Globals",
"label.implements": "Implements",
"label.implementationOf": "Implementation of",
"label.inheritedFrom": "Inherited from",
"label.index": "Index",
"label.indexable": "Indexable",
"label.indexSignature": "Index signature",
"label.member": "Member",
"label.modifier": "Modifier",
"label.name": "Name",
"label.overrides": "Overrides",
"label.packages": "Packages",
"label.reExports": "Re-exports",
"label.renamesAndReExports": "Renames and re-exports",
"label.returns": "Returns",
"label.source": "Source",
"label.type": "Type",
"label.typeDeclaration": "Type declaration",
"label.value": "Value",
"kind.accessor.singular": "Accessor",
"kind.accessor.plural": "Accessors",
"kind.class.singular": "Class",
"kind.class.plural": "Classes",
"kind.constructor.singular": "Constructor",
"kind.constructor.plural": "Constructors",
"kind.enum.singular": "Enumeration",
"kind.enum.plural": "Enumerations",
"kind.enumMember.singular": "Enumeration Member",
"kind.enumMember.plural": "Enumeration Members",
"kind.event.singular": "Event",
"kind.event.plural": "Events",
"kind.function.singular": "Function",
"kind.function.plural": "Functions",
"kind.interface.singular": "Interface",
"kind.interface.plural": "Interfaces",
"kind.method.singular": "Method",
"kind.method.plural": "Methods",
"kind.module.singular": "Module",
"kind.module.plural": "Modules",
"kind.namespace.singular": "Namespace",
"kind.namespace.plural": "Namespaces",
"kind.variable.singular": "Variable",
"kind.variable.plural": "Variables",
"kind.parameter.singular": "Parameter",
"kind.parameter.plural": "Parameters",
"kind.property.singular": "Property",
"kind.property.plural": "Properties",
"kind.reference.singular": "Reference",
"kind.reference.plural": "References",
"kind.typeAlias.singular": "Type alias",
"kind.typeAlias.plural": "Type Aliases",
"kind.typeParameter.singular": "Type parameter",
"kind.typeParameter.plural": "Type parameters"
}
}
Specify the base path for all urls.
Accepts a string value. Defaults to
"undefined"
.
If undefined all urls will be relative.
{
"publicPath": "http://abc.com"
}
Sanitize HTML and JSX inside JsDoc comments.
Accepts a boolean value. Defaults to
false
.
Please note this options does not effect 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 library 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
}
Custom anchor prefix
Accepts a string value. Defaults to
"undefined"
.
This option should be used when parsers require a custom anchor prefix.
{
"anchorPrefix": "markdown-header"
}
Add HTML named anchors to headings and table rows.
Accepts a boolean value. Defaults to
false
.
This option should be used if there are issues with anchoring to symbols within a page.
- For markdown parsers that do not automatically assign header ids.
- When cross referencing symbols that are referenced in a table row.
{
"useHTMLAnchors": false
}
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
}
Configures how the navigation model will be generated.
Defaults to
{"excludeGroups":false,"excludeCategories":false,"excludeFolders":false}
.
By default navigation is not written to file but can be consumed programmatically. Please see Navigation Guide for more information.
navigationModel.excludeGroups
Do not organise navigation by groups.
navigationModel.excludeCategories
Do not organise navigation by categories.
navigationModel.excludeFolders
Excludes unnecessary nesting with complex modules/namespace hierarchies.
{
"navigationModel": {
"excludeGroups": false,
"excludeCategories": false,
"excludeFolders": false
}
}