feat: use starlight-typedoc - #3986 - #4042
Open
FabianLars wants to merge 36 commits into
Open
Conversation
Prototype A of the "build both, then decide" evaluation for the JS API reference direction. Replaces the hand-rolled packages/js-api-generator (which copied starlight-typedoc's internals) with the upstream starlight-typedoc plugin, generating Markdown that Starlight renders natively. - add starlight-typedoc@0.23, typedoc@0.28, typedoc-plugin-markdown@4.12, typedoc-plugin-mdn-links@5.1 (compatible with Starlight 0.41.3) - config/typedoc-plugins.ts: one createStarlightTypeDocPlugin() instance per package (core + fs + autostart slice; flip PROTOTYPE_FULL for all 26). Each package gets its own output dir -- TypeDoc cleans its output dir per run, so a shared dir clobbers. Output URLs kept compatible with today's site. - config/typedoc-tauri-plugin.mjs: non-destructive, reflection-level fix for the '#### Platform-specific' headings that leak into member tables (replaces the old theme's string surgery; no submodule source mutation). - disable packages/js-api-generator in the workspace so its old typedoc@0.26 / typedoc-plugin-markdown@4.2 don't shadow the modern stack. Validated (dev): core / fs / autostart render 200 natively; namespace links resolve (the #3424 blocker is absent in this config); type cross-linking + MDN links work; the Uint8Array<ArrayBuffer> canary renders cleanly with NO submodule patch (git -C packages/plugins-workspace status stays clean). Known gaps (see comparison writeup): full-site links validation + the ~130 existing /reference/javascript links are URL-compatible but member anchors move from a single flat page to per-namespace pages; source links show node_modules .d.ts paths for re-exported types (needs sourceLinkTemplate). Prototype only -- not for merge. Slice = core + fs + autostart.
…green Takes the starlight-typedoc reference from a 3-package slice to production-ready: - config/typedoc-plugins.ts: auto-discover every plugin exposing guest-js/index.ts (drop the hardcoded 26-plugin list + the PROTOTYPE_FULL slice gate). New plugins in the submodule are picked up automatically. - add skipErrorChecking so doc generation isn't coupled to a plugin's own TS errors (e.g. shell's guest-js/init.ts, a webview-injected script with DOM typing gaps). - delete packages/js-api-generator entirely (replaced by the plugin); drop build:references from the build pipeline (starlight-typedoc generates during astro build). Validated: full `astro build` GREEN with starlightLinksValidator ON -- core + 27 auto-discovered plugins generated, 1959 pages, "All internal links are valid" (the ~130 existing /reference/javascript links resolve unchanged -- no rewiring needed, the output is URL-compatible with the old generator). Submodule stays clean. Remaining polish (not blocking): "Defined in" shows node_modules .d.ts paths for types re-exported from @tauri-apps/api (needs per-package sourceLinkTemplate + re-export handling); platform-specific inside member tables is inline bold, not a rich aside.
Some JSDoc comments in the Tauri sources write platform notes as markdown headings, which TypeDoc faithfully renders as real <h4> elements. On /reference/javascript/deep-link/ this turned a support note into a section heading with the anchor #--macos--android--ios-unsupported. The normalizer only matched the exact string "#### Platform-specific", so two variants leaked through: #### Platform-specific: (19 occurrences) #### - **macOS / Android / iOS**: ... (5 occurrences, the reported bug) Widen it to accept an optional trailing colon, and to demote a heading whose body is a list item back to the list item it was meant to be. The latter is unambiguously malformed markdown upstream (a heading cannot contain a bullet), so the rule stays narrow: genuine section headings such as "## Security", "# Examples" and "#### Warning" are left untouched. The underlying typo belongs in tauri-apps/plugins-workspace; this keeps the docs build resilient to it either way. Verified by regenerating deep-link, api and opener: no heading-form platform notes remain in the generated reference, and the bogus anchor is gone from the rendered page.
…Script 7 typescript >= 7 (native compiler) drops the JS compiler API typedoc requires, and pnpm always links a package's typescript peer from its importer's context — no override or packageExtension can redirect it (all three were tried and rejected). Moving the typedoc stack into its own workspace package (the same isolation the old js-api-generator had) lets it keep typescript 5.9 while the repo root uses typescript 7. - resolvePeersFromWorkspaceRoot: the package's @astrojs/starlight -> astro peers link the root instances instead of resolving fresh copies - minimumReleaseAgeExclude for astro: pnpm re-checks release maturity when an already-locked version gains a new importer, and rejects it otherwise
…nerator references
✅ Deploy Preview for tauri-v2 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for tauri-releases canceled.
|
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
This was referenced Aug 11, 2026
…base # Conflicts: # package.json # pnpm-lock.yaml # pnpm-workspace.yaml
Contributor
|
I wonder if it's possible to show the parameter types inline, instead of in a table below 
compared to 
|
Contributor
|
yeah afaik there's an option, btw should I bring it closer to v1 like the example section being up top? |
Contributor
yeah if the parameter types are inlined with just the type references below, then they should be below everything else |
Contributor
|
enum as table expand objects https://deploy-preview-4042--tauri-v2.netlify.app/reference/javascript/api/namespacedpi/ |
Contributor
|
I'm going to |
Contributor
|
Also it seems like currently the functions were shown at the end, would it make sense to show them first? Since most of the useful things we provide are the functions as classes, the types, enums are all helpers |
Contributor
|
you mean this? specifically for this page https://deploy-preview-4042--tauri-v2.netlify.app/reference/javascript/api/namespaceapp/#type-aliases I'd argue that moving functions up would bury the other down below on the TOC. Unless the opposite is also true in other pages (many enum and helpers that hides the function on TOC), in that case either way this would be an issue so it ends as a matter of preference |
Contributor
|
or I could reduce the toc depth to 2 levels |
Contributor
|
Yeah that's what I meant. I wouldn't mind this too much either ways that this should only be for looking up certain APIs anyways |
Contributor
|
@Legend-Master what do you think about the toc depth? It is also possible to remove the 'Functions', 'Enumerations' headings but I tried and it not so clear at glance before/after toc depth (not same image but close) 
before/after toc depth |
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
3 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.
Rebase of #3986
Closes #4052