project-site

Build and deploy a Knot Vector project website (home, download, docs, changelog, roadmap, architecture) as a static site on a Cloudflare Worker at the project's domain (Alt:SA family: altmp.app and subdomains), following xPartition's structure. Use when a project needs its own site, or when updating one after a release or roadmap change.

Every project gets a small, fast static site that renders the project's own data files. Nothing is hand-copied, so the site can't drift from the repo.

PageSource
Home (index.html)Hand-written: what it is, hero, latest download (from releases.json)
Downloadreleases.json (files, sizes, SHA-256)
Changelog (changelog.html)release-notes.json + releases.json
Roadmap (roadmap.html)roadmap.json (see roadmap-upkeep)
Architecture (architecture.html)Hand-written diagram + docs/architecture.md content
Docs (docs/…)Markdown rendered at build time, or hand-written pages

Structure (from xPartition)#

Text
1site/2  index.html  changelog.html  roadmap.html  architecture.html  404.html3  site.css    site.js         (shared header/nav, theme, data loading)4  release-notes.json  releases.json  roadmap.json   (copied from repo root by tools/sync-site-data)5  robots.txt  sitemap.xml6  releases/<version>/<files>   (if downloads are hosted on the site)7wrangler.jsonc

wrangler.jsonc:

JSON
1{2  "name": "<project>",3  "account_id": "<CLOUDFLARE_ACCOUNT_ID>",       // Knot Vector account; look it up, never commit secrets4  "compatibility_date": "<today>",5  "assets": { "directory": "./site", "html_handling": "auto-trailing-slash", "not_found_handling": "404-page" },6  "routes": [{ "pattern": "<domain>", "custom_domain": true }]          // e.g. altmp.app, ngrp.altmp.app7}

Steps#

  1. Design first. Get the user to approve a direction (concept page with 2–3 options) before building a new site.
  2. Scaffold: node <toolkit>/templates/site/scaffold.cjs <repo> --name "<Name>" --domain <domain> [--theme atlas] [--accent "#hex" --accent2 "#hex"] [--mark text --suffix API].
    • What it writes: the shared pages, assets/site.js/site.css, site.config.json, tools/sync-site.cjs and wrangler.jsonc.
    • What you write: site/index.html and any extra pages, using the data-* hooks in site.js. See templates/site/README.md; Alt-SAMP/Website is the first real site built this way.
    • Deploy config: keep account_id out of wrangler.jsonc and set CLOUDFLARE_ACCOUNT_ID when deploying.
  3. Copy the data files into site/ as part of the build, and never edit them there.
  4. Preview locally: npx wrangler dev, or any static server on site/.
  5. Verify: every page loads, no console errors, and it works at 400 px wide. xPartition's tools/verify-site.cjs is the reference checker.
  6. Deploy: npx wrangler deploy. The custom domain attaches on first deploy if the zone is in the same account.
  7. Open the live URL in a browser and check it.

Wiki (docs from several repos)#

When a project family needs one wiki (altmp.app: engine, Godfather-API and Agent-Toolkit docs), use templates/site/wiki/ instead of separate sites:

  1. Docs stay canonical in each repo as markdown (docs/wiki/*.md, SKILL.md, ...). Never copy them by hand.
  2. List sources, refs and the nav in wiki.json. Read sources at origin/main (or origin/dev for an engine) so a feature branch checked out next door can't leak onto the site.
  3. node tools/sync-site.cjs --fetch && node tools/build-site.cjs, preview with node tools/serve.cjs, and run both with --check before merging.
  4. Retire old subdomains with a tiny redirect Worker that 301s every old URL to its wiki page (see Alt-SAMP/Website/redirects/). Ask the owner before deleting any Worker or DNS record.

Gotchas#

  • Wrong account: account_id must be the Knot Vector account. The user has several; pick by name.
  • Changelog drift: never copy changelog text into HTML. Render it from release-notes.json.
  • Large files: downloads over 25 MiB can't be Worker assets. Host them on GitHub Releases or R2 and link to them from releases.json.

Reference#

  • altmp.app: Alt-SAMP/Website (wiki.json, tools/sync-site.cjs, tools/build-site.cjs, pages/, redirects/).
  • xPartition: Knot-Vector/xPartition site/, wrangler.jsonc, tools/verify-site.cjs, tools/sync-site-releases.ps1.