keystatic-setup
Add Keystatic — a git-based CMS from the Keystone team — to a new-website Astro scaffold, so a non-technical person can edit content through a UI while the data still rests as Markdown in the GitHub r
SKILL.mdskills/keystatic-setup/SKILL.md
GitHubKeystatic setup (scaffold-time, opt-in)
Adds an optional editor UI to the new-website Astro overlay. Opt-in: the default
scaffold is CMS-free (Markdown-in-git is the workflow). Run this only when new-website
§1 Q3 says a non-technical person edits after launch. Keystatic is git-based — it writes
Markdown/Markdoc into the repo, so "data rests in your GitHub" stays literally true and
the site stays free + static. (Keystatic is built by Thinkmill, the Keystone team.)
Prereq: the site uses Content Collections (new-website Q1) — Keystatic edits the files those collections read. If the site is flat pages only, add a collection first.
Local mode (what this skill wires up)
Edit via the dev server; Keystatic commits nothing on its own — you review and git commit/push, Cloudflare deploys. The admin runs in astro dev only; the production
build stays fully static (no adapter, no auth, no server). Steps applied to the project:
- Install (per the official Astro guide — verify current commands at keystatic.com):
npm install @keystatic/core @keystatic/astro npx astro add react markdoc # admin UI (React) + content format (Markdoc) astro.config.mjs— add the integrations. Thekeystatic()integration injects a server-rendered/keystaticadmin route, so adding it unconditionally fails the static build with[NoAdapterInstalled](verified). For local mode, gate it toastro dev— the admin runs locally, production stays fully static, no adapter needed:
Theimport react from '@astrojs/react'; import markdoc from '@astrojs/markdoc'; import keystatic from '@keystatic/astro'; const isDev = process.argv.includes('dev'); // keystatic admin = dev-only export default defineConfig({ // …existing site/trailingSlash/build… integrations: [/* existing */ react(), markdoc(), ...(isDev ? [keystatic()] : [])], output: 'static', });keystatic()integration auto-injects the/keystaticadmin route + its API — you do NOT hand-write route files. (Verified deps on Astro 7 — each checked vianpm view <pkg>, not assumed:@astrojs/markdoc@^2(peerastro: ^7.0.0— the^1line stays capped atastro: ^6.0.0and will NOT install against an Astro 7 site);@keystatic/astro@^5(peer range explicitly coversastro: 2 || 3 || 4 || 5 || 6 || 7);@astrojs/react@^6, NOT^5—^5declares noastropeer so it installs against Astro 7, but its ownvitedependency is^7.3.2against astro 7'svite@^8.0.13, producing a duplicate non-deduped vite tree and real build-time deprecation warnings;^6.0.1'svitedependency (^8.0.13) matches astro 7 exactly, confirmed vianpm view @astrojs/react@6 dependencies.vite;@keystatic/core@^0.5declares noastropeer and has no such transitive mismatch either, so it's fine as-is;react@19.npx astro add react markdoc(the Install step above) resolves the right majors automatically — this parenthetical is for anyone tempted to hand-pin an older note.)keystatic.config.tsat the repo root — one collection per repeating content type, eachpathpointing intosrc/content/:
Theimport { config, fields, collection } from '@keystatic/core'; export default config({ storage: { kind: 'local' }, collections: { posts: collection({ label: 'Posts', slugField: 'title', path: 'src/content/posts/*', format: { contentField: 'content' }, schema: { title: fields.slug({ name: { label: 'Title' } }), content: fields.markdoc({ label: 'Content' }), }, }), }, });label:strings ARE the CMS UI the owner sees daily — write them in the owner's language, not English (a German owner getslabel: 'Beiträge'/'Titel'/'Inhalt'). For a multilingual site built withastro-i18n-setup: per-locale entry dirs → mirror them as separate collections (one per locale directory — a singlepathglob can't span locale subdirectories, and a mis-scoped path leaves the other locale uneditable); alocalefrontmatter field → keep ONE collection and add that field to the Keystatic schema. Mirror the site's real Content Collections (the samepath/schema the Astrosrc/content.config.tsreads), so the CMS and the site agree on shape.- Allowlist —
Bash(npx keystatic:*)+WebFetch(domain:keystatic.com)already ship in the templatesettings.json; just confirm they're present in the project's copy (don't re-add — avoid duplicates). - README — document the workflow:
npm run dev→ open/keystatic→ edit → the files undersrc/content/change →git commit && git push→ Cloudflare deploys.
GitHub cloud mode (documented upgrade — not wired by default)
Local mode needs the editor to run a dev server. For a truly non-technical editor who should edit in the browser, upgrade to GitHub mode (commits straight to the repo from a hosted admin):
keystatic.config.ts:storage: { kind: 'github', repo: 'owner/name' }.- Connect Keystatic to GitHub (Keystatic Cloud, or your own GitHub App) for auth.
- The admin's auth/API routes now need on-demand rendering → add a server adapter
(
@astrojs/cloudflare) and switch the relevant routes to server output; add theKEYSTATIC_GITHUB_*env vars + OAuth callback. Follow the current keystatic.com docs. - Trade-off: browser editing for non-technical users, at the cost of an adapter + a GitHub App + secrets to manage. Recommend only when local mode is genuinely too technical.
Caveats
- Keystatic's default content format is Markdoc (
.mdoc), not plain.md— pickfields.markdoc/fields.mdx/fields.textto match what the site renders. - Local-mode admin is dev-only; it is not part of the deployed static site.
- Adds React + Markdoc deps — only worth it when someone actually edits via UI.
Wiring (done once in the suite)
new-website/SKILL.md§1 Q3 → "if non-technical editor: runkeystatic-setup"; add the skill to the §3 bundled-skills copy list (conditional — only for CMS sites).references/WEBSITE_ARCHITECTURE.mdPart 4 (Keystatic) → point at this skill.
Verify (scaffold a throwaway CMS site in /tmp)
npm install && npm run build # static prod build succeeds (keystatic gated off in build)
npm run dev # open http://localhost:4321/keystatic → admin loads (200)
# create an entry in the UI → a Markdown/Markdoc file appears under src/content/<collection>/
npm test # suite stays green