docs(site): add the Deco Blocks docs site (Home, Docs, Under the hood, Roadmap)

[tlgimenes]

What this is

The source of the Deco Blocks documentation site, under site/, plus a workflow that builds it and (after merge) publishes it to GitHub Pages.

The site is one self-contained HTML page with four hash-routed parts:

• Home: what Deco Blocks is and how publishing works, with an interactive outage example.
• Docs: the proposed API for the next major: quickstart, content model, schema, routing, preview, Studio compatibility, the Next.js and TanStack guides, and the API reference.
• Under the hood: how the runtime resolves, routes and loads content, with a step-by-step walkthrough widget.
• Roadmap: the to-do list that gets the next major to a release: ten release blockers, Studio support, work items (API, CLI, Studio, docs), migration plans for storefront-tanstack, blog-tanstack and a FastStore storefront, and a filterable table of 111 features with status and effort.

It also has ⌘K search, a light/dark theme toggle and a print layout. The only external requests are the Fontshare and Google Fonts stylesheets and the font files they load. No analytics and no third-party scripts.

Layout

• site/build.py assembles site/dist/index.html (gitignored) from site/src/*. Python 3.9+, standard library only.
• site/gen_roadmap.py renders the Roadmap from site/data/roadmap.json and checks it: ids, cross-links, counts, and links into the docs.
• site/data/roadmap.json holds exactly what the Roadmap shows, nothing more.
• site/src/ has the page shell, Home, the Docs/Under-the-hood content (with the MIT-licensed Prism bundle and its notice), CSS, JS and brand SVGs.
• .github/workflows/pages.yml builds on PRs that touch site/ and deploys to Pages on pushes to main of this repository (and manual runs on main).

See site/README.md for the data format and the public-content policy.

Preview

Locally:

python3 site/build.py && open site/dist/index.html   # xdg-open on Linux

From this PR: open the "Docs site" workflow run under Checks, download the docs-site artifact, unzip it and open index.html.

Left out of the public build on purpose

• The underlying analysis. The Roadmap comes from a code-level review of three sites. Only the conclusions are committed: feature statuses, effort, summaries and plans. The per-file evidence and working notes are not.
• One of the three sites is private. It appears only as "the FastStore storefront", with platform-level facts (FastStore v4, Next.js Pages Router, VTEX Headless CMS). Details that could identify its codebase or owner were removed or generalized.
• Issues in code that is deployed or released today are not described on the site. Where the next major needs a design change because of them, the Roadmap states only the design requirement for the unreleased API.
• No local paths, personal data, internal URLs or customer names.

Before going public

• Enable GitHub Pages with source GitHub Actions (Settings › Pages). Until then the deploy job on main fails; nothing else depends on it.
• Review the anonymized FastStore storefront content (Roadmap › Site migrations › FastStore storefront, and the FastStore rows in the feature table).
• Decide whether to announce the unreleased next major publicly. The Docs and Roadmap describe an API that isn't released yet.
• Apply the docs corrections listed under Roadmap › Work items › Docs (the items that correct statements that are wrong today come first).
• Optional: set up a custom domain for the Pages site.
• Squash-merge with a docs(site): … title, so the change doesn't trigger a package release.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WNwbSEePYNcY5YCgqZURig

---

Summary by cubic

Adds the Deco Blocks docs site source under site/ and a workflow that builds it on every PR touching site/ (downloadable artifact) and deploys it to GitHub Pages from main. The site documents both the released framework (v7) and the proposed next-major API — the composition-based, Git-backed content model and the run resolve option — with technical-writer passes that define every term. It's a standalone Bun package: TanStack Start prerenders each page to static HTML, content lives in MDX, Shiki highlights code at build time, and Pagefind backs the ⌘K search.

Site

• Four sections — Home, Docs, Under the hood, Roadmap — with light/dark themes and a print layout. v7 is the default version with its own home at / and 49 pages on the released framework and its apps; the next major lives under /next/, and a version select labeled "v7 (current)" / "next" on both homes switches between them. The Roadmap tab shows only while the next-major version is selected.
• Blocks teaches function composition stored as data, with a step-by-step resolution walkthrough; JSON examples sit next to the TypeScript calls they mean.
• "Section" is no longer a framework concept: a block that returns JSX is just a block, and only the page's sections field and Studio's legacy names keep the word.
• The next-major docs tell one content story: content is JSON files in .deco/blocks that developers, agents and Studio edit; deco content turns them into a module createCMS reads, publishing is a commit, and the hosted CMS makes published commits live without a deploy. Custom loaders stay in the API but leave the narrative (one pointer and the Loader reference remain); the KV setup is gone.
• The resolve option is run; the SDK reads no files and runs in any JavaScript runtime.
• page, redirect and telemetry are built-in blocks that createCMS spreads under your block map (always defined, overridable); resolving a saved page returns it ready to render (seo and every block in sections resolved), and UNKNOWN_BLOCK only means a name is in neither the map nor the saved entries. remoteLoader polls for a release every minute (interval option, DECO_CONTENT_INTERVAL, with jitter), and the Workers guide keeps the bundled snapshot in memory as the fallback.
• New next-major pages cover the content protocol Studio edits content through (deco content serve, polling), thin instrumented upstream API clients, and telemetry via createCMS({ site, token }), switched off through a Studio edit to the Telemetry entry.
• CLI deco schema and deco content write .deco/blocks.gen.ts and run from predev/prebuild; deco schema finds blocks.ts(x) in root or src/ (--entry overrides it). Schema compatibility is a CI check (deco schema --check, part of the first release), not a runtime rule.
• Studio builds its forms from whichever schema the user points it at, usually main's, and saves edits as commits on a draft branch.
• A newcomer pass added a glossary, one revision rule everywhere, moved rendering before routing, fixed wrong statements, and normalized block types and entries; every code example now uses double quotes and semicolons.
• The Home hero's "Resolve it" step shows the CMS setup and resolve call in one file; its stability section says changes go live in seconds; its points row is three columns ("Safe with the live code" is gone), and the "Swap any piece" card becomes "Publish by committing".
• The v7 docs add a "Going live after a migration" page (cutover checklist, parity checks with @decocms/parity, migrator-written CI workflows, withABTesting traffic shift) and extend the migration, VTEX, routing, variants, content, loaders, TanStack, troubleshooting, observability, SEO and glossary pages with public links. The v7 overview embeds the five Deco Studio training videos (Portuguese), each paired with the English page covering the same ground.
• The Roadmap renders from site/data/roadmap.json and is validated (ids, cross-links, counts); the analysis behind it and one private site are intentionally excluded.
• Styling is Tailwind utilities driven by a themed token set, with a full-width docs shell that keeps a 720px article column; the build fails if any page's HTML exceeds 48 KB gzipped.

Rollout

• Enable Pages with "GitHub Actions" as its source; until then the deploy job on main fails, with nothing else depending on it.
• Squash-merge with a docs(site): title so no package release is triggered.
• Review the anonymized FastStore content and decide whether to announce the unreleased API before going public.

^{Written for commit 27c4583. Summary will update on new commits.}