English for Keystatic CMS Developers

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 relatedPosts field 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 draft field 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

1. Explain, in two sentences, the difference between a collection and a singleton to a content editor with no technical background.
2. Write a short onboarding note for a new content editor explaining that saving a post opens a pull request rather than publishing instantly.
3. Draft a message describing a schema change (a new field) and how it will appear in the admin UI.

Related Resources

• English for Sanity CMS Developers
• English for Astro Content Collections
• English for Contentful CMS Developers

Navigating Nuance: Practical English for Keystatic Developers

As a developer working with Keystatic, you’ll be interacting heavily with content teams who primarily communicate in English. This isn’t just about technical jargon; it’s about clear, concise language that ensures everyone – from the content editor to the backend engineer – understands and aligns on expectations. One of the biggest challenges for non-native speakers is translating technical concepts into natural-sounding English, particularly when describing data structures like collections and singletons. It’s crucial to move beyond literal translations and understand how native speakers frame these ideas within a development context.

Often, the most significant misunderstandings arise in communication around code reviews or PR descriptions. For example, instead of saying “This collection contains singleton fields,” which can sound overly technical and potentially confusing for someone unfamiliar with Keystatic’s architecture, a more natural approach would be, “This collection holds individual pieces of content – think of it as a container for distinct articles.” Similarly, when explaining the reader API, avoiding phrases like “the API endpoint” and opting instead for “how we deliver content to the front-end” can significantly improve clarity. When crafting PR descriptions, focus on what change was made and why, rather than simply stating how. For instance, instead of “Updated field schema,” try “Refactored the ‘title’ field schema to include a required field for improved data quality.”

The key is to adopt a proactive approach to vocabulary. Don’t hesitate to ask clarifying questions – even if your initial phrasing isn’t perfect. Most Keystatic teams will appreciate the effort and be willing to help you refine your language. Utilizing tools like Grammarly or Hemingway Editor can also assist in identifying areas where your writing could be clearer and more concise. Remember, effective communication is a two-way street; it’s not just about conveying information but also actively listening and understanding the perspectives of others.

Here’s an example of how to use the keystatic query command to retrieve data from a collection:

keystatic query --collection myCollection --fields title,body

This demonstrates retrieving specific fields (title, body) from a collection named myCollection. The output would be formatted in a way that’s easily understandable by content editors and developers alike, showcasing the power of Keystatic’s structured data approach. Paying attention to phrasing like “retrieve” and “fields” will contribute to clear communication within your team.