Modernize documentation build architecture by RaananW · Pull Request #1580 · BabylonJS/Documentation

RaananW · 2026-05-20T12:54:15Z

Summary

This draft PR modernizes the documentation site architecture while preserving the existing static export deployment model. It introduces a clearer separation between markdown compilation, typed content discovery, validation, static artifact generation, TypeDoc generation, docs-page UI state, and future App Router migration planning.

The goal is to make the documentation build easier to reason about, easier to validate, and less dependent on route-level side effects, without changing the server architecture or requiring SSR/ISR.

Why this is better and more stable

Keeps output: "export" as the deployment contract and validates that the site still builds as static HTML.
Centralizes markdown compilation so home/docs/tests use the same pipeline instead of subtly different parsing paths.
Adds a typed content graph as the source of truth for route manifests, breadcrumbs, examples, and navigation data.
Adds a content validation gate before build output is generated, catching broken links, invalid structure entries, frontmatter issues, and incomplete example metadata earlier.
Makes generated artifacts explicit through dedicated scripts for content, sitemap, search data, example preview images, TypeDoc, and App Router evaluation.
Moves TypeDoc generation out of route utilities, so pages read prebuilt artifacts instead of mixing generation logic with static path discovery.
Isolates docs-page UI concerns under features/docs, reducing the size and responsibility of the catch-all docs route.
Evaluates App Router migration readiness without adding conflicting app/ routes in this branch.

Main changes

Added shared markdown helpers under lib/markdown.
Added typed content graph, static artifact, example image, and validation utilities under lib/contentGraph.
Added explicit build scripts:
- build:content
- validate:content
- build:sitemap
- build:search
- build:typedoc
- build:example-images
- check:example-images
- evaluate:app-router
Refactored docs rendering into features/docs providers/components/hooks.
Split TypeDoc route-safe artifact readers from build-only TypeDoc generation utilities.
Added regression tests for the content graph, artifact generation, validation, docs UI feature helpers, TypeDoc artifacts, and App Router evaluation.
Added documentation-modernization-plan.md as the shared implementation and verification record.

App Router evaluation result

The static data pipeline is now ready for a dedicated App Router proof branch, but this PR intentionally does not migrate production routes to App Router.

The evaluation found that equivalent app/ routes cannot coexist with the current pages/ routes at the same URLs, and the shared shell still needs client/server boundary cleanup first. A future migration should happen in a focused proof branch with route-output comparisons before replacing production routes.

Validation

Completed during the phase work:

npm run evaluate:app-router
npm test
npm run build
git diff --check

The build still completes as a static export. Existing content warnings remain visible, but they are surfaced by the new validation flow rather than introduced by this PR.

bjsplat · 2026-05-20T13:03:12Z