ADR-0009: Website built with Vite and TypeScript, hosted on CloudflareLink to the section ADR-0009: Website built with Vite and TypeScript, hosted on Cloudflare#

Status: Accepted 2026-10-15 (project sponsor) Date: 2026-10-15 Profiles affected: none (website only) Supersedes: decision 4 of ADR-0008. Its other decisions stand.

ContextLink to the section Context#

ADR-0008 had the website generated by MkDocs and deployed to GitHub Pages. GitHub Pages was never enabled (for a private repository on a personal account it needs GitHub Pro), so nothing was published. On 2026-10-15 the project sponsor decided to host univip.org on Cloudflare and to build the site with TypeScript and Vite, so that the build output can be uploaded directly to Cloudflare Workers or Cloudflare Pages.

Options consideredLink to the section Options considered#

1. Keep MkDocs and upload its output to Cloudflare. The least work. It keeps a Python toolchain for the site, and the Material theme is tied to MkDocs 1.6 because MkDocs 2.0 removes the plugin and theming systems it depends on.
2. A documentation framework built on Vite (VitePress, Astro Starlight). Search, navigation and theming come ready-made. It brings a UI framework (Vue or Astro) and its conventions into a repository that has none.
3. A small Vite plugin in TypeScript that renders the repository's Markdown. No UI framework, and the link rules are plain code in site/src/build/. There is more code for the project to own.

DecisionLink to the section Decision#

Option 3.

1. site/ is a Vite and TypeScript project. npm run build renders the repository into site/dist/: static HTML, the client script and styles, the schemas at their $id URLs, the OpenAPI description, the examples, 404.html, sitemap.xml, robots.txt and _headers.
2. site/dist/ is deployed unchanged to Cloudflare Workers (static assets, configured by site/wrangler.jsonc) or Cloudflare Pages (Direct Upload or wrangler pages deploy), with the custom domain univip.org. No server-side code runs.
3. The build fails on a broken link or heading anchor, on a published page missing from the navigation, and on a schema whose $id differs from the URL it is published at.
4. Links keep working on GitHub. Markdown files link to each other with relative paths and GitHub-style heading anchors, and the build maps them to site URLs.
5. The repository stays the single source of truth; nothing is edited on the website directly.

ConsequencesLink to the section Consequences#

• MkDocs, tools/build_site.py, site/mkdocs.yml and site/requirements.txt are removed. The site workflow builds and checks the site with Node and keeps site/dist/ as a downloadable artifact. It no longer deploys to GitHub Pages.
• Page URLs have neither a trailing slash nor .html (/spec/0.2/07-telemetry); directory indexes end in / (/spec/0.2/). Problem type URIs (https://univip.org/problems/<slug>) resolve without a redirect. Nothing was ever published under the MkDocs layout, so no URL breaks.
• Cloudflare serves the headers in _headers: cross-origin access to the schemas, the API description and the examples (Pages sends it by default, Workers does not), a content security policy, and long-lived caching for hashed assets.
• DNS for univip.org is served by Cloudflare or points at it. site/README.md gives the steps.
• Building the site needs Node 22.12 or later.

Open questionsLink to the section Open questions#

• Earlier versions must stay online once a later one is published (ADR-0008 decision 5). The build publishes only the current version, so this is needed before the first version is tagged.
• Whether CI deploys automatically, which needs a Cloudflare API token as a repository secret, or the sponsor uploads each build.