Building the documentation

This file describes how the kit's documentation is produced, what to edit, and what is generated. For the product docs themselves, start at index.html (searchable landing page) or the engine / Blender indexes. Kit version in prose hubs: engine v0.31.1 · Blender add-on v0.32.0 (from packages/engine/package.json + blender_addon/blender_manifest.toml at build time).

Contributor quick start

Pick the row that matches what you want to change, edit the source file, then run the command. Never hand-edit generated HTML under docs/ (except meta .md files).

Every built prose page footer shows the exact fragment path. Full build (docs:build) runs validate + link check at the end.

Three kinds of documentation

The interactive pages are clickable node graphs and step-by-step code traces that pull live source from packages/engine/ and blender_addon/. Prose chapters are longer-form narrative (architecture, workflow, feature traces in prose) as styled HTML — edit the fragment files directly, not markdown.

Meta markdown (STYLE_GUIDE.md, LLM_*.md, …) is for contributors and tooling; it is listed on the landing footer but not converted to prose HTML. This guide (BUILDING-DOCS.html) is indexed in search under the Contributors topic.

Source map — what to edit for everything

Rule of thumb: never hand-edit generated HTML under docs/ except the short blender/00-INDEX.md redirect stub and hand-edited meta .md files. Edit the source column, then npm run docs:build.

Orchestrator: scripts/build-docs.mjs runs trace → blender → prose → landing → validate → link check. package.json scripts: docs:build, docs:trace, docs:blender, docs:prose, docs:validate, docs:check-links.

Build commands

All commands run from the repository root.

docs:build is the one to use after any doc change. It runs, in order:

1. scripts/build-trace-docs.mjs → engine diagrams + traces
2. scripts/build-blender-docs.mjs → Blender diagrams + traces
3. scripts/build-prose-docs.mjs → prose chapters
4. scripts/build-landing.mjs → docs/index.html (includes BUILDING-DOCS.html in search)
5. scripts/docs/validate-docs.mjs → fragment registry + topic coverage
6. scripts/check-doc-links.mjs → internal link validation

The Babylon Launcher can also trigger a build via POST /api/docs/build (see launcher docs).

Architecture

flowchart LR
  subgraph sources ["Edit these"]
    direction TB
    shell["diagram-shell.html"]
    proseShell["prose-shell.html"]
    shared["shared.mjs"]
    engineAreas["engine-areas.mjs"]
    engineTraces["engine TRACES"]
    blenderAreas["blender AREA_PAGES"]
    blenderTraces["blender TRACES"]
    proseContent["prose/content/"]
    proseManifest["prose/manifest.mjs"]
    topics["topics.mjs"]
  end

  subgraph build ["Build scripts"]
    direction TB
    buildTrace["build-trace-docs"]
    buildBlender["build-blender-docs"]
    buildProse["build-prose-docs"]
    buildLanding["build-landing"]
  end

  subgraph generated ["Generated — do not hand-edit"]
    direction TB
    engineHtml["docs/engine/*.html"]
    blenderHtml["docs/blender/*.html"]
    launcherHtml["docs/launcher/*.html"]
    metaHtml["docs/BUILDING-DOCS.html"]
    indexHtml["docs/index.html"]
  end

  subgraph code ["Read at build time"]
    direction TB
    engineSrc["packages/engine/"]
    blenderSrc["blender_addon/"]
  end

  shell --> buildTrace
  shared --> buildTrace
  shared --> buildBlender
  engineAreas --> buildTrace
  engineTraces --> buildTrace
  engineSrc --> buildTrace
  blenderAreas --> buildBlender
  blenderTraces --> buildBlender
  blenderSrc --> buildBlender
  proseShell --> buildProse
  proseContent --> buildProse
  proseManifest --> buildProse
  buildTrace --> engineHtml
  buildBlender --> blenderHtml
  buildProse --> engineHtml
  buildProse --> launcherHtml
  buildProse --> metaHtml
  engineAreas --> buildLanding
  engineTraces --> buildLanding
  blenderAreas --> buildLanding
  blenderTraces --> buildLanding
  topics --> buildLanding
  buildTrace --> buildLanding
  buildBlender --> buildLanding
  buildProse --> buildLanding
  buildLanding --> indexHtml

Prose chapters (HTML fragments)

Narrative docs (architecture, physics, workflow, launcher guide, …) are HTML body fragments edited directly:

scripts/docs/prose/content/engine/01-ARCHITECTURE.html (etc.)

scripts/build-prose-docs.mjs wraps each fragment in docs/_template/prose-shell.html (toolbar, prev/next nav, typography) and writes docs/engine/01-ARCHITECTURE.html (etc.). Register new chapters in scripts/docs/prose/manifest.mjs (PROSE_CHAPTERS) and scripts/docs/topics.mjs (PAGE_TOPICS).

Fragment files contain only the <article> inner HTML (<h1>, <p>, <table>, <pre>, …). Use <pre class="mermaid"> for diagrams (mermaid.js loads from CDN when present). Link to other chapters with .html paths; contributor meta docs stay .md (STYLE_GUIDE.md, LLM_KERNEL.md, …).

Starter template: copy scripts/docs/prose/content/_FRAGMENT-TEMPLATE.html when adding a chapter.

Prose CSS classes (defined in prose-shell.html)

Reference chapters: 13 — Feature List (inventory) · 14 — API Guide (behavior author API).

Interactive HTML: the shared shell

Every diagram and trace page is assembled from one template:

docs/_template/diagram-shell.html

The shell contains the viewer UI (pan/zoom canvas, node panel, toolbar, import/export of diagram JSON). Build scripts inject:

• DIAGRAM_DATA — JSON for nodes, edges, title
• <title> — page title
• Bottom nav — links to sibling area/trace pages (engine = blue, Blender = amber)
• Body patches — resizable side panel; trace pages add a code block panel

To change viewer behaviour or styling for all diagram pages, edit the shell once and run npm run docs:build.

Assembly lives in scripts/docs/shared.mjs → EmitDiagramPage().

Subsystem diagrams vs code traces

User-facing name: subsystem diagram. Internally the data still lives in ENGINE_AREA_PAGES / AREA_PAGES (historical “area” jargon — not Blender AREA lights). The landing index tags them kind: "diagram" and displays the badge subsystem. On diagram and trace pages, the bottom nav shows breadcrumb links plus a full Traces row listing every code trace on that side (current page highlighted).

Subsystem diagrams

High-level subsystem maps: boxes and arrows, hand-authored content, no source extraction.

Each page entry has:

• navLabel (engine only) — short label in the bottom nav
• diagram / nodes + edges — graph data (id, x, y, w, h, label, sub, desc, meta rows)

Blender area pages use helpers N() and E() from shared.mjs for nodes and edges. Engine area pages use plain JSON objects (same shape).

Code traces

Step-by-step walkthroughs along a feature path. Each step is either:

• { file, symbol, note } — build extracts the function/class from disk
• { title, code, note } — inline snippet (e.g. manifest JSON); no extraction

Output files are named trace-<id>.html (e.g. trace-physics.html).

Trace pages use a wider code panel (CODE_PANEL_PATCH_* in shared.mjs). Clicking a step shows the extracted source and file:line.

Automatic diagram ↔ trace linking

Subsystem diagrams and code traces stay paired at build time — no hand-maintained link lists in the bottom nav or on every node. The single source of truth is PAGE_TOPICS in scripts/docs/topics.mjs (the same map that powers the landing-page topic hub).

How topics choose related pages

Each subsystem diagram and trace page is tagged with one or more topic ids (physics, rendering, export, …). Meta topics start and contributor are ignored when pairing.

• Shared topic — a trace is related to a subsystem diagram when their topic sets overlap (e.g. both include physics).
• Overview fallback — engine/index.html, engine/architecture.html, and blender/index.html list every trace on that side in the bottom nav when they have no content-topic overlap.

Helpers in topics.mjs: TracesForDiagram(href), DiagramsForTrace(href), FilterNavByHrefs().

Bottom nav (page-level)

Nav HTML is built in scripts/docs/shared.mjs (BuildDiagramBottomNav) and wired in build-trace-docs.mjs / build-blender-docs.mjs.

Node metadata (click a box)

When a subsystem diagram is emitted, scripts/docs/diagram-links.mjs adds Trace rows to each node's meta panel unless the node already has a Trace key (manual entries are preserved).

A trace is attached to a node when:

1. It is topic-related to the parent diagram page, and
2. Any of the following match a step in that trace:
   • Symbol — step symbol equals the node label, or appears in sub
   • File path — a step file contains a token from the node's File, Files, or Module meta value (split on ·, commas, spaces)
   • traceIds — optional node field, e.g. "traceIds": ["physics", "constraint"], forces those traces when heuristics are not enough

On overview diagrams, only symbol matches (and explicit traceIds) are used — file-path matching is disabled so the map does not link every box to every trace.

On code-trace pages, each step node gets Diagram meta rows for every topic-related subsystem diagram (same-side). Cross-side links (e.g. ../engine/input.html from a Blender node) remain manual in the source data. In the viewer, Trace and Diagram meta values render as clickable links (diagram-shell.html → renderMeta).

Adding a new trace or diagram

1. Add the page to PAGE_TOPICS with the right topic id(s).
2. Give diagram nodes a label / sub / File meta that overlaps the trace's step symbols or paths — or set traceIds on the node.
3. Run npm run docs:build. Nav and node panels update automatically.

To opt a node out of auto traces, add any Trace meta row yourself (even a single manual target); auto-linking skips that node entirely.

Symbol extraction (anti-rot)

Before writing trace HTML, the build reads the real source and embeds it in each step:

• TypeScript — ExtractSymbol() in shared.mjs (functions, classes, const exports; includes JSDoc above the symbol when present)
• Python — ExtractPySymbol() (function or class body by indentation)

If a symbol is missing or renamed, the build prints MISSING: …, sets exit code 1, and does not write trace pages for that packet. This keeps docs from silently showing stale code.

After changing a traced function's name or file, update the TRACES array and re-run the appropriate docs:* command.

Landing page, topic hub, and search

docs/index.html is fully generated by scripts/build-landing.mjs.

It indexes every subsystem diagram, code trace, prose chapter, and this guide, so search stays in sync with the graphs and narrative docs. Features:

• Topic hub — browse by intent (Physics, Export, Scripting, …) via scripts/docs/topics.mjs; each topic has curated Start here links
• Full-text ranking over titles, summaries, and node/step/chapter text
• Synonym map (SYNONYMS in build-landing.mjs) — e.g. "collision" also matches collider/physics pages; "scale" matches applyObjectScale
• Suggestion chips under the search box
• ?topic= and ?q= URL parameters for deep links (e.g. ?topic=physics&q=scale)

Adding a page to a topic

1. Add or update the page's href in PAGE_TOPICS in scripts/docs/topics.mjs (one or more topic ids).
2. If the page should appear in Start here, add its href to that topic's startHere array (order matters).
3. Run npm run docs:build.

New prose chapters require an entry in PROSE_CHAPTERS (manifest.mjs) and topic assignment in PAGE_TOPICS. Contributor markdown under docs/ is listed in KEPT_META_MD (scripts/docs/prose-config.mjs) and linked from the landing footer — not prose HTML.

To improve search for a new concept, add synonyms in SYNONYMS or ensure the page's desc / note fields use words people will search for.

File reference

Quick index of build scripts and templates (see Source map above for edit-vs-output pairing).

Common tasks

Regenerate after a code change

If you only changed implementation and trace symbols are unchanged:

npm run docs:build

Add an engine code trace

1. Append an object to TRACES in scripts/build-trace-docs.mjs (id, title, intro, steps).
2. Use { file: "packages/engine/…", symbol: "FunctionName", note: "…" } for live extraction.
3. Run npm run docs:trace (or docs:build) and fix any MISSING errors.
4. Optionally add a prose section in scripts/docs/prose/content/engine/10-FEATURE-TRACES.html.

The new page appears in the bottom Traces row on every diagram/trace page on that side. The landing page indexes it automatically. Matching diagram nodes gain Trace meta rows when their label/file overlaps trace steps (see node metadata below).

Add a Blender code trace

Same as above, but edit TRACES in scripts/build-blender-docs.mjs and use blender_addon/… paths. Run npm run docs:blender.

Add or edit a subsystem diagram

• Engine: edit scripts/docs/engine-areas.mjs (ENGINE_AREA_PAGES).
• Blender: edit AREA_PAGES in scripts/build-blender-docs.mjs.

Adjust x/y for layout. Re-run docs:build. Nav labels come from navLabel (engine) or page.title (Blender).

Add a prose chapter

1. Copy scripts/docs/prose/content/_FRAGMENT-TEMPLATE.html to engine/NN-MY-TOPIC.html.
2. Append an entry to PROSE_CHAPTERS in scripts/docs/prose/manifest.mjs (wire prev / next into the chain).
3. Add href → topics in scripts/docs/topics.mjs; link from 00-INDEX.html.
4. Run npm run docs:validate then npm run docs:build.

Change diagram viewer UI

Edit docs/_template/diagram-shell.html, then npm run docs:build.

New feature documentation checklist

When shipping a user-facing subsystem or major feature, work through this list (small PRs per bullet are fine):

1. Subsystem diagram — add or extend nodes in ENGINE_AREA_PAGES and/or AREA_PAGES (Blender side when authoring matters).
2. Code trace(s) — append to TRACES in build-trace-docs.mjs and/or build-blender-docs.mjs; fix any MISSING: symbols.
3. Prose — chapter section or new fragment under scripts/docs/prose/content/; register in manifest.mjs; add a row to 10-FEATURE-TRACES.html when it is a Blender → runtime chain.
4. Cross-links — prose doc-links line pointing at the subsystem diagram + primary trace(s).
5. Topics — PAGE_TOPICS and optional startHere in topics.mjs (also drives automatic diagram ↔ trace nav and node links).
6. Search — synonyms in SYNONYMS (build-landing.mjs) and descriptive desc / note text on diagram nodes and trace steps.
7. Reference — add rows to 13-FEATURE-LIST.html when shipping user-facing capability; extend 14-API-GUIDE.html when behavior authors get new APIs.
8. Validate — npm run docs:validate then npm run docs:build (runs link check too).

What not to edit

These files are overwritten on every build:

• docs/index.html
• docs/engine/*.html (including numbered prose chapters)
• docs/blender/*.html
• docs/launcher/*.html
• docs/BUILDING-DOCS.html

Edit the sources instead: diagram/trace data in scripts/, prose fragments in scripts/docs/prose/content/. Generated HTML includes a footer pointing at the source fragment.

Viewing locally

Open docs/index.html in a browser (file:// or via a static server). The playground and launcher can serve /docs after a build. Diagram pages are self-contained single HTML files — no bundler required.

Related docs

• Engine index — runtime overview + prose chapter list
• Blender index — add-on overview (prose HTML)
• Feature traces (prose) — scannable Blender → runtime chains
• Feature list — full capability inventory
• API guide — behavior author runtime API
• Style guide — code conventions (separate from this build guide)