TypeDoc 0.26 Beta

[Gerrit0]

TypeDoc 0.26 is now in beta! :tada:

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, #2521.
• --media, --includes, and --stripYamlFrontmatter options have been removed.

Remaining Work

See the full changelog for additional details.

• [x] Handle @document on classes, interfaces, enums, functions, variables
• [x] Handle relative image and markdown links within documents and comments
• [x] Support setting html: false in markdown-it configuration
• [x] Add option to always create a module, even for a single entry point site.
• [x] Figure out how to handle relative image links in packages mode
• [x] Update documentation
• [x] 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, #2056
• Support packageOptions, #2523
• Support customFooterHtml, #2559
• Handle keyboard focus properly on dropdowns/checkboxes, #2556
• Remove headers improperly used as labels in default theme, #2557
• Fix charset capitalization, #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

[Gerrit0]

0.26.0-beta.2

• Detect relative links in markdown [text](link) and ![text](link) style links and automatically copy referenced files to a media directory under the docs folder.
• Support for partial Korean translations (@XiNiHa)
• Default excludePrivate to true
• Support @hideconstructor, #2577
• Added highlightLanguages option to limit what Shiki languages are loaded (reduces rendering time by ~150ms)

Remaining Work

• [x] Detect relative links in <a href> and <img src>
• [ ] Update docs
• [x] Investigate #2147 (pushed to 0.27)
• [x] Add option for #940
• [x] Update CI to compile/lint with internal strict mode on + off

[dzek69]

Hey, the new project documents feature is shaping up great! Can't wait to finally bump my versions and be able to use the new TypeScript features as well!

I just tried it out and I have some ideas for improvements. Or questions maybe.

I don't really understand the @group tag, @category I get, but I still don't see the connection between project documents and these tags.

I tried various values in the frontmatter section, but regardless of what I do I see all my documents listed alphabetically above the index entry on the menu and no sections on the index page:

I suppose I use them wrong, but nevertheless - I'd be nice to be able to organize the pages into subtrees, maybe with some new property like directory?

Also I'd be great if I could somehow keep the order I defined the files in the array? Cause Getting started should come before Advanced usage, but currently it's the opposite and I can't do anything about it.

[Gerrit0]

I don't really understand the @group tag, @category I get, but I still don't see the connection between project documents and these tags.

For documents added with the projectDocuments option, they aren't useful, where they come in handy is when adding documents associated with some reflection. For example, I used @document in this interface's comment to reference a file:

I tried various values in the frontmatter section, but regardless of what I do I see all my documents listed alphabetically above the index entry on the menu and no sections on the index page:

Lack of sections on the index page looks wrong, I'll have to take a closer look this weekend.

I suppose I use them wrong, but nevertheless - I'd be nice to be able to organize the pages into subtrees, maybe with some new property like directory?

You can do this today by using a / in the document name in the frontmatter. (Note: Only makes a folder in the UI if there is one named for the "folder", or if there are at least two within the "folder")

---
title: Test/Nested
group: Guides
---

This guide will show...

Also I'd be great if I could somehow keep the order I defined the files in the array? Cause Getting started should come before Advanced usage, but currently it's the opposite and I can't do anything about it.

You're after the --sortEntryPoints option, swap that to false and TypeDoc will use the order you listed in the options.

[dzek69]

Thanks, it looks like I can achieve what I wanted already 👍🏻

One bug, in case you missed it, the document folders and the breadcrumbs does not play well together:

[Gerrit0]

One bug, in case you missed it, the document folders and the breadcrumbs does not play well together:

This is because those folders aren't real folders, the "top document" isn't actually a parent. It's just a happy accident of the tree implementation that it allows this to work. The "right" solution would be support for sub-documents, which is probably what I'll go for before merging this feature

[Gerrit0]

0.26.0-beta.3

• Detect relative links in <img> and <a> tags in comments/documents
• Documents may now specify children as an array/object within their frontmatter to add child documents.
• Fixed very slow conversion on Windows where Msys git was used by typedoc to discover repository links, #2586.
• Groups and categories can now be collapsed in the page body, #2330.
• Added --useHostedBaseUrlForAbsoluteLinks option to use the --hostedBaseUrl option to produce absolute links to pages on a site, #940.
• Validation will now be run in watch mode, #2584.
• Added support for documenting individual elements of a union type, #2585. Note: This feature is only available on type aliases directly containing unions.
• TypeDoc will now only render the "Type Declaration" section if it will provide additional information not already presented in the page. This results in significantly smaller documentation pages in many cases where that section would just repeat what has already been presented in the rendered type.
• Fixed an issue where the "On This Page" section would include markdown if the page contained headings which contained markdown.
• Added comment.beforeTags and comment.afterTags hooks for plugin use. Combined with CommentTag.skipRendering this can be used to provide custom tag handling at render time.
• API: DefaultThemeRenderContext.hook must now be passed context if required by the hook.
• API: JSONOutput.SignatureReflection.typeParameter has been renamed to typeParameters to match the JS API.

Remaining Work

Besides updating the website docs, the remaining work is just nice to haves, and can wait if necessary

• [ ] Update website docs
• [x] Fix @link tags on union elements
• [x] Think about #2147 some more, haven't come up with a method I'm happy with yet. (pushed to 0.27)
• [x] Make a bunch of tests for the package plugin, #2586 led to the PackagePlugin code looking very suspicious.

[steve02081504]

@Gerrit0

1. When there is more than one indexable: no split/title between elements in the indexable list. This makes it difficult to read.
2. maybe I want to hide the group attribute when all indexable items are in the same group
3. Some things don't have translation support so I can't add translations to them:
   • Group
   • Example
   • Alias
   • See

[Gerrit0]

When there is more than one indexable: no split/title between elements in the indexable list. This makes it difficult to read.

Fixed!

maybe I want to hide the group attribute when all indexable items are in the same group

It doesn't make sense to include an @group tag for index signatures at all today. @group is for categorizing the children of a reflection, and index signatures are special and are not children, so cannot be grouped, which is why that tag is still present.

Some things don't have translation support so I can't add translations to them:

Fixed! Thanks again for the PR adding a bunch of translations.

[Gerrit0]

v0.26.0-beta.4

This will likely be the last beta before the full 0.26 release, I don't plan on including any additional features to this release. Some docs will likely be updated tomorrow, the remaining throughout this week.

• Fixed @link tags not resolving in comments on union elements
• Broken @link tags will now be validated in readme files
• It is now possible to add translations for tags & reflection flags
• Fixed rendering of multiple index signatures
• Added json5 to default list of highlighted languages (#2593)
• Comments including @import will now be properly ignored (#2594)
• TypeDoc's search for git repositories is now much smarter, and will handle nested repositories
• Cleaned up log messages to make them more internally consistent
• Headers added to the page for block tags now have anchors (#2308)
• Print a summary of warnings/errors after a run, #2581
• Fixed broken icons if a custom theme added scripts to the <head> element, #2589

[Gerrit0]

v0.26.0-beta.5

Well, that didn't take long to prove me wrong... I realized I forgot a bug yesterday as I hadn't written it down, and found more when fixing that.

• If a group like "Methods" is collapsed on the page, and a link to a method is clicked in the index, TypeDoc failed to open the <details> element
• The "Copy" / "Copied" text on codeblocks is now translatable
• The warning if a member is normally hidden due to filter settings, but should be visible as a link was clicked which goes directly to it is now translatable

[Gerrit0]

0.26.0 is out :tada: