v0.23 Beta Release

[Gerrit0]

It's several months later than I really wanted to start this process, but 0.23 is finally nearing completion and is ready for beta release! Please try it out and leave feedback either in comments in this issue, or as new issues.

npm install --save-dev typedoc@beta

This release includes two major efforts. A re-imagined default theme thanks to @futurGH, and a complete revamp of TypeDoc's comment parsing to allow TypeDoc to be compatible with TSDoc.

Theme Rebuild

TypeDoc's current default theme has remained essentially the same for the past 6 years. It worked, but wasn't particularly mobile friendly, with small click targets being clustered together. The new theme resolves this, and also makes better use of large screens.

Before	After

TSDoc Compatibility

In 0.22 and earlier, TypeDoc's comment parser is essentially a line-by-line loop with some regular expressions applied. This does an admirable job of handling most comments, but it is less than ideal when dealing with complicated references. Replacing this with a real parser means that it is possible for TypeDoc to perform much more rigorous validation of comments and distinguish between block/modifier tags.

It is important to note that TypeDoc, while aiming to be compatible with TSDoc, does not require its use. It also does not restrict rendering to TSDoc supported constructs. Comments continue to be rendered via Marked, which means that if Marked supports a feature, TypeDoc generally does too. This is important because many commonly used markdown features are not yet specified by TSDoc (including support for headings, tsdoc/197 and lists tsdoc/178). If this "laxness" isn't acceptable for your use case, I recommend api-extractor.

Important Breaking Changes

• Support for Node 12 dropped - it will be EOL by the time 0.23 releases for real.
• Support for TS < 4.6 dropped
• @inheritDoc now follows the TSDoc specification when copying documentation.
• Support for [[target]] links has been deprecated. Since TypeScript 4.3, the {@link} syntax will be recognized by editors and used to actually create links, and it should be used instead. v0.24 will remove TypeDoc's support for [[target]] links.
• Step four in TypeDoc's link resolution has been removed, which may break some links.
• Comments on export declarations will now only override comments for references and namespaces.
• All top level reflections will now be rendered in their own page. This is more consistent with several other documentation systems and makes exported functions/variables/type aliases no longer feel "tacked on" as is evident with the old system.

New Features

• Added support for the @group tag to override the default grouping by kind (classes, functions, etc.)
• Improved support for several JSDoc style constructs, including detecting @example tags which expect to be treated as code blocks. TypeDoc now matches VSCode's behavior.
• Members marked with @deprecated will now be rendered with a line through their name.
• If parts of a comment will be overwritten by an @inheritDoc tag, TypeDoc will now warn you about it instead of silently overwriting a comment.

Remaining Work

For additional information about resolved bugs and remaining work to be completed before release, see the changelog.

• Update documentation on https://typedoc.org, add a page/section for each special tag recognized by TypeDoc.
• Restore support for {@link} and [[link]] tags in readme files
• Make comment parser options configurable
• Read tsdoc.json for comment parser configuration
• Full support for declaration references (TypeDoc still just splits link targets on . to try to resolve links), #262, #488, #1326, #1845.
• Add support for additional comment styles, #1433
• Add custom rendering for @see tags
• Show toggles for modifier tags and make default visibility features configurable, #1816.

Future work originally considered for this release

• Add support for a @copyDoc inline tag which can be used to pull pieces of documentation from other entries without fully overriding the comment (@inheritDoc is specified by TSDoc to specifically disallow this, so a new tag), #304
• Experiment with a --commentDiscovery option to tell TypeDoc to delegate all comment discovery to TypeScript

[Gerrit0]

Had a bit of time, so beta.1 is now up:

• Added visibilityFilters option which configures which filters are shown under settings. This should be an object which matches the interface:

  interface VisibilityFilters {
    private?: boolean;
    protected?: boolean;
    inherited?: boolean;
    external?: boolean;
    [tag: `@${string}`]: boolean;
  }

• Fixed filter display so that the Private/Protected/Externals filters won't be shown if they can never filter anything

[Gerrit0]

It turns out "full support for declaration references" is quite the rabbit hole... TSDoc initially went with one syntax, the maintainers there are looking at switching to a different (much nicer, and similar to JSDoc) syntax, JSDoc uses a third, VSCode handles things similar-ish to how TypeDoc does it today...

My current plan is for TypeDoc to support the beta syntax that TSDoc does, and fall back to matching like it does today if link resolution fails... life is really busy right now though. I wanted to be at a full release or nearly there by now, but it looks like this won't be fully ready until mid June.

[Gerrit0]

beta.2 (based on 0.22.16)

Breaking:

• In the JSON output for DeclarationReflections, getSignature is no longer a one-tuple.
• In the JSON output for DeclarationReflections, setSignature is no longer a one-tuple.
• In the JSON output for DeclarationReflections, typeParameter has been renamed to typeParameters

Features:

• Merged in master to add support for TypeScript 4.7.
• Added blockTags, inlineTags, modifierTags to control which tags TypeDoc will allow when parsing comments.
  If a tag not in in one of these options is encountered, TypeDoc will produce a warning and use context clues to determine how to parse the tag. (Next: Also pick these up if configured in tsdoc.json)
• TypeDoc will now try to place block elements on a new line in HTML output, resulting in less overwhelming diffs when rebuilding docs, Can the rendered output contain more line breaks? #1923.

Fixed:

• TypeDoc will now automatically inherit documentation from classes implements by other interfaces/classes.
• Fixed @inheritDoc on accessors, inheritdoc doesn't work for getter methods #1927.
• Restored support for [[link]] and {@link} within README.md

[Gerrit0]

The declaration reference rabbit hole is never ending... I'm tempted to implement just the pieces of the TSDoc spec that make sense to me, and wait for feature requests to support more parts of it... In the meantime...

beta.3 (based on 0.22.17)

Breaking:

• Dropped support for TS < 4.6
• defaultValue will no longer be set on reflections with kind ReflectionKind.EnumMember

Features:

• typedoc.json now supports comments, like tsconfig.json
• Support for reading blockTags, inlineTags, and modifierTags from tsdoc.json alongside tsconfig.json
• Added typedoc/tsdoc.json export which can be extended by user tsdoc.json files.

[Gerrit0]

Just two required TODOs left! Granted, one of them is declaration references, which is probably 8 hours of work, and docs always seem to take more time than I predict... getting very close...

beta.4 (based on 0.22.17)

Breaking:

• extends in typedoc.json is now resolved using NodeJS module resolution, so a local path must begin with ./.

Features:

• Entry point strategies Resolve and Expand may now specify globs, Allow use of minimatch pattern #1926.

• Added new commentStyle option which can be used to control what comments TypeDoc will parse.

  Value	Behavior
  JSDoc	Use block comments starting with /**
  Block	Use all block comments
  Line	Use // comments
  All	Use both block and line comments

Fixed:

• The excludeNotDocumented option will no longer hide a module if it has a documentation comment, Empty modules with only top-level docstring are not included #1948.
• Prevent --excludeNotDocumented from hiding properties of type literals (a in function fn(p: { a: string })), Improve the discovery of the doc comment for symbol (or may be a symbol for a doc comment) #1752.
• Module comments will no longer be attached to non-modules in some cases

[Gerrit0]

I believe the only thing left now is to write docs, going to get a healthy start on this today, but likely won't finish... I think pending any bug reports, that this will be the last pre-release for 0.23, which should release sometime this week.

Edit: Or... ya know, when writing docs I could discover half a dozen things that I forgot

beta.5 (based on 0.22.17)

• {@link} tags in comments will now be resolved as declaration references similar to TSDoc's declaration references.

[jlarmstrongiv]

Very nice! I like the theme refresh

I think the only thing that’s harder is jumping around to the different functions, etc. In the last version, the sidebar had all of them, so they were all a click or command+f away. In the new version, I have to click on the package-name / function breadcrumbs in the top of the page to go back and select another function.

Maybe bringing back the longer sidebar, or adding a shortcut to focus the search bar command+/, or adding a command palette would help?

Also, I have bad eyes, and the contrast in dark mode is super strong between the #f3f3f3 text and #141617 background with a WCAG score of 16.34, when 4.5 is passing for small text and 7.0 is enhanced contrast. It would be nice if we could tone it down in the default theme (either a lighter background or greyer text), though I see that I can add a custom css file too.

On mobile, the top navbar covers/hides the top of the page.

Again, overall great! Don’t focus only on the critiques—nice job

[jlarmstrongiv]

Also, what does warning Block and modifier tags will be ignored within the readme. mean?

[Gerrit0]

Thanks for the feedback! It's greatly appreciated.

Maybe bringing back the longer sidebar

Spent some time clicking around TypeDoc's docs with the new vs old, and I agree. Bringing it back...

shortcut to focus the search bar command+/,

Just / will do this already, but it looks like it won't make the header appear if it is hidden, easy bug to fix, will be resolved next beta.

contrast in dark mode is super strong

I am solidly in the "hopeless" side of the scale of color design, do you have a recommendation?

On mobile, the top navbar covers/hides the top of the page.

Oh mobile... fixed!

Also, what does warning Block and modifier tags will be ignored within the readme. mean?

This means that your readme contained something that looked like a @tag to TypeDoc. It could be an email, twitter handle... Just made an update to print out the tags that are being ignored.

[jlarmstrongiv]

Thanks for the feedback! It's greatly appreciated.

Glad it helps!

Spent some time clicking around TypeDoc's docs with the new vs old, and I agree. Bringing it back...

Just / will do this already, but it looks like it won't make the header appear if it is hidden, easy bug to fix, will be resolved next beta.

Oh mobile... fixed!

👍👍👍

I am solidly in the "hopeless" side of the scale of color design, do you have a recommendation?

Sure, I’d recommend looking at other apps in dark mode or using TailwindCSS colors.

• Google Chrome uses #d1d4da on #28292d (AAA 9.78)
• Discord uses #d4d5d7 on #2a2c30 (AAA 9.52)

If you use TailwindCSS colors, say the Slate family, then you could meet accessibility standards by using:

• Slate 800 #1e293b for the background color
• Slate 50 #f8fafc for the one large page title (AAA 15.69)
• Slate 300 #c1ccda for small text and descriptions (AAA 10.15)

Also, is the top navbar a different shade of grey?

This means that your readme contained something that looked like a @tag to TypeDoc. It could be an email, twitter handle... Just made an update to print out the tags that are being ignored.

I think TypeDoc may accidentally be finding npm scopes (namespaces) by mistake, for example @mdx-js/mdx.

In my monorepo, I’m using namespaces for every project. It seems to give me a warning when I have a README with:

# Workspaces CLI

Examples:

- `npx @clis/workspaces dependencies add @configs/stylelint --save-dev`

What’s the best way to suppress those warnings?

[Gerrit0]

What’s the best way to suppress those warnings?

TypeDoc recognizes code blocks, so if in a code block/inline code block, it shouldn't complain about it being a tag. I copied that text into a new project and TypeDoc parses it as expected, with no tags. You can also escape the @ with \@ which most markdown parsers will ignore, so shouldn't have an effect on any other rendered version.

[Gerrit0]

Now it's actually almost here... I just need to make {@label} work and finish writing docs... tomorrow.

beta.6 (based on 0.22.18)

• @deprecated causing names to be crossed out when rendering is now inherited to follow the TSDoc spec
• @inheritDoc now resolves names with declaration references
• Adjusted colors to reduce overly heavy contrast
• searchGroupBoosts now works with groups defined by the @group tag
• The warning about block/modifier tags in the readme will now include the tag names found
• The search bar will now always be shown if focused
• The navigation sidebar will now include parent members if the element being displayed does not contain children
• Text is no longer cut off at the top of the screen on small screen sizes
• Updated default tag definitions to include missing tags supported by TypeDoc
• Support .cts and .mts entry points in packages mode (The file does not contain a sourceMappingURL #1952)

[jlarmstrongiv]

Awesome 🎉

The entry points in packages mode works with .cts 👍
The sidebar is easier to navigate 👍

I am still running into issues with the warnings within code blocks, but only using the entrypoint mode, not packages mode. Both have the inline code block. The warnings print:

warning Block and modifier tags will be ignored within the readme:
@clis
@configs

warning Block and modifier tags will be ignored within the readme:
@clis

using content:

# Workspaces CLI

Helpers for working within all packages in the monorepo:

## Dependencies

- `npx @clis/workspaces dependencies add @configs/stylelint --save-dev`

and

# Dependencies CLI

## Architecture

- `npx @clis/dependencies architecture --filter="@nestjs/example"`

Also, is there a way to ignore a package in the --entryPointStrategy packages globs? It only contains css and a package.json

Thanks again for the exciting beta release 😄

[Gerrit0]

I am still running into issues with the warnings within code blocks

Wow, that was a confusing bug... turns out it was an off by one... only visible if your readme ended with a code block. Fixed with 75cbf1f. I didn't see it earlier because I just stuck your readme at the top of one in a project I had set up. Thanks!

Also, is there a way to ignore a package in the --entryPointStrategy packages globs? It only contains css and a package.json

Currently, it looks like there is not, once a package is added by a glob, there isn't a way to filter it back out. It seems like a reasonable feature request to check --exclude during expansion to me though. PR welcome :)

typedoc/src/lib/utils/entry-point.ts

Lines 292 to 296 in 80fa823

	function getEntryPointsForPackages(
	logger: Logger,
	packageGlobPaths: string[],
	options: Options
	): DocumentationEntryPoint[] | undefined {

[Gerrit0]

beta.7 (based on 0.22.18)

• @label will now be used when resolving declaration references
• Improved error handling for @inheritDoc if declaration references fail to parse.
• Fixed incorrect parse of a comment if it ended with a code block

[jlarmstrongiv]

Wow, that was a confusing bug... turns out it was an off by one... only visible if your readme ended with a code block. Fixed with 75cbf1f. I didn't see it earlier because I just stuck your readme at the top of one in a project I had set up. Thanks!

Woah that’s a weird bug 😂 nice find. Installed the latest beta—fixed!

Currently, it looks like there is not, once a package is added by a glob, there isn't a way to filter it back out. It seems like a reasonable feature request to check --exclude during expansion to me though. PR welcome :)

I’ll see if I can read the contributing doc and add it next week! Thanks for the pointer. Related #1959

[Gerrit0]

0.23 for real is out! 🎉