Skip to content

Latest commit

 

History

History
718 lines (494 loc) · 18.2 KB

options.mdx

File metadata and controls

718 lines (494 loc) · 18.2 KB
Raw

import { Callout, FileTree } from "nextra/components";

Options

These options should be used in conjunction with the core [TypeDoc options](/docs/using-typedoc).

Output Options

outputFileStrategy

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"
}

membersWithOwnFile

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"]
}

flattenOutputFiles

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
}

fileExtension

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"
}

entryFileName

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:

  1. The value of the entryModule option (if defined).
  2. The resolved Readme file (skipped if the readme option is set to none).
  3. The documentation index page.
{
  "entryFileName": "index"
}

entryModule

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"
}

mergeReadme

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
}

excludeScopesInPaths

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
}

UX Options

hidePageHeader

Do not print page header.

Accepts a boolean value. Defaults to false.

{
  "hidePageHeader": false
}

hidePageTitle

Do not print page title.

Accepts a boolean value. Defaults to false.

{
  "hidePageTitle": false
}

hideBreadcrumbs

Do not print breadcrumbs.

Accepts a boolean value. Defaults to false.

{
  "hideBreadcrumbs": false
}

excludeGroups

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
}

useCodeBlocks

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
}

expandObjects

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
}

expandParameters

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
}

parametersFormat

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"
}

propertiesFormat

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"
}

enumMembersFormat

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"
}

typeDeclarationFormat

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"
}

indexFormat

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"
}

textContentMappings

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's ReflectionKind 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"
  }
}

Utility Options

publicPath

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"
}

sanitizeComments

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
}

anchorPrefix

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"
}

useHTMLAnchors

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
}

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
}

navigationModel

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
  }
}