Babylon.js documentation website

Requirements

• Node.js 24.x (used by CI and supported by the build and test tools)
• npm 11.10.0 or newer (required to enforce the seven-day release-age policy)

Getting Started

Install dependencies

npm install

Run the development server:

npm run dev

Open http://localhost:3000 with your browser to see the result.

You can start editing the page by modifying pages/index.js. The page auto-updates as you edit the file.

Static artifacts

The regular build keeps expensive or deployment-specific artifacts out of local page generation:

npm run build

The sitemap is generated by the Azure Pipelines master build before static export:

npm run build:ci

Static export snapshots are uploaded by azure-pipelines.yml after the build succeeds. Pull request builds also receive a GitHub comment with the uploaded snapshot path. Configure these Azure Pipeline variables:

• DEPLOYMENT_SERVER
• DEPLOY_TOKEN
• GITHUB_SERVICE_CONNECTION

Master builds run npm run build:ci, upload the generated static export, and purge the documentation CDN.

Playground and editor preview snapshots are generated only when explicitly requested. To see which snapshots are missing without launching a browser:

npm run check:example-images

To generate missing snapshots under public/img/playgroundsAndNMEs, run:

npm run build:example-images

Useful options:

npm run build:example-images -- --dry-run
npm run build:example-images -- --dry-run --strict

Generated snapshot images are normal static assets and should be reviewed and committed when intentional.

Readable HTML

Documentation content must be present in the exported HTML, not only in __NEXT_DATA__ or added after JavaScript runs. This lets non-JavaScript readers, including search crawlers and AI agents, read the same articles as browsers. Keep the app-wide theme provider server-rendered; limit client-only rendering to interactive widgets, never a wrapper around page content. MUI's initialization script runs before the page content is painted and sets data-theme using the existing theme storage key or the system preference. Both color schemes are exported in the document head as CSS variables, including custom documentation colors, so readers see the correct colors without waiting for React hydration. Use theme.vars for color tokens and useColorScheme for the toggle state; do not branch rendered styles on theme.palette.mode. The exported document sets data-theme="dark" as its no-JavaScript fallback, keeping API stylesheet colors in sync with MUI under either system preference.

The server-rendering regression tests cover the app wrapper and compiled article content. After deployment, fetch an article without executing JavaScript and check that its headings, prose, code, tables, and links appear in the HTML body. robots.txt and llms.txt aid discovery but do not replace readable page HTML.

Code package variants

JavaScript and TypeScript code fences that use the BABYLON namespace are converted at build time into ES6, ES6-pure (when supported), and UMD tabs. The Markdown remains the canonical UMD source. Run the strict audit after changing the transformer, symbol map, or code examples:

npm run validate:code-variants

Use the no-code-variants fence metadata only for community extensions, removed APIs, or illustrative placeholders that have no ES module equivalent.

Custom markdown components

Markdowns can now be augmented with special components. For example, adding:

<Playground id="#Y642I8" title="Tinted Shadows Example" description="A Playground example of tinted shadows." />

will add a playground to the examples pane, allow to show its preview, add a styled link and add it to the search index for the playground. This will also generate images for this playground's preview when needed. Please make sure to commit those images.

Documentation for all markdown components is coming soon.