1. Build & test the Astro + Starlight site locally:
The compiler-verified documentation engine, W3C SKOS knowledge graph, and deterministic browser playground for Vox
Astro 7.4 + Starlight 0.42 · Executable .vox doctests (vox-doc-pipeline) · Diátaxis + SKOS + Nanopublication facets · Coolify eval.voxlang.org/v1/eval sandbox
Led by Bertrand Reyna-Brainerd · Stewarded by the Vox Foundation (in formation) · Apache-2.0 · Pre-1.0 Research Prototype (v0.6.0 Workspace)
voxlang.org · eval.voxlang.org · vox-foundation/vox (Language & Compiler) · vox-foundation/vox-axis (Desktop GUI)
Animated Documentation & Eval Pipeline Tour (voxlang_site_tour.webp)
Section titled “Animated Documentation & Eval Pipeline Tour (voxlang_site_tour.webp)”
voxlang.org Publishing & Verification Tour (Animated WebP · Imperial Roman Bibliotheca Series)
Four bespoke architectural plates cycling through: (I) Daniele Procida's Diátaxis quadrants[^1] unified under the W3C SKOS controlled vocabulary (kb-taxonomy.v1.yaml)[^2] and .well-known/llms.txt[^5]; (II) The vox-doc-pipeline four-arch gate (frontmatter validation, executable .vox doctest compilation, why_vox byte-parity sync, and Nanopublication provenance[^3]); (III) The eval.voxlang.org/v1/eval capability-sandboxed interpreter vault (--caps deterministic)[^4]; and (IV) Astro 7.4 + Starlight 0.42 static synthesis, VoxDiagram rendering, and Cloudflare Pages edge deployment.
End-to-End Architecture Schematic
Section titled “End-to-End Architecture Schematic”
From Source Manuscript (docs/src/) to Verified Edge Site & Deterministic Sandbox
Documentation in Vox is treated as executable, taxonomy-classified code: broken internal links, invalid SKOS facets, drifted homepage anchors, or uncompilable .vox snippets fail CI before deployment.
Why a Dedicated Documentation & Sandbox Pipeline Exists
Section titled “Why a Dedicated Documentation & Sandbox Pipeline Exists”In fast-moving language projects, documentation rots in three predictable ways:
- Uncompilable code examples. Syntax evolves in the compiler while tutorial snippets silently break.
- Unstructured RAG ingestion. When AI coding agents ingest hundreds of Markdown files without controlled
topic/domainfacets or authorship provenance, obsolete notes and current SSOTs blend together. - High onboarding friction. Asking a reader to clone a Rust workspace just to test a 15-line
.voxdeclaration loses most curious developers before they run their first program.
How voxlang.org eliminates all three:
| Subsystem | Engineering Mechanism | Key Files & Gates |
|---|---|---|
1. Suite Portal Frontpage (docs/src/index.mdx) | Serves as the unified public entry point for the entire Vox suite: pairs the interactive <VoxPlayground /> with animated .webp tours (vox_language_suite_tour.webp and axis_hero_tour.webp), the Vox Axis VRBS ROMA 3D/2.5D Simulator & AQVAEDUCTUS cascade showcase, side-by-side Light/Dark theme captures, and the 4-repository federation map. | docs/src/index.mdx, src/styles/reader-layout.css, tests/reader-layout.spec.ts |
2. Compiler-Verified Doctests (vox-doc-pipeline) | Extracts every fenced ```vox block across docs/src/ and runs vox check against the current compiler. A snippet may only bypass compilation if annotated with an explicit // vox:skip <reason> marker (reserved for multi-file excerpts). | vox-doc-pipeline --lint-only, Docs Quality/docs-quality CI job |
| 3. Diátaxis + W3C SKOS + Nanopublication Facets | Organizes pages into Diátaxis quadrants1 while requiring YAML frontmatter (title, description, category, topic, domain, authorship) validated against contracts/documentation/kb-taxonomy.v1.yaml2 and a 40–120 word <!-- kb:summary --> block3. | contracts/documentation/kb-taxonomy.v1.yaml, kb-facet-backlog.v1.yaml (shrink-only) |
| 4. Astro 7.4 + Starlight 0.42 Static Engine | Builds the public site from frontmatter-derived navigation (src/utils/sidebar.mjs — SUMMARY.md is retired), compiles vox-diagram blocks into deterministic SVGs, enforces zero broken internal links via starlight-links-validator 0.27.0, and provides a dual-chevron collapsible reader layout (#687) with the unified 4-token font contract (--font-display, --font-serif, --font-sans, --font-mono). | astro.config.mjs, src/utils/sidebar.mjs, src/components/VoxPlayground.astro |
5. Live Browser Eval Sandbox (eval.voxlang.org) | Interactive <VoxPlayground /> islands send .vox snippets to POST https://eval.voxlang.org/v1/eval, which runs vox run --interp --caps deterministic inside a stateless Coolify container4 with an in-memory SQLite VoxDb and zero ambient filesystem, network, or secret access. | vox-eval.compose.yml, .github/workflows/deploy-hetzner.yml, vox ci coolify-eval |
| 6. Agent Discovery & Installer Bootstrap | Publishes .well-known/llms.txt5 for LLM context ingestion and serves /voxup (POSIX) and /voxup.ps1 (PowerShell) bootstrap scripts verified by Playwright smoke tests (tests/smoke.spec.ts). | public/voxup, public/voxup.ps1, tests/smoke.spec.ts |
Separation of Concerns & Satellite Maintainability
Section titled “Separation of Concerns & Satellite Maintainability”To prevent cross-repository drift, vox-foundation/voxlang.org enforces a strict Single-Source Authoring Contract:
| Artifact Class | Canonical Source of Truth | How It Reaches voxlang.org (Zero Hand-Copy Rule) |
|---|---|---|
Language rationale (Why Vox) | <!-- ANCHOR: why_vox --> in vox-foundation/vox/README.md | Synced into {/* SYNC-FROM-README: why_vox */} in docs/src/index.mdx; byte-parity enforced by vox-doc-pipeline. |
| CLI, MCP, env-var, config & plugin references | Rust clap definitions & YAML contracts in vox-foundation/vox | Emitted into docs/src/reference/*.generated.md by vox ci command-sync and vox ci generate-plugin-catalog-docs (Docs Quality/generator-drift CI gate). |
| Crate API reference pages | Rustdoc JSON across workspace crates | Emitted into docs/src/api/*.generated.md (linguist-generated in .gitattributes). |
| Sidebar navigation hierarchy | Page YAML frontmatter (category, sort_order, title) | Computed dynamically at build time by src/utils/sidebar.mjs (never edit a manual table of contents). |
| Documentation taxonomy & contracts | contracts/documentation/* and contracts/operations/catalog.v1.yaml | Verified across vox and voxlang.org by vox ci cross-repo-parity (BLAKE3 digest check). |
Status
Section titled “Status”Graded into four honest states (Working, Prototype, Research, Not started):
| Subsystem | State | Checked | Notes (2026-11-10 Verification) |
|---|---|---|---|
| Astro 7.4.5 / Starlight 0.42.9 site build | Working | 2026-11-10 | Compiles all authored and generated pages cleanly; GitHub-style alerts render as native Starlight asides; starlight-links-validator 0.27.0 blocks broken internal links. |
vox-doc-pipeline frontmatter, SKOS & doctest gate | Working | 2026-11-10 | Verified in Docs Quality/docs-quality CI (0 errors): enforces required YAML keys, SKOS topic/domain prefLabels, shrink-only facet backlog, .vox doctests, and why_vox sync. |
Cloudflare Pages deployment (voxlang.org) | Working | 2026-11-10 | Deployed from main via wrangler pages deploy dist --project-name=vox-docs, gated by Playwright layout and smoke checks (tests/smoke.spec.ts, tests/collapsible-sidebars.spec.ts). |
Coolify Browser Eval Sandbox (eval.voxlang.org) | Working | 2026-11-10 | Runs vox run --interp --caps deterministic behind /v1/eval, declarative compose synced via vox ci coolify-eval sync-compose --compose vox-eval.compose.yml. |
Ludus Leaderboard Arena (VoxLeaderboardArena.astro) | Prototype | 2026-11-10 | Renders and verifies Ed25519-signed VerifiedLeaderboardSnapshotV1 payloads published by ops.voxlang.org. |
Building, Testing & Synchronizing
Section titled “Building, Testing & Synchronizing”All commands are portable across machines (using VOX_ROOT="${VOX_ROOT:-../vox}" when invoking the sibling Rust compiler workspace):
./scripts/build.sh./scripts/test.sh
# 2. Run the compiler-verified documentation linter & doctest runner from a sibling vox checkout:VOX_ROOT="${VOX_ROOT:-../vox}"cargo run --manifest-path "$VOX_ROOT/Cargo.toml" -p vox-doc-pipeline -- --lint-only
# 3. Verify Coolify eval sandbox compose parity & cross-repo BLAKE3 contract digests:cargo run --manifest-path "$VOX_ROOT/Cargo.toml" -p vox-cli -- ci coolify-eval discovercargo run --manifest-path "$VOX_ROOT/Cargo.toml" -p vox-cli -- ci cross-repo-parityIntellectual Lineage, Prior Art & References
Section titled “Intellectual Lineage, Prior Art & References”Footnotes
Section titled “Footnotes”-
Diátaxis Documentation Architecture: Separating documentation into Tutorials, How-To Guides, Reference, and Explanation follows Daniele Procida, Diátaxis: A systematic approach to technical documentation authoring (diataxis.fr). ↩
-
SKOS Controlled Vocabulary (
kb-taxonomy.v1.yaml): HierarchicaltopicanddomainprefLabel/broader/relatedfacets follow W3C SKOS Simple Knowledge Organization System Reference (Alistair Miles & Sean Bechhofer, W3C Recommendation, 2009). ↩ -
Nanopublication Provenance (
authorship,origin,kb:summary): Attaching machine-verifiable assertion, provenance, and publication metadata to each knowledge artifact draws from Paul Groth, Andrew Gibson, & Jan Velterop, “The Anatomy of a Nanopublication”, Information Services & Use 30(1–2), 2010. ↩ -
Capability-Sandboxed Interpreter (
eval.voxlang.org): Executing untrusted browser snippets under--caps deterministicwith zero ambient authority follows Jack B. Dennis & Earl C. Van Horn (CACM 1966), Mark S. Miller (Robust Composition, 2006), and the Bytecode Alliance WASI capability model. ↩ -
Machine-Readable LLM Discovery (
.well-known/llms.txt): Exposing a structured Markdown index of documentation for coding agents follows Jeremy Howard’sllms.txtspecification (Answer.AI, 2024). ↩