Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
🚀 Deploying Preview to Cloudflare 🚀Preview Deployments by commit
|
This was referenced Oct 1, 2026
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## main #1125 +/- ##
==========================================
- Coverage 92.64% 92.50% -0.14%
==========================================
Files 244 263 +19
Lines 23113 25292 +2179
Branches 2263 2502 +239
==========================================
+ Hits 21412 23397 +1985
- Misses 1692 1872 +180
- Partials 9 23 +14 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Contributor
|
| File | Main | PR | Change |
|---|---|---|---|
orama-db.json |
9.55 MB | 9.55 MB | -153.00 B (-0.0%) |
Performance estimate (single CI run)
- Generation time: 47.1% slower (6.41 s → 9.43 s)
- Peak memory: 7.8% lower (1.63 GB → 1.50 GB)
web Generator
Performance estimate (single CI run)
- Generation time: 3.7% slower (51.81 s → 53.72 s)
- Peak memory: 1.3% lower (3.25 GB → 3.20 GB)
avivkeller
self-requested a review
October 1, 2026 13:37
ovflowd
marked this pull request as ready for review
October 1, 2026 14:15
A TypeDoc plugin with a `doc-kit` output: one page per export, with doc-kit signatures, typed lists, stability indices and source links, plus a type map and a page list. Members of chosen types (a bundler's options, say) can have pages of their own, listed and linked wherever the type appears. Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
avivkeller
requested changes
Oct 2, 2026
avivkeller
left a comment
avivkeller
left a comment
Member
There was a problem hiding this comment.
This is a first pass, and I didn't look at all the files.
From trying to change webpack-doc-kit to use this library, note that:
collectDeclarationsonly reads the direct children of the project, or of its entry-point modules. webpack exports 28 nested namespaces (optimize,container,javascript,cli,util,sources, etc).- Enums and namespaces are not in
PAGE_KINDS(Intentional?) - Accessors render as
{unknown}type - Call signatures of interfaces are dropped.
signaturesOfignores named function types.StatsObject(webpack type) gives an invalid toutput ypedocKitMemberAnchorsshouldn't exist, IMO, it should always betrue, since things like{@link Compiler.run}break without it- Type-map URLs assume doc-kit's input root is the site root.
- Source links are relative to the host's Git root. IMO it should be relative to a provided value
As an aside, export= isn't properly handled, but I'd argue that's an issue for a project using the poor syntax over a issue here.
| "typedoc": "^0.28.0" | ||
| }, | ||
| "devDependencies": { | ||
| "typedoc": "^0.28.20", |
Member
There was a problem hiding this comment.
Why is this version and the version in peerDependencies differenrt?
Comment on lines
+17
to
+20
| "exports": { | ||
| ".": "./src/index.mjs", | ||
| "./package.json": "./package.json" | ||
| }, |
Member
There was a problem hiding this comment.
Is this needed, or is main enough for this package?
Comment on lines
+13
to
+15
| "test": "node --test \"src/**/*.test.mjs\"", | ||
| "test:update-snapshots": "node --test --test-update-snapshots \"src/**/*.test.mjs\"" | ||
| }, |
Member
There was a problem hiding this comment.
Suggested change
| "test": "node --test \"src/**/*.test.mjs\"", | |
| "test:update-snapshots": "node --test --test-update-snapshots \"src/**/*.test.mjs\"" | |
| }, | |
| "test": "node --experimental-test-module-mocks --test \"src/**/*.test.mjs\"", | |
| "test:update-snapshots": "node --test --experimental-test-module-mocks --test-update-snapshots \"src/**/*.test.mjs\"" | |
| }, |
|
|
||
| The output directory receives: | ||
|
|
||
| - A page per exported function, class, interface, type alias and variable: `Function.build.md`, `Interface.BuildOptions.md`, … |
Member
There was a problem hiding this comment.
Is this the format we want? [Type].[Name].md?
Not functions/build.md?
|
|
||
| ## Options | ||
|
|
||
| - `docKitBasePath` {string} The URL path the pages are served under. **Default:** the output directory's name (`/api`). |
Member
There was a problem hiding this comment.
TypeDoc provides a basePath, how is this different? Can we use TypeDoc's?
| * @param {string} file | ||
| * @param {string} contents | ||
| */ | ||
| export const writeIfChanged = async (file, contents) => { |
Member
There was a problem hiding this comment.
We should always write, like we do in the other generators, why are we unique here?
| * @param {string} directory | ||
| * @param {Map<string, string>} files The files about to be written | ||
| */ | ||
| export const removeStalePages = async (directory, files) => { |
Member
There was a problem hiding this comment.
IMO this is out of our scope, our plugin shouldn't be managing the filesystem outside of what it needs to.
| return ['', markdown]; | ||
| } | ||
|
|
||
| const end = /\n\s*\n/.exec(markdown); |
Comment on lines
+4
to
+20
| /** The URL path the pages are served under (`/reference`) */ | ||
| docKitBasePath: string; | ||
| /** The URL of the site (`https://rolldown.rs`) */ | ||
| docKitSiteUrl: string; | ||
| /** Types whose members each have a page of their own (`InputOptions`) */ | ||
| docKitMemberPages: string[]; | ||
| /** The name members of a type are documented on, by type name */ | ||
| docKitReceivers: Record<string, string>; | ||
| /** Event emitters, mapped to the type mapping their events to their arguments */ | ||
| docKitEvents: Record<string, string>; | ||
| /** Types whose members take their signatures from another type's members */ | ||
| docKitSignatureSources: Record<string, string>; | ||
| /** The import path of each entry point, by file */ | ||
| docKitImportPaths: Record<string, string>; | ||
| /** Whether members get an anchor of their name alone */ | ||
| docKitMemberAnchors: boolean; | ||
| } |
Member
There was a problem hiding this comment.
docKitImportPaths: TypeDoc's built-in@moduletagdocKitEvents:class Watcher extends EventEmitter<WatcherEvents>carries the event map inextendedTypes[0].typeArguments.docKitMemberAnchors: This seems redundant...docKitSiteUrl: We don't need the URL, do we? Can't we just use/?
etc
these options feel confusing
Comment on lines
+46
to
+56
| export interface PageEntry { | ||
| name: string; | ||
| /** The kind of the declaration (`Function`), or `Member` for a member page */ | ||
| kind: string; | ||
| url: string; | ||
| category?: string; | ||
| /** The type a member page belongs to */ | ||
| owner?: string; | ||
| /** Whether the page only refers to the member page documenting the type */ | ||
| inlined?: boolean; | ||
| } |
Member
There was a problem hiding this comment.
This feels almost "too large", is all this info needed?
Member
|
I didn't want to push directly to your branch (although I will if you give me the OK), but here's how I would resolve most of these concerns |
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This PR adds
@doc-kit/typedoc, a TypeDoc plugin that writes the API reference of a TypeScript project as doc-kit Markdown, so TypeScript projects get doc-kit's signatures, typed lists, stability indices and source links straight from their sources.It registers a
doc-kitoutput (outputs: [{ name: 'doc-kit', path: 'docs/api' }]) that writes:`build(options[, extra])`heading + typed list),{Type}annotations,> Stability:from@deprecated/@experimental,source_link, and@example/@see/@throws. Custom block tags render as**Tag:** content.type-map.jsonfor doc-kit'stypeMap, andpages.json(every page with its kind, URL and@category) for sites to build their navigation from.A few
docKit*options cover what bigger APIs need. The main one isdocKitMemberPages: members of chosen types (e.g. a bundler's options) get a page of their own, and the type's page, the types extending it and the parameters typed with it list them as linked one-liners instead of repeating their docs. The others handle event emitters (Event:entries from an event-map type), receivers (this.resolve()instead ofpluginContext.resolve()), signatures taken from another type, import paths and legacy member anchors. They're all documented in the package's README.Some notes:
typedoc --watchworks nicely withnode --watchon doc-kit.reflection.variant,type.type) instead ofinstanceof, so it still works when the plugin resolves a different TypeDoc copy than the host (linked packages, strict package managers).This is part of a proof of concept of migrating rolldown.rs from VitePress to doc-kit. There it replaces ~1,100 lines of Rolldown-specific TypeDoc → doc-kit conversion with this plugin and a small
typedoc.config.mjs.Validation
@deprecated,@experimental,@default, a custom tag) and snapshotting every generated file.**Kind:** async parallel), and member lists are titled "Properties".Related Issues
Part of the Rolldown docs migration PoC: rolldown/rolldown#11072. It's the base of a stack: #1125 (TypeDoc plugin) → #1126 (Graphviz diagrams) → #1127 (llms-full), each targeting the one below, with this one targeting
main. The changes don't depend on each other, the stack just keeps them reviewable one at a time while the Rolldown PoC builds from the top branch.Check List
node --run testand all tests passed.node --run format:check&node --run lint.