TypeDoc 0.26 Beta

[Gerrit0]

TypeDoc 0.26 is now in beta! 🎉

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

npm install --save-dev typedoc@beta

The full release will be made on 2024-06-21.

This release includes support for TypeScript 5.5 in addition to two large features

External Markdown Pages

It has been a highly requested feature for TypeDoc to support including additional markdown pages beyond just the project's readme. In fact the original issue requesting them, #247, is the oldest issue still open. There have been a few external plugins over the years which added this, then broke with TypeDoc updates, but it's now coming to TypeDoc proper!

This feature falls into two parts:

1. Project level documents
2. Reflection level documents

Project level documents can be added with the --projectDocuments option. These documents will be added as children of the root reflection object, so are a good fit for guides on how to use the library and other top level pages that should be included in your docs.

Reflection level documents can be added as children to declarations with the @document tag. These are intended for referencing lower level documents which are relevant when viewing documentation for that item. Note: "top level" declarations is a somewhat tricky term. The initial implementation of this feature only supports

The markdown pages added may include YAML formatted frontmatter. TypeDoc will check the frontmatter for title, group, and category properties. The title property will set the name of the document used, while group and category are treated like the @group and @category tags on a normal reflection.

Note: This frontmatter must begin and end with --- on lines by itself. TypeDoc's frontmatter extraction uses this to determine when the block ends.

Example:

/**
 * @document relative/path/to/document.md
 */
namespace Foo {}

---
title: Document name
group: Guides
---

This guide will show...

Localization Support

TypeDoc has always been an English project, without any real support for other languages. This version sets up the infrastructure to support changing rendered text and TypeDoc's log messages to other languages. See internationalization.md for details. Translation PRs are welcome!

Important Breaking Changes

• Dropped support for Node 16
• Moved from marked to markdown-it for parsing markdown. TypeDoc has been on an old version of Marked for a while now to avoid breaking changes they made which turned parsing from a synchronous approach to potentially async. Supporting async code in TypeDoc's renderer is currently infeasible. Markdown-it also supports plugins which extend markdown and can be used within TypeDoc to add custom rendering of syntax within comments.
• Updated Shiki from 0.14 to 1.x, this should mostly be a transparent update which adds additional languages and themes.
• All function-likes may now have comments directly attached to them. This is a change from previous versions of TypeDoc where functions comments were always moved down to the signature level. This mostly worked, but caused problems with type aliases, so was partially changed in 0.25.13. This change was extended to apply not only to type aliases, but also other function-likes declared with variables and callable properties. As a part of this change, comments on the implementation signature of overloaded functions will now be added to the function reflection, and will not be inherited by signatures of that function, const interpreted as function typed via an interface declaration, yield unexpected comment summaries #2521.
• --media, --includes, and --stripYamlFrontmatter options have been removed.

Remaining Work

See the full changelog for additional details.

• Handle @document on classes, interfaces, enums, functions, variables
• Handle relative image and markdown links within documents and comments
• Support setting html: false in markdown-it configuration
• Add option to always create a module, even for a single entry point site.
• Figure out how to handle relative image links in packages mode
• Update documentation
• Add option to specify what highlight languages are loaded. Shiki 1.x takes ~250ms longer to load than 0.14 due to loading more languages, the majority of which won't be used by a TS project.

[Gerrit0]

0.26.0-beta.1

• Handle @document on more reflection types
• Add a warning if an unrecognized block tag is used (likely needs adjustment before full release, I suspect several JSDoc tags are missing from TypeDoc's list of known tags)
• Support cascading modifier tags, Cascade namespace tags to individual API members in rendered doc #2056
• Support packageOptions, Add packageOptions config value for packages mode #2523
• Support customFooterHtml, Suggestion: Custom footer string #2559
• Handle keyboard focus properly on dropdowns/checkboxes, keyboard focus is not visible on the settings dropdown and checkboxes present in the setting dropdown.  #2556
• Remove headers improperly used as labels in default theme, Ensures select element has an accessible name. #2557
• Fix charset capitalization, <meta charSet="utf-8"/> The attribute name of [ charSet ] must be in lowercase.(attr-lowercase) #2568
• Allow users to set markdown-it's html option (will probably default this to true so that TypeDoc can color links in readme files which point to a specific type of reflection, currently defaulted to false)
• Implicitly add a trailing slash to hostedBaseUrl
• Added alwaysCreateEntryPointModule option to control how TypeDoc behaves when only one entry point is provided

... and now I probably disappear for 2 weeks and don't do anything, except maybe fix bugs people find ;)

[bndkt]

@Gerrit0 I'm excited to try packageOptions in Beta 2, but it seems the npm publish failed.

[Gerrit0]

Sorry about that! Should be up now.

I suspect I might need to revert the block tag validation change, or at least rework it, as I forgot about how special inheritDoc is