Documentation website

Status: Current. The website, its Markdown exports and the checks that the documentation workflow runs are built and pass for both deployment paths, and the website is published at https://docs.allors.com/immersive/, beneath the Allors documentation home, from the repository’s Pages source GitHub Actions.

This record describes the documentation website of Immersive: what was decided, what was reused from Allors3 and what remains to do. The writing guide owns the editorial rules and Terminology owns the vocabulary. The pages live in docs/src/content/docs/; the website instructions cover local development, validation and publication.

Decision

Immersive adopts the Allors documentation standard as first implemented for Allors3 in allors3 pull request #284, merged as commit 33452c88c0e99b2db1243c4de0a061da23f0ae0c on main, inspected on 2026-10-18. The Allors documentation home is intended to present the Allors platforms and a collection of supporting open-source tools, each product publishing its own documentation beneath its own path. Immersive is one of the supporting tools; its documentation is smaller than a platform’s and proportional to its scope, with the same writing and accuracy standard.

Area	Decision
Readers	Human documentation serves users of the weaver and the libraries, and maintainers. Agent instructions in AGENTS.md point to the same content.
Site	Astro with Starlight. docs/ is the website project, with the content in docs/src/content/docs/. User and maintainer content have separate navigation groups.
Authoring	Markdown. MDX and components are available when a page needs them; none is used yet.
Hosting	GitHub Pages, built with GitHub Actions, at the path /immersive/ beneath the shared origin https://docs.allors.com, whose root is the Allors documentation home, with / also validated. The sidebar’s first entry links to the home, and the link checker leaves that link to the home’s own build. The origin’s own site and its custom domain belong to the documentation home, not to this repository.
Version context	Pages and exports identify the documented version as main · v2.1 (preview), following version.json and the published preview packages.
Visuals	Mermaid where suitable; the dependency diagram in How weaving works is the first. No interactive component yet.
Language and structure	Oxford English, precise practitioner terminology and Diátaxis, as defined in the writing guide.
Checks	The tooling tests, the Astro check, the production build with exports, the link check, a test that the control reference matches the libraries, and browser tests with accessibility checks, for both deployment paths.

What was reused

The following files were copied from the Allors3 implementation at the commit above, with the project-specific changes listed below:

File	Change for Immersive
astro.config.mjs	Title, description, sidebar entries; the title is read from site.mjs.
site.mjs	Adds title; sets the repository, version and the default base path /immersive/.
integrations/exports.mjs	The agent index heading and description are built from site.mjs.
integrations/source-links.mjs, integrations/scrollable-content.mjs	Unchanged.
scripts/check-links.mjs	The default base path. Target paths in its messages use forward slashes on every platform, so that its tests pass on Windows; port this to Allors3.
src/content.config.ts, src/components/PageTitle.astro, src/styles/documentation.css, public/favicon.ico, tsconfig.json, playwright.config.ts, .gitignore	Unchanged.
package.json, package-lock.json	The package name; the pinned dependency versions are identical.
tests/exports.test.mjs, tests/links.test.mjs, tests/source-links.test.mjs, tests/fixtures/anchors.md	Base paths, repository paths and version strings.
tests/browser/documentation.spec.ts	The page names, the diagram and the table it exercises; the workspace example tests were dropped.
.github/workflows/documentation.yml	The base path matrix, and the sources of the Windows Forms and Avalonia libraries as trigger paths, so that a library change runs the control-table test.

Two additions are specific to Immersive: scripts/controls-table.mjs generates the rows of the tables of Substituted controls and testers from the library sources and from its own list of tester members, and tests/controls.test.mjs fails when the rows differ from that output or a tester is missing from the page.

This second adoption shows what a shared implementation would contain: the three integrations, the link checker, the title component, the stylesheet, the content schema, the tooling tests and the workflow, parametrized by the values now in site.mjs. Extracting them is a decision for the Allors documentation home; until then, keep the copies identical where the table says so, and port fixes between the repositories.

Validation

On 2026-10-19 the following ran locally from docs/ for the base paths /immersive/ and /: npm test, npm run check, npm run build, npm run check:links and npm run test:browser, as the website instructions describe. The examples in Getting started were run from a clean directory against the published 2.1.10-preview packages, and the observed failure of the MSBuild package and its validated change are recorded in Run the weaver and Weaver internals.

Automated checks do not establish that an explanation is accurate or clear. The writing guide requires editorial review of changed pages and of representative exports.

Remaining work

• Decide with the other Allors repositories whether to extract the reused tooling.
• Revisit this record when the MSBuild package is changed and when Allors.Immersive.Avalonia is published.