Documentation
Everything it does, and why it does it that way.
Install it into a project you already have, then read the four ideas the rest of it follows from. Nothing here describes a feature the home page does not demonstrate.
Getting started
What AstroCraft is
A git-backed CMS that mounts into an Astro site you already have, reads its field types from your own Zod schema, and commits edits to your own repository.
Install AstroCraft
Requirements, the five directories you copy, the fourteen packages they need, and the decision about the test suite that comes with them.
Mount it in your Astro config
One integration line, one actions export, one tsconfig block — and why output must be 'server' rather than a preference you get to have.
Configuration
src/admin.config.ts is the only file you write: five keys naming the facts the CMS cannot derive, and the validator that catches the two typed mistakes.
Your first account
One CLI command creates the first admin. What the store is, why sign-up cannot make itself an admin, and how the throttles behave when you get a password wrong.
Licences and activation
One key, N websites, and exactly one thing gated — Publish. What an outage does, what moving domains does, and why your published site contains no check at all.
Using the CMS
The dashboard
Every screen the CMS ships, what each one derives its numbers from, and the one rule that keeps a count from disagreeing with the list beneath it.
Working with entries
The collection list, its four statuses, and the three verbs that each write exactly one commit — create, rename and delete.
The document editor
Nine block types, seven markdown input rules, three menus and one keyboard — and the byte-fidelity rule that keeps your diff down to the edit you made.
Details, SEO and History
The editor's right rail: fields generated from your Zod schema, a search and social preview that mirrors as you type, and the last twenty saves.
The image library
Upload, describe and optimise images, one commit each: why alt text is not a property of a file, and what the AVIF conversion measures first.
Composing pages
The page composer writes real .astro files from your own section components: four panes, declared props only, and a parser that refuses rather than rewrites.
Review and publish
The review queue spanning every collection and page, the build gate that runs before any push, and the live check that reads your site's commit stamp.
Team, roles and invites
The roster, what each role may do, how an invite is minted and spent, and the three checks that stop a guard from being mistaken for a permission.
Configuration
How the schema becomes the admin
Every Zod shape the walker maps to a control, the two heuristics behind long text, and the one schema style that will not work today.
The component library
How the composer discovers your sections, what it reads out of each file, and the override block for the facts your source cannot state.
Settings
Seven stored preferences, four SEO readouts and one row that writes a commit — every setting on the screen, what reads it, and what it costs to get wrong.
SEO and the published site
Where an author edits search and social metadata, the four machine-readable files the build emits, and the one rule the draft/preview split turns on.
Deployment
Deploying the CMS
Deploy AstroCraft as one container holding a real clone, plus two branch builds of your public site. Notes for Dokploy, Coolify and Railway.
Environment variables
Every variable the CMS reads, which of them a .env file can reach, and the measured reason two of them cannot live there.
Bring a database
Two variables move accounts, invites, settings, drafts, snapshots and sessions into Turso/libSQL — and make the container disposable. Entirely optional.
Updating
Which version you are on, which three directories a release replaces, and the one step that is destructive by omission rather than by action.
Reference
How it works
The three tenants, the rendering inversion the session guard depends on, and what happens between a keystroke and a commit.
Commands and checks
The four commands CI runs, what each one catches that the others cannot, and how to measure the editor's JavaScript for yourself.
Troubleshooting
AstroCraft's failure modes: the ones it produces on purpose, the ones that look like bugs and are not, and those whose message names the wrong cause.
Something here not covered?
An issue on the repository is the fastest way to move it — anything drawn on the home page ships in the version it is drawn for, and anything else is a request.