TypeDoc 0.27 Beta

[Gerrit0]

TypeDoc 0.27 is now in beta! 🎉

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

/**
 * 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, The document's name appears as ____ #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, Support for package exports map #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, Nested object parameter descriptions are not included in the output #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, Support for documenting params with named types #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, Decouple Renderer class from HTML output #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, Expand union types #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, Expand union types #2303.
• Introduced a new @useDeclaredType tag for type aliases which can sometimes
  improve their documentation, Way to expand complex type aliases (Awaited, ReturnType, typeof etc.) #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, Support for merging modules together with @module #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, [Discussion] Default Modern Theme + complete / linkable built-in TS lib docs. #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, Use the comment for the first signature if a later signature does not have a comment #2718.
• Fixed handling of @enum if the type was declared before the variable, @enum incorrectly handles type declared before value #2719.
• Fixed empty top level modules page in packages mode, Blank modules page at top level #2753.
• TypeDoc can now link to type alias properties, Cannot link to default property #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.

[Gerrit0]

I was hoping to get this out with the TS release, but want to give a few days to update plugins, as the past couple weeks have kept me entirely too busy, so I didn't get the rest of 0.27 finished until just a few minutes ago... sorry about that! The downside of hobby projects..

Planning on Monday/Tuesday for this release now.

0.27.0-beta.1

• Drop support for TypeScript <5.0, no longer supported by DefinitelyTyped (once TS 5.7 releases)
• Add support for TypeScript 5.7
• TypeDoc now properly flags readonly index signatures.
• Expandable class hierarchy, Expandable Hierarchy Section #2744
• Fix infinite loop when handling @mergeModuleWith if targeting a non-toplevel module, Update Chinese translations #2776
• Fix inconsistency with handling of global symbols, Global namespaces from script files and module files via declare global considered different #2774
• Tag name instead of tag target name is added to class names, Use tag instead of display name as class name #2772
• Separated output shortcut --html for HTML output, --out may now be reused by plugins (e.g. typedoc-plugin-markdown) for the default output, Create dedicated html outputShortcut #2769

[blutorange]

Nice work! I tried the beta version and everything seemed to be working smoothly.

I suppose you're aware of it, but since I didn't see it mentioned explicitly: Typedoc is now distributed as ESM, not CommonJS anymore, resulting in some plugins such as typedoc-plugin-merge-modules that still use CommonJS not working anymore. They just need to be converted to ESM as well and everything works again.

[Gerrit0]

Thanks for that note! I'm not sure how I missed that in the list of breaking changes, it absolutely should be called out.

[Gerrit0]

Didn't think there was going to be another beta release before the full one, but there were a couple issues which got in the way when updating a plugin.

v0.27.0-beta.2

• Fixed broken generation of search indices
• declare module "foo" will now create a module, Extraneous quotation marks with declare module "name" #2778
• Fix conversion of import types with qualifiers, Type alias with an import type links to the module, not the referenced type #2779
• Removed dependency on resolve-import by implementing it myself, 28 dependencies aren't worth 140 lines of code
• Downgrade Minimatch to restore support for Node 18
• Create and use a @gerrit0/mini-shiki package instead of directly using shiki to remove 35 unused dependencies from install

[Gerrit0]

0.27 release is out!