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

[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, Support @hideconstructor JSDoc tag to hide constructors from classes. #2577
• Added highlightLanguages option to limit what Shiki languages are loaded (reduces rendering time by ~150ms)

Remaining Work

• Detect relative links in <a href> and <img src>
• Update docs
• Investigate Support for documenting params with named types #2147 (pushed to 0.27)
• Add option for Use absolute URL's for the assets #940
• 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, Typedoc took 2.5 hours in conversions #2586.
• Groups and categories can now be collapsed in the page body, Make page sections (including groups/categories) collapsible in the main page body #2330.
• Added --useHostedBaseUrlForAbsoluteLinks option to use the --hostedBaseUrl option to produce absolute links to pages on a site, Use absolute URL's for the assets #940.
• Validation will now be run in watch mode, Should validation work in watch mode? #2584.
• Added support for documenting individual elements of a union type, How to document each type in `export type Foo = 'foo1' | 'foo2'? #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
• Fix @link tags on union elements
• Think about Support for documenting params with named types #2147 some more, haven't come up with a method I'm happy with yet. (pushed to 0.27)
• Make a bunch of tests for the package plugin, Typedoc took 2.5 hours in conversions #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 (0.26 Beta: Add json5 to defaults in option declaration for highlightLanguages . #2593)
• Comments including @import will now be properly ignored (0.26 Beta: TS 5.5 @import comments passthrough in declarations to documentation. #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 (Add ids to tag-generated headers #2308)
• Print a summary of warnings/errors after a run, Feature request: display warning and error count like eslint. #2581
• Fixed broken icons if a custom theme added scripts to the <head> element, Plugins: Icons invisible when a large script is added on head.end #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 🎉