English for Keystatic CMS Developers
Vocabulary for developers using Keystatic, the git-backed headless CMS — collections, singletons, fields, and the reader API — for content teams working in English.
Keystatic is a git-backed headless CMS — content is stored as markdown or JSON files directly in your repository rather than a separate database, and editors get a friendly admin UI on top. Because it sits between “just edit the markdown file” and “full hosted CMS,” discussing it clearly in English requires precision about where content actually lives and how changes flow. This guide covers the vocabulary.
Core Concepts
Git-backed CMS — a content system where every edit is committed to your git repository (often opening a pull request), rather than stored in an external database. “Because Keystatic is git-backed, every content change shows up as a normal commit — we get full history and review for free.”
Config file — the central keystatic.config.ts file where you define collections, singletons, and fields; this is the schema for your entire content model.
“Adding a new field to the blog post schema is one line in the config file — Keystatic’s admin UI updates automatically to show it.”
Reader API — the typed API Keystatic generates for reading your content at build time, so your frontend gets fully-typed content without a separate fetch layer.
“We use the reader API in getStaticProps — it’s type-safe, so if a field is renamed in the config, TypeScript flags every place that breaks.”
Content Structure
Collection
A collection is a set of repeatable content entries of the same shape — like blog posts or team members — each stored as its own file.
“Blog posts are a collection — each post is its own markdown file in
content/posts/, and the collection schema defines what fields every post must have.”
Singleton
A singleton is a single, one-off piece of content with no repeated entries — like site-wide settings or a homepage hero section.
“The homepage hero text is a singleton, not a collection — there’s only ever one of it, so it doesn’t need a list view in the admin.”
Field
A field defines one piece of structured data within a collection or singleton — text, rich text (document field), images, relationships, or arrays.
“We added a
relatedPostsfield as a relationship to the same collection, so editors can link posts to each other from the admin UI.”
Document Field
The document field is Keystatic’s structured rich-text editor, storing content as a tree of nodes (rather than raw markdown), which can be rendered to HTML, markdown, or React components.
“The document field lets editors add callout blocks and embeds through the UI, without needing to know any markdown syntax themselves.”
Storage Modes
Local mode — content is read from and written to the local filesystem, typically used during development. “In local mode, saving a post in the admin UI writes directly to the markdown file on disk — perfect for local development.”
GitHub mode — content changes go through the GitHub API, usually opening a pull request rather than committing directly to the main branch. “We run GitHub mode in production — editors submit changes through the Keystatic admin, and it opens a PR for review before merging.”
Cloud mode — an optional hosted layer on top of GitHub mode that adds asset storage and image optimisation without needing your own image pipeline.
Editorial Workflow
Branch-based editing — editors work on a separate git branch through the admin UI, and changes only reach production once that branch is merged (often via the opened pull request).
“Marketing drafted the new landing page copy on a branch through the admin — nothing went live until we approved and merged the PR.”
Draft field — a boolean field marking an entry as unpublished, commonly used to keep in-progress content out of the build until it’s ready.
“We check the
draftfield in our data-fetching code and exclude anything still marked as a draft from the production build.”
Explaining the System to Non-Technical Editors
| Situation | Phrase |
|---|---|
| Explaining where content lives | ”Every blog post is a file in our repository — Keystatic just gives you a friendly interface so you don’t need to write markdown by hand.” |
| Explaining the review step | ”When you save, it opens a pull request instead of publishing immediately — someone on the dev team reviews it before it goes live.” |
| Describing a schema change | ”We added an ‘excerpt’ field to every post — you’ll see a new box in the admin the next time you edit an existing post.” |
| Reassuring about content safety | ”Because everything is stored in git, we can always see exactly who changed what and revert any accidental edit.” |
Common Mistakes
- Calling every content type a “collection” — a singleton is for one-off content, and treating it like a collection confuses editors expecting a list view.
- Saying “the CMS database” — Keystatic has no database; content lives as files in git, which is worth clarifying to stakeholders used to traditional CMS platforms.
- Describing the document field as “just markdown” — it’s a structured tree that can render to multiple formats, not raw markdown text.
Practice Exercise
- Explain, in two sentences, the difference between a collection and a singleton to a content editor with no technical background.
- Write a short onboarding note for a new content editor explaining that saving a post opens a pull request rather than publishing instantly.
- Draft a message describing a schema change (a new field) and how it will appear in the admin UI.