Keystatic 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. The keystatic() integration injects a
server-rendered /keystatic admin route, so adding it unconditionally fails the static
build with [NoAdapterInstalled] (verified). For local mode, gate it to astro dev —
the admin runs locally, production stays fully static, no adapter needed:import 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',
});
The keystatic() integration auto-injects the /keystatic admin route + its API —
you do NOT hand-write route files. (Verified deps on Astro 7 — each checked via
npm view <pkg>, not assumed: @astrojs/markdoc@^2 (peer astro: ^7.0.0 — the ^1
line stays capped at astro: ^6.0.0 and will NOT install against an Astro 7 site);
@keystatic/astro@^5 (peer range explicitly covers astro: 2 || 3 || 4 || 5 || 6 || 7);
@astrojs/react@^6, NOT ^5 — ^5 declares no astro peer so it installs against
Astro 7, but its own vite dependency is ^7.3.2 against astro 7's vite@^8.0.13,
producing a duplicate non-deduped vite tree and real build-time deprecation warnings;
^6.0.1's vite dependency (^8.0.13) matches astro 7 exactly, confirmed via
npm view @astrojs/react@6 dependencies.vite; @keystatic/core@^0.5 declares no astro
peer 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.ts at the repo root — one collection per repeating content type,
each path pointing into src/content/:import { 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' }),
},
}),
},
});
The label: strings ARE the CMS UI the owner sees daily — write them in the
owner's language, not English (a German owner gets label: 'Beiträge' / 'Titel' /
'Inhalt'). For a multilingual site built with astro-i18n-setup: per-locale
entry dirs → mirror them as separate collections (one per locale directory — a single
path glob can't span locale subdirectories, and a mis-scoped path leaves the other
locale uneditable); a locale frontmatter field → keep ONE collection and add that
field to the Keystatic schema.
Mirror the site's real Content Collections (the same path/schema the Astro
src/content.config.ts reads), so the CMS and the site agree on shape.
- Allowlist —
Bash(npx keystatic:*) + WebFetch(domain:keystatic.com) already ship
in the template settings.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
under src/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 the
KEYSTATIC_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 — pick
fields.markdoc/fields.mdx/fields.text to 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: run keystatic-setup"; add
the skill to the §3 bundled-skills copy list (conditional — only for CMS sites).
references/WEBSITE_ARCHITECTURE.md Part 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
1---2name: keystatic-setup3description: >4 Add Keystatic — a git-based CMS from the Keystone team — to a new-website Astro5 scaffold, so a non-technical person can edit content through a UI while the data6 still rests as Markdown in the GitHub repo. Wires LOCAL storage mode (edit in the7 dev server, commit/push); documents the GitHub cloud-mode upgrade for browser8 editing. Run ONCE, at scaffold time, when new-website Q3 = "a non-technical person9 edits content". Trigger phrases: "add a CMS", "Keystatic", "non-technical editor",10 "client edits content", "git-based CMS".11metadata:12 source: https://skillmd.com/skills/karero/keystatic-setup13---1415# Keystatic setup (scaffold-time, opt-in)1617Adds an optional editor UI to the `new-website` Astro overlay. **Opt-in:** the default18scaffold is CMS-free (Markdown-in-git is the workflow). Run this only when new-website19§1 Q3 says a non-technical person edits after launch. Keystatic is git-based — it writes20Markdown/Markdoc into the repo, so "data rests in your GitHub" stays literally true and21the site stays free + static. (Keystatic is built by Thinkmill, the Keystone team.)2223Prereq: the site uses **Content Collections** (new-website Q1) — Keystatic edits the24files those collections read. If the site is flat pages only, add a collection first.2526## Local mode (what this skill wires up)2728Edit via the dev server; Keystatic commits nothing on its own — you review and `git29commit`/`push`, Cloudflare deploys. The admin runs in `astro dev` only; the production30build stays fully static (no adapter, no auth, no server). Steps applied to the project:31321. **Install** (per the official Astro guide — verify current commands at keystatic.com):33 ```bash34 npm install @keystatic/core @keystatic/astro35 npx astro add react markdoc # admin UI (React) + content format (Markdoc)36 ```372. **`astro.config.mjs`** — add the integrations. The `keystatic()` integration injects a38 **server-rendered** `/keystatic` admin route, so adding it unconditionally fails the static39 build with `[NoAdapterInstalled]` (verified). For local mode, **gate it to `astro dev`** —40 the admin runs locally, production stays fully static, no adapter needed:41 ```js42 import react from '@astrojs/react';43 import markdoc from '@astrojs/markdoc';44 import keystatic from '@keystatic/astro';4546 const isDev = process.argv.includes('dev'); // keystatic admin = dev-only4748 export default defineConfig({49 // …existing site/trailingSlash/build…50 integrations: [/* existing */ react(), markdoc(), ...(isDev ? [keystatic()] : [])],51 output: 'static',52 });53 ```54 The `keystatic()` integration **auto-injects** the `/keystatic` admin route + its API —55 you do NOT hand-write route files. (Verified deps on Astro 7 — each checked via56 `npm view <pkg>`, not assumed: `@astrojs/markdoc@^2` (peer `astro: ^7.0.0` — the `^1`57 line stays capped at `astro: ^6.0.0` and will NOT install against an Astro 7 site);58 `@keystatic/astro@^5` (peer range explicitly covers `astro: 2 || 3 || 4 || 5 || 6 || 7`);59 `@astrojs/react@^6`, NOT `^5` — `^5` declares no `astro` peer so it *installs* against60 Astro 7, but its own `vite` dependency is `^7.3.2` against astro 7's `vite@^8.0.13`,61 producing a duplicate non-deduped vite tree and real build-time deprecation warnings;62 `^6.0.1`'s `vite` dependency (`^8.0.13`) matches astro 7 exactly, confirmed via63 `npm view @astrojs/react@6 dependencies.vite`; `@keystatic/core@^0.5` declares no `astro`64 peer and has no such transitive mismatch either, so it's fine as-is; `react@19`.65 `npx astro add react markdoc` (the Install step above) resolves the right majors66 automatically — this parenthetical is for anyone tempted to hand-pin an older note.)673. **`keystatic.config.ts`** at the repo root — one collection per repeating content type,68 each `path` pointing into `src/content/`:69 ```ts70 import { config, fields, collection } from '@keystatic/core';71 export default config({72 storage: { kind: 'local' },73 collections: {74 posts: collection({75 label: 'Posts',76 slugField: 'title',77 path: 'src/content/posts/*',78 format: { contentField: 'content' },79 schema: {80 title: fields.slug({ name: { label: 'Title' } }),81 content: fields.markdoc({ label: 'Content' }),82 },83 }),84 },85 });86 ```87 **The `label:` strings ARE the CMS UI the owner sees daily** — write them in the88 owner's language, not English (a German owner gets `label: 'Beiträge'` / `'Titel'` /89 `'Inhalt'`). For a multilingual site built with `astro-i18n-setup`: per-locale90 entry dirs → mirror them as separate collections (one per locale directory — a single91 `path` glob can't span locale subdirectories, and a mis-scoped path leaves the other92 locale uneditable); a `locale` frontmatter field → keep ONE collection and add that93 field to the Keystatic schema.94 Mirror the site's real Content Collections (the same `path`/schema the Astro95 `src/content.config.ts` reads), so the CMS and the site agree on shape.964. **Allowlist** — `Bash(npx keystatic:*)` + `WebFetch(domain:keystatic.com)` already ship97 in the template `settings.json`; just confirm they're present in the project's copy98 (don't re-add — avoid duplicates).995. **README** — document the workflow: `npm run dev` → open `/keystatic` → edit → the files100 under `src/content/` change → `git commit && git push` → Cloudflare deploys.101102## GitHub cloud mode (documented upgrade — not wired by default)103104Local mode needs the editor to run a dev server. For a truly non-technical editor who105should edit in the browser, upgrade to **GitHub mode** (commits straight to the repo from106a hosted admin):107- `keystatic.config.ts`: `storage: { kind: 'github', repo: 'owner/name' }`.108- Connect Keystatic to GitHub (Keystatic Cloud, or your own GitHub App) for auth.109- The admin's auth/API routes now need **on-demand rendering** → add a server adapter110 (`@astrojs/cloudflare`) and switch the relevant routes to server output; add the111 `KEYSTATIC_GITHUB_*` env vars + OAuth callback. Follow the current keystatic.com docs.112- Trade-off: browser editing for non-technical users, at the cost of an adapter + a113 GitHub App + secrets to manage. Recommend only when local mode is genuinely too technical.114115## Caveats116- Keystatic's default content format is **Markdoc** (`.mdoc`), not plain `.md` — pick117 `fields.markdoc`/`fields.mdx`/`fields.text` to match what the site renders.118- Local-mode admin is dev-only; it is not part of the deployed static site.119- Adds React + Markdoc deps — only worth it when someone actually edits via UI.120121## Wiring (done once in the suite)122- `new-website/SKILL.md` §1 Q3 → "if non-technical editor: run `keystatic-setup`"; add123 the skill to the §3 bundled-skills copy list (conditional — only for CMS sites).124- `references/WEBSITE_ARCHITECTURE.md` Part 4 (Keystatic) → point at this skill.125126## Verify (scaffold a throwaway CMS site in /tmp)127```128npm install && npm run build # static prod build succeeds (keystatic gated off in build)129npm run dev # open http://localhost:4321/keystatic → admin loads (200)130# create an entry in the UI → a Markdown/Markdoc file appears under src/content/<collection>/131npm test # suite stays green132```