feat: use starlight-typedoc by vasfvitor · Pull Request #3986 · tauri-apps/tauri-docs

vasfvitor · 2026-07-19T04:49:29Z

there are a few workarounds that I'll see about fixing upstream

depends on #3985

there are slight differences for the better

https://deploy-preview-3986--tauri-v2.netlify.app/reference/javascript/autostart/
https://tauri.app/reference/javascript/autostart/

https://deploy-preview-3986--tauri-v2.netlify.app/reference/javascript/dialog/
https://tauri.app/reference/javascript/dialog/

<T> from Channel being removed is not a regression, was a fix in typedoc
https://deploy-preview-3986--tauri-v2.netlify.app/reference/javascript/api/namespacecore/
https://tauri.app/reference/javascript/api/namespacecore/

todo:
~~bug on code block~~
https://deploy-preview-3986--tauri-v2.netlify.app/reference/javascript/opener/
https://tauri.app/reference/javascript/opener/

new page
https://deploy-preview-3986--tauri-v2.netlify.app/reference/javascript/shell/

netlify · 2026-07-19T04:49:34Z

✅ Deploy Preview for tauri-v2 ready!

Name	Link
🔨 Latest commit	`edc5859`
🔍 Latest deploy log	https://app.netlify.com/projects/tauri-v2/deploys/6a6a3d50f266d800086262e0
😎 Deploy Preview	https://deploy-preview-3986--tauri-v2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 98 (🔴 down 1 from production) Accessibility: 98 (no change from production) Best Practices: 100 (no change from production) SEO: 100 (no change from production) PWA: 80 (no change from production) View the detailed breakdown and full score reports
🤖 Make changes	Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

socket-security · 2026-07-19T04:50:06Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Package	Supply Chain Security	Quality	Maintenance
typedoc-plugin-frontmatter@1.3.1
starlight-typedoc@0.23.0
typedoc-plugin-mdn-links@3.2.11 ⏵ 5.1.1		⁺⁶	^-10
typedoc-plugin-markdown@4.2.6 ⏵ 4.12.0	⁺¹	⁺⁵	^-1
typedoc@0.26.6 ⏵ 0.28.20	⁺¹²

View full report

netlify · 2026-07-21T01:18:45Z

✅ Deploy Preview for tauri-releases ready!

Name	Link
🔨 Latest commit	`edc5859`
🔍 Latest deploy log	https://app.netlify.com/projects/tauri-releases/deploys/6a6a3d5006149d0008764f1f
😎 Deploy Preview	https://deploy-preview-3986--tauri-releases.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

socket-security · 2026-07-21T01:19:21Z

All alerts resolved. Learn more about Socket for GitHub.

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

View full report

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

vasfvitor · 2026-07-24T18:13:15Z

+ * Every transform here is a workaround for a known upstream bug or rough edge, kept in one
+ * place so each can be deleted once fixed at the source. Current inventory:
+ *
+ *  - typedoc-plugin-markdown `escapeChars` (dist/libs/utils/escape-chars.js) escapes
+ *    backticks unconditionally, so inline code in headings and mixed link labels renders
+ *    as literal backticks -> ESCAPED_CODE_SPAN_RE undoes it. (Reported-upstream candidate.)
+ *  - starlight-typedoc appends `:::` aside directives to member comments (libs/theme.ts
+ *    #addDeprecatedAside); with table formats the comment lands in a table cell where a
+ *    block directive cannot parse and leaks as literal text -> TABLE_ASIDE_RE flattens it
+ *    to bold. (Reported-upstream candidate.)
+ *  - typedoc-plugin-markdown emits type expressions as code-span fragments joined by
+ *    escaped angle brackets, which renders as broken-looking chips with literal `<` `>`
+ *    -> mergeGenerics() collapses the safe cases. (Cosmetic; likely by design upstream.)
+ *  - typedoc-plugin-markdown v4 titles every constructor section "Constructor", which is
+ *    ambiguous in the ToC and broke the previous generator's #new-classname anchors
+ *    -> renameConstructorHeading() restores `new ClassName()`. (v4 design change, no
+ *    opt-out found.)
+ *  - TS 5.7+ generic Uint8Array noise, stripped via UINT8_GENERIC_RE (not an upstream
+ *    bug, just a docs-build preference).


I'll review these later. I have annotated here and left for reference

these are from a few issues I noticed visually when navigating and comparing with ours

vasfvitor · 2026-07-24T18:15:57Z

+ * into bold inline text so it reads cleanly in both tables and prose.
+ *
+ * Two variants exist in the sources, both handled here:
+ *   `#### Platform-specific` / `#### Platform-specific:`  -> bold label
+ *   `#### - **macOS / iOS**: Unsupported.`                -> plain list item
+ *
+ * The second form (e.g. deep-link's `isRegistered`) is malformed markdown upstream: a
+ * heading can't contain a list bullet. Left alone it becomes a real `<h4>` with an anchor
+ * like `#--macos--android--ios-unsupported`, so a platform note shows up as a section
+ * heading. We demote it back to the list item it was meant to be. Headings that are
+ * genuine section titles (`## Security`, `#### Warning`, ...) are deliberately untouched.


fixed at tauri-apps/plugins-workspace#3504

well... I would merge this as is but the workaround would display the incorrect behaviour

awaitng plugin-workspace next release to match the code

github-project-automation Bot added this to Documentation Jul 19, 2026

github-project-automation Bot moved this to 🪵 Backlog in Documentation Jul 19, 2026

github-actions Bot assigned vasfvitor Jul 19, 2026

vasfvitor force-pushed the typedoc-starlight-md branch from bdcedc4 to 0ff6f12 Compare July 21, 2026 01:18

vasfvitor mentioned this pull request Jul 21, 2026

update to typescript 7 #3985

Merged

vasfvitor added 15 commits July 22, 2026 22:17

fix

43e2d71

docs(comments): describe the typedoc pipeline standalone, drop old-ge…

41ae482

…nerator references

fix: restore submodule pointers accidentally downgraded in 3f17118

7e5fc51

cleanup

8c7446d

format

ac5d214

add postprocessing for known bugs

6e5cbd7

Update normalize.mjs

1706dff

fixes

a183865

docs: explain resolvePeersFromWorkspaceRoot in workspace config

e9c397b

chore: regenerate lockfile after rebase onto v2 (ts7)

5a54b57

chore(tauri-typedoc): add test script for normalize.test.mjs

0125da5

vasfvitor force-pushed the typedoc-starlight-md branch from 0ff6f12 to 0125da5 Compare July 23, 2026 20:00

vasfvitor added 2 commits July 23, 2026 17:22

use catalog

8e72d1a

Merge branch 'v2' into typedoc-starlight-md

37d3e8e

vasfvitor commented Jul 24, 2026

View reviewed changes

move preference out of normalize

edc5859

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: use starlight-typedoc - #3986

feat: use starlight-typedoc#3986
vasfvitor wants to merge 18 commits into
v2from
typedoc-starlight-md

vasfvitor commented Jul 19, 2026 •

edited

Loading

Uh oh!

netlify Bot commented Jul 19, 2026 •

edited

Loading

Uh oh!

socket-security Bot commented Jul 19, 2026 •

edited

Loading

Uh oh!

netlify Bot commented Jul 21, 2026 •

edited

Loading

Uh oh!

socket-security Bot commented Jul 21, 2026 •

edited

Loading

Uh oh!

vasfvitor Jul 24, 2026

Uh oh!

vasfvitor Jul 24, 2026

Uh oh!

vasfvitor Jul 24, 2026

Uh oh!

vasfvitor Jul 24, 2026

Uh oh!

vasfvitor Jul 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

vasfvitor commented Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify Bot commented Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for tauri-v2 ready!

Uh oh!

socket-security Bot commented Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify Bot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for tauri-releases ready!

Uh oh!

socket-security Bot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vasfvitor Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

vasfvitor Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

vasfvitor Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

vasfvitor Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

vasfvitor Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

vasfvitor commented Jul 19, 2026 •

edited

Loading

netlify Bot commented Jul 19, 2026 •

edited

Loading

socket-security Bot commented Jul 19, 2026 •

edited

Loading

netlify Bot commented Jul 21, 2026 •

edited

Loading

socket-security Bot commented Jul 21, 2026 •

edited

Loading