CMS
The structured-content engine, file formats, and API.
The full spec of how collections work. Engine lives in console lib/cms.ts.
Files, per collection, inside each site repo
.sitecms.json: the registry. Per collection: id, name, page, version: 2, cmsFields (key, label, type), optional detail{dir, slugFrom}..cms/<id>/items.json: ordered array of items. System fields:_id(8-char),_status(“published” | “draft”),_slug(when detail pages are on). All other keys are field values as strings..cms/<id>/item.html: one item’s markup with{{fieldKey}}slots.{{_url}}resolves to the item’s detail URL..cms/<id>/detail.html: optional full-page template for detail pages.
Rendering
The listing page contains <!-- cms:<id>:start --> and <!-- cms:<id>:end --> anchors. Rendering joins published items through item.html and splices between the anchors. Escaping is type-aware: richtext values are raw HTML, everything else is escaped. Detail pages render to <dir>/<slug>/index.html for published items; stale pages are deleted. Every mutation writes items.json, the page, affected detail pages, and the registry in ONE commit (git trees API), so each operation is one deploy.
Field types
text, richtext, image, link, date, number, option. Types shape the editor (image preview + upload, number input, richtext toolbar) and inform AI generation. Values are strings; there is no hard validation beyond numbers.
Migration from v1
v1 defined collections as page + itemOpen tag with positional field extraction. Migration (automatic on first open): last item block becomes item.html with slots, all blocks extract to items.json, page gets anchors, first render is equivalent markup. The live site does not change.
API surface
POST /api/sites/<site>/collections actions: migrate, add, update, duplicate, remove (bulk via itemIds), status (bulk), reorder, slug, schema (labels/types), upload (base64 image to images/cms/), unregister. All item mutations accept a rev token from GET; a stale rev returns 409 with stale: true and the UI refreshes.
POST /api/sites/<site>/collections/ai actions: generate (items land as drafts), csv (AI column mapping, drafts), bulk (instruction across items, scope all/published/draft), inferSchema (names and types fields), addField / removeField (agent edits item.html, validated so no existing slot is lost), linkDetail (wraps items in links to their pages), enableDetail (agent designs detail.html from the site’s own look, assigns slugs, auto-links listing), createApply (create a collection from agent edits + migrate, one commit).
Guarantees
- Template edits are rejected if any existing
{{slot}}disappears. - Draft items never render anywhere.
- A collection needs at least one field and keeps at least one item (the template source in v1; in v2 empty collections are allowed but add uses the last item as default source).
Migrated sites
- naacp-snohomish-site / events (2026-07-22): 13 hand-coded Webflow event pages migrated to a v2 collection. Fields: title, date (text to preserve display format), image, excerpt, body (richtext). Slugs were preserved exactly from the original URLs, so no links broke. Pattern for future migrations: extract card + detail data, cross-check consistency, keep
_slugexplicit, re-render through the same template logic the console uses and diff against the originals before committing (the NAACP diff was about 2 lines per page, which is the fidelity bar).
Variant pages from cloned Webflow sites (learned on backpack-support-site)
Building orphan concept variants by slicing a cloned page’s section blocks works, with two hard rules. One: sections cannot be REORDERED; Webflow’s scroll choreography assumes original order and the hero paints blank if it runs against a moved section (symptom: DOM reports the text visible while the page shows background). Two: some sections are load-bearing for page scripts; on backpack-support-site the hero + stats + services trio must stay together and in order, while trailing sections (marquee, 10x, support, faq) drop safely. Always salvage embedded <style> blocks from dropped sections into the head, and verify each variant with a real browser screenshot, not just curl.