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.
| Page | Source |
|---|---|
Home (index.html) | Hand-written: what it is, hero, latest download (from releases.json) |
| Download | releases.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)#
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.jsoncwrangler.jsonc:
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#
- Design first. Get the user to approve a direction (concept page with 2–3 options) before building a new site.
- 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.cjsandwrangler.jsonc. - What you write:
site/index.htmland any extra pages, using thedata-*hooks insite.js. Seetemplates/site/README.md; Alt-SAMP/Website is the first real site built this way. - Deploy config: keep
account_idout ofwrangler.jsoncand setCLOUDFLARE_ACCOUNT_IDwhen deploying.
- What it writes: the shared pages,
- Copy the data files into
site/as part of the build, and never edit them there. - Preview locally:
npx wrangler dev, or any static server onsite/. - Verify: every page loads, no console errors, and it works at 400 px wide. xPartition's
tools/verify-site.cjsis the reference checker. - Deploy:
npx wrangler deploy. The custom domain attaches on first deploy if the zone is in the same account. - 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:
- Docs stay canonical in each repo as markdown (
docs/wiki/*.md,SKILL.md, ...). Never copy them by hand. - List sources, refs and the nav in
wiki.json. Read sources atorigin/main(ororigin/devfor an engine) so a feature branch checked out next door can't leak onto the site. node tools/sync-site.cjs --fetch && node tools/build-site.cjs, preview withnode tools/serve.cjs, and run both with--checkbefore merging.- 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_idmust 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/xPartitionsite/,wrangler.jsonc,tools/verify-site.cjs,tools/sync-site-releases.ps1.