Skip to content

1. Build & test the Astro + Starlight site locally:

voxlang.org — Compiler-Verified Bibliotheca, W3C SKOS Knowledge Graph, and Deterministic Browser Eval Sandbox

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)

Status: research prototype  Last Updated  License


Animated Documentation & Eval Pipeline Tour (voxlang_site_tour.webp)

Section titled “Animated Documentation & Eval Pipeline Tour (voxlang_site_tour.webp)”
Animated WebP tour of voxlang.org: Diataxis & W3C SKOS Knowledge Graph, vox-doc-pipeline Doctest Compiler Gate, eval.voxlang.org Deterministic Browser Playground, and Astro 7.4 + Starlight 0.42 Cloudflare Pipeline

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.


voxlang.org Pipeline: vox-doc-pipeline to Astro Starlight to Cloudflare Pages and Coolify eval.voxlang.org

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:

  1. Uncompilable code examples. Syntax evolves in the compiler while tutorial snippets silently break.
  2. Unstructured RAG ingestion. When AI coding agents ingest hundreds of Markdown files without controlled topic/domain facets or authorship provenance, obsolete notes and current SSOTs blend together.
  3. High onboarding friction. Asking a reader to clone a Rust workspace just to test a 15-line .vox declaration loses most curious developers before they run their first program.

How voxlang.org eliminates all three:

SubsystemEngineering MechanismKey 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 FacetsOrganizes 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 EngineBuilds 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 BootstrapPublishes .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 ClassCanonical Source of TruthHow It Reaches voxlang.org (Zero Hand-Copy Rule)
Language rationale (Why Vox)<!-- ANCHOR: why_vox --> in vox-foundation/vox/README.mdSynced into {/* SYNC-FROM-README: why_vox */} in docs/src/index.mdx; byte-parity enforced by vox-doc-pipeline.
CLI, MCP, env-var, config & plugin referencesRust clap definitions & YAML contracts in vox-foundation/voxEmitted 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 pagesRustdoc JSON across workspace cratesEmitted into docs/src/api/*.generated.md (linguist-generated in .gitattributes).
Sidebar navigation hierarchyPage 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 & contractscontracts/documentation/* and contracts/operations/catalog.v1.yamlVerified across vox and voxlang.org by vox ci cross-repo-parity (BLAKE3 digest check).

Graded into four honest states (Working, Prototype, Research, Not started):

SubsystemStateCheckedNotes (2026-11-10 Verification)
Astro 7.4.5 / Starlight 0.42.9 site buildWorking2026-11-10Compiles 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 gateWorking2026-11-10Verified 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)Working2026-11-10Deployed 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)Working2026-11-10Runs 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)Prototype2026-11-10Renders and verifies Ed25519-signed VerifiedLeaderboardSnapshotV1 payloads published by ops.voxlang.org.

All commands are portable across machines (using VOX_ROOT="${VOX_ROOT:-../vox}" when invoking the sibling Rust compiler workspace):

Terminal window
./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 discover
cargo run --manifest-path "$VOX_ROOT/Cargo.toml" -p vox-cli -- ci cross-repo-parity

Intellectual Lineage, Prior Art & References

Section titled “Intellectual Lineage, Prior Art & References”
  1. 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). ↩

  2. SKOS Controlled Vocabulary (kb-taxonomy.v1.yaml): Hierarchical topic and domain prefLabel / broader / related facets follow W3C SKOS Simple Knowledge Organization System Reference (Alistair Miles & Sean Bechhofer, W3C Recommendation, 2009). ↩

  3. 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. ↩

  4. Capability-Sandboxed Interpreter (eval.voxlang.org): Executing untrusted browser snippets under --caps deterministic with 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. ↩

  5. Machine-Readable LLM Discovery (.well-known/llms.txt): Exposing a structured Markdown index of documentation for coding agents follows Jeremy Howard’s llms.txt specification (Answer.AI, 2024). ↩