Generate TypeDoc API Documentation from GitHub Source

[RaananW]

Overhauls the TypeDoc API documentation pipeline to generate docs directly from the actual Babylon.js TypeScript source files instead of CDN-hosted .d.ts declaration files. This produces correct GitHub source links with accurate line numbers and proper module naming.

Breaking Changes

This PR does not generate the typedoc from the BABYLON namespace, which means that old typedoc links are no longer valid!

Motivation

Previously, API docs were generated from .d.ts files fetched from a CDN, which meant:

• "Defined in" source links pointed to declaration files, not the real source
• Line numbers in source links were wrong (declaration files have different line counts)
• Module names appeared as internal paths like packages_dev_core_src instead of @babylonjs/core

What Changed

Source-based Generation

• Shallow git clone of BabylonJS/Babylon.js at the published npm version tag, using sparse checkout to only fetch the needed package directories
• TypeDoc runs against real .ts source, enabling native git integration for correct GitHub links with accurate line numbers
• @module JSDoc tag injection into entry point files so TypeDoc names modules as @babylonjs/core, @babylonjs/loaders, etc. instead of internal monorepo paths
• Configurable multi-package support — 7 packages out of the box: core, loaders, serializers, gui, materials, inspector, viewer

Context-aware Search

• New search overlay component that adapts to the current page:
  • Class/Interface pages: searches members (properties, methods, accessors) with in-page anchor navigation
  • Module pages: filters results to the current module
  • Index/root pages: global search across all modules
• Absolute-positioned floating overlay in the upper-right corner — doesn't consume page width
• Keyboard navigation (arrow keys, Enter, Escape)
• Mobile responsive

Per-module Search Indices

• Build-time HTML parsing generates per-module JSON search index files under public/api-search/<prefix>/
• Manifest file enables lazy loading — the component only fetches data for the module(s) relevant to the current page
• Generated files are gitignored

Routing & UX Fixes

• pages/typedoc/[...id].tsx → pages/typedoc/[[...id]].tsx (optional catch-all) to fix 404 on /typedoc root
• Breadcrumb navigation with proper relative href resolution
• Source link visibility restored (CSS had display: none)
• Turbopack compatibility for fs usage

Dependency Updates

• Updated to TypeDoc 0.28.x, TypeScript 5.9.x, Next.js 16.x, and other major dependency bumps

Packages Covered

Package	npm Name	Monorepo Path
Core	@babylonjs/core	packages/dev/core
Loaders	@babylonjs/loaders	packages/dev/loaders
Serializers	@babylonjs/serializers	packages/dev/serializers
GUI	@babylonjs/gui	packages/dev/gui
Materials	@babylonjs/materials	packages/dev/materials
Inspector	@babylonjs/inspector	packages/dev/inspector
Viewer	@babylonjs/viewer	packages/tools/viewer

Key Files

• configuration/typedoc.config.ts — Package configuration and interfaces
• lib/buildUtils/typedoc.utils.ts — Clone, generation, search index, breadcrumbs, page data
• components/typedocSearch.component.tsx — Context-aware search React component
• pages/typedoc/[[...id]].tsx — API doc page route
• pages/typedoc/apiPage.global.scss — TypeDoc styling overrides

Build Notes

• The git clone is cached in a temp directory and reused if the entry point already exists
• Build time is longer than the old CDN approach since TypeDoc processes real .ts source across all packages
• public/api-search/ directory is generated at build time and gitignored
• npm run clean removes the .temp clone directory

[bjsplat]

snapshot for this PR available at:

https://snapshots-cvgtc2eugrd3cgfd.z01.azurefd.net/DOCS/refs/pull/1551/merge

[Copilot]

Pull request overview

This PR refactors the TypeDoc generation pipeline to build API docs from the real Babylon.js TypeScript sources (via a shallow/sparse git clone) instead of CDN .d.ts files, and adds a new context-aware search UI with build-generated per-module search indices.

Changes:

• Generate TypeDoc from cloned Babylon.js repo source and adjust routing/breadcrumb behavior for /typedoc root.
• Add TypeDocSearch overlay with global/module/member search behavior backed by per-module JSON indices generated at build time.
• Update ignore rules and scripts (including a new clean script) to support the new .temp and search-index outputs.

Reviewed changes

Copilot reviewed 7 out of 10 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
lib/buildUtils/typedoc.utils.ts	Switch TypeDoc generation to a shallow/sparse clone of Babylon.js source; add per-module search-index generation; adjust breadcrumbs and lowercase-redirect logic.
configuration/typedoc.config.ts	Introduce typed configuration for packages, repo, and version resolution for TypeDoc generation.
components/typedocSearch.component.tsx	New search overlay component with context-aware behavior and keyboard navigation.
pages/typedoc/[[...id]].tsx	Optional catch-all route support for /typedoc, plus embedding the search overlay.
pages/packages/viewer/[...id].tsx	Update viewer TypeDoc generation call signature and embed the search overlay.
pages/typedoc/apiPage.global.scss	Restore “Defined in” source link visibility by showing .tsd-sources li.
.gitignore	Ignore generated per-module API search index output under public/api-search/.
package.json	Add clean script for removing .temp and .next.
package-lock.json	Lockfile updates due to dependency/tooling changes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bjsplat]

snapshot for this PR available at:

https://snapshots-cvgtc2eugrd3cgfd.z01.azurefd.net/DOCS/refs/pull/1551/merge