TypeDoc 0.27 is now in beta! :tada:

Please try it out and report any issues in new issues:

npm install --save-dev typedoc@beta

The full release will be made on 2024-11-21 (TS 5.7 release date, may be pushed if TS pushes)

This release mainly focuses on improved flexibility for type conversion and several improvements to the default theme, but also makes some changes to output.

Conversion Flexibility

TypeDoc uses the compiler to retrieve the types of documented members, and converts them into a simplified structure for rendering. Historically, not much flexibility has been exposed to control this behavior. v0.24 added support for @interface to tell TypeDoc to treat a type alias as if it was an interface, and @namespace to convert variables as namespaces. v0.27 extends this support with some additional tags:

@expand - tells TypeDoc to also render details about the properties of this type when rendering references to this type.
@inline - tells TypeDoc to replace references to this type with a copy of the referenced type.
@useDeclaredType - tells TypeDoc to use TypeScript's getDeclaredType method to get types for conversion. Using this on a mapped type will cause the evaluated type to be rendered. Note: This can sometimes produce worse documentation, the most common error case is that it will render as a self-reference.

Default Theme Changes

This release includes quite a few quality of live improvements to the default theme:

Reworked Modules Page

Modules/namespace pages have been re-worked to be more generally useful. The @summary tag can now be used to define a "short summary" for a reflection, which will be rendered on the modules page, or the useFirstParagraphOfCommentAsSummary option can be set to automatically use the first paragraph of a reflection's comment as the summary. Re-exports (like CommentStyle below) will be rendered with an arrow pointing to the canonical export.

Expanded References

If @expand is used on a type alias or interface, references to it will be expanded. In the screenshot below the @expand tag was placed on InlineTagDisplayPart and RelativeLinkDisplayPart. This screenshot also shows how TypeDoc can render comments for each branch of a union at the root level of a type alias.

Code

```ts /** * Represents a parsed piece of a comment. * @category Comments * @see {@link JSONOutput.CommentDisplayPart} */ export type CommentDisplayPart = /** * Represents a plain text portion of the comment, may contain markdown */ | { kind: "text"; text: string } /** * Represents a code block separated out form the plain text entry so * that TypeDoc knows to skip it when parsing relative links and inline tags. **/ | { kind: "code"; text: string } | InlineTagDisplayPart | RelativeLinkDisplayPart; /** * Represents an inline tag like `{@link Foo}` * * The `@link`, `@linkcode`, and `@linkplain` tags may have a `target` * property set indicating which reflection/url they link to. They may also * have a `tsLinkText` property which includes the part of the `text` which * TypeScript thinks should be displayed as the link text. * @category Comments * @expand */ export interface InlineTagDisplayPart { kind: "inline-tag"; tag: `@${string}`; text: string; target?: Reflection | string | ReflectionSymbolId; tsLinkText?: string; } ```

Smarter Code Rendering

When TypeDoc renders types, it used to apply some very basic rules about when to wrap a type to multiple lines, namely deciding to wrap object types and top level unions on every line, and placing all other types on the same line. This mostly worked, but could also cause very messy rendering. TypeDoc now uses an algorithm similar to prettier, which can be controlled with the typePrintWidth option to determine when types should be wrapped.

Along with this change, TypeDoc will now be smarter when deciding whether or not to recurse into types to render additional details about them. This is most obvious when viewing documentation for functions which accept or return functions or objects with functions. TypeDoc will still render the full details if it detects that there is additional details provided via documentation comments (either directly or via @expand) within the type.

Old	New
Note: This is only about half of the rendered signature

Alerts

GitHub supports alerts to call out important information. TypeDoc now supports the same format in comments and markdown documents and will render them in a similar way.

Outputs

TypeDoc supports both HTML and JSON outputs, but if a plugin (e.g. typedoc-plugin-markdown) wanted to add an additional output type, there wasn't an obvious place to hook into the API to expose it to users. TypeDoc now supports the idea of a generic output for a project, which also makes it possible to render TypeDoc's output multiple times with different settings.

The options key is optional, and may include any TypeDoc option, though users should be aware that options which are used during conversion will be effectively ignored if set under outputs.

// typedoc.json
{
    "outputs": [
        {
            "name": "html",
            "path": "../docs"
        },
        {
            "name": "html",
            "path": "../docs-grouped-nav",
            "options": {
                "navigation": true
            }
        },
        {
            "name": "json",
            "path": "../docs/docs.json"
        }
    ],
}

Change Log

Breaking Changes

Relaxed requirements for file names and generated url fragments. This may result in a different file name structure, #2714.
Anchors to document headings and reflections within a HTML generated pages have changed. They can be partially restored to the previous format by setting --sluggerConfiguration.lowercase false. This change was made to more closely match the default behavior of GitHub's markdown rendering and VSCode's autocomplete when creating a relative link to an external markdown file.
Removed the hideParameterTypesInTitle option, this was originally added as a workaround for many signatures overflowing the available horizontal space in rendered pages. TypeDoc now has logic to wrap types/signatures smartly, so this option is no longer necessary.
Changed the default kindSortOrder to put references last.
Changed the default sort order to use alphabetical-ignoring-documents instead of alphabetical.
Changed default of suppressCommentWarningsInDeclarationFiles to true
API: Constructor signatures now use the parent class name as their name (e.g. X, not new X)
API: @group, @category, @groupDescription and @categoryDescription will no longer be removed from the reflections they are present on. They are skipped during rendering with the notRenderedTags option.

Features

TypeDoc will now discover entry points from package.json exports if they are not provided manually, #1937.
Relative links to markdown files may now include #anchor links to reference a heading within them.
Improved support for @param comments with nested object types, #2555.
Improved support for @param comments which reference a type alias/interface. Important properties on the referenced type can now be highlighted with @param options.foo, which will result in the additional note being included under the documentation for that parameter, #2147. Note: This feature is limited to references. It is not supported on other types of types.
Added a new outputs option which is an array of outputs. This can be used to render the documentation multiple times with different rendering options or output types, #2597.
Added support for rendering alerts (or callouts) in markdown.
Add support for an @expand tag which can be placed on type aliases and interfaces. When a type with @expand is referenced and TypeDoc has a place to include additional details about the type, the properties of the type will be included in the page where @expand is found. Note that use of this tag can significantly increase the size of your generated documentation if it is applied to commonly used types as it will result in inlining the comments for those types everywhere they are referenced, #2303.
Add support for an @inline tag which can be placed on type aliases and interfaces. When a type with @inline is referenced, TypeDoc will resolve the referenced type and convert the type as if it was included directly within the referencing type. Note that use of this tag can significantly increase the size of your generated documentation if it is applied to commonly used types as it will result in inlining the comments for those types everywhere they are referenced, #2303.
Introduced a new @useDeclaredType tag for type aliases which can sometimes improve their documentation, #2654..
Added a new @mergeModuleWith tag which can be used to tell TypeDoc to place a module/namespace's children under a different module/namespace and remove the real parent, #2281.
Add notRenderedTags option. This option is similar to the excludeTags option, but while excludeTags will result in the tag being completely removed from the documentation, notRenderedTags only prevents it from being included when rendering.
Added groupReferencesByType option.
Added navigation.excludeReferences option
Added useFirstParagraphOfCommentAsSummary option to configure how TypeDoc handles comments for module members without the @summary tag.
Introduced favicon option to specify a .ico or .svg favicon to reference.
Sections within the page and in the "On This Page" navigation are now tied together and will expand/collapse together, #2335.
API: Introduced a new app.outputs object for defining new output strategies.

Bug Fixes

TypeDoc will now use the first signature's comment for later signatures in overloads if present, #2718.
Fixed handling of @enum if the type was declared before the variable, #2719.
Fixed empty top level modules page in packages mode, #2753.
TypeDoc can now link to type alias properties, #2524.
Fixed an issue where properties were not properly marked optional in some cases. This primarily affected destructured parameters.
Added yaml to the highlight languages supported by default.
TypeDoc now recognizes txt as an alias of text to indicate a code block should not be highlighted.
Items which are hidden with @ignore or @hidden but still referenced by other types will no longer produce warnings about not being exported.
If a project only has one module within it, TypeDoc will now consider that module when resolving @link tags.
The arrows to indicate whether or not a section is open now work when JavaScript is disabled.
Group/category search boosts are now applied when writing the search index rather than when converting. This prevents issues where boosts used by just one package were incorrectly reported as unused when running with entryPointStrategy set to packages.

TypeStrong / typedoc

TypeDoc 0.27 Beta #2763