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.

Markdown for agents

npm run build:agent-docs (part of npm run build and npm run build:ci) generates agent-friendly copies of the documentation in public/:

• public/llms.txt: an llms.txt index of the top three levels of every section, linking to the markdown version of each page.
• public/<route>.md: every documentation page as plain markdown, so https://doc.babylonjs.com/setup/starterHTML is also available at https://doc.babylonjs.com/setup/starterHTML.md. The home page is index.md. Each file ends with links to its subpages.

Custom components are converted to plain markdown: <Playground> and editor embeds become links, <Alert> becomes a > [!NOTE]-style callout, and site-relative URLs become absolute. Code blocks are copied unchanged. Each HTML page links to its markdown copy with <link rel="alternate" type="text/markdown">. These files are generated, ignored by git, and must not be edited by hand. When adding a custom markdown component, add a conversion in lib/agentDocs/markdownExport.ts; the build warns about unconverted components and __tests__/agent-docs.test.ts fails on them.

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.