Someone has suggested Sanity for your next website, and the word "headless" turns up in every line of the proposal. You can tell it is a CMS, but not what it changes for the team who will write the pages, or what you give up compared with WordPress or Webflow. It is a good question to ask before signing, because Sanity CMS does not behave like the tools most marketing teams know.
I use it every day. This site is built with Next.js and Sanity, with the Studio embedded at /studio, and in May 2026 I rebuilt the marketing site of Moonworkers, my own company, on the same stack. Here is how the tool works, what I have built with it, and the cases where I would choose something else.
01What "headless" means, without the jargon
A traditional CMS does two jobs at once: it stores your text and it builds the pages that display it. A headless CMS only does the first. It holds the content and makes it available through an API; another program, the website, fetches it and decides how it looks.
In practice, that means three things for you. The same content can feed a website, an app or another tool without being copied. The site's design no longer depends on the CMS, so you can redo it without touching the text. And a program can write into the CMS as easily as a person can, which matters a lot to me for automating publication.
The trade-off is that you need a developer to build the visible part. Nobody drags a block onto a page to see how it looks, as they would in a visual editor. More on that below.
02How Sanity stores content
Sanity has two parts that people often mix up: the Studio, where you write, and the Content Lake, where the content is stored.
The Content Lake stores content as structured data, in JSON documents, ready to be queried and delivered to any channel. An article there is not an HTML page: it is a document with a title, a slug, a language, a body and a list of sources. That is what makes it reusable, and checkable.
The Studio is the editing interface. It is open source, collaborative in real time, and developers describe the content models in it with JavaScript objects. The Studio's code is published under the MIT licence on GitHub; storage, though, remains a service hosted by Sanity.
Schemas are written in code
In most CMSs, you create a field by clicking around an admin screen. In Sanity, a schema describes, in code, the document types and fields that writers can fill in. The content model is therefore versioned like the rest of the site, and you can read its history.
The official Sanity Studio 101 video shows a detail I found reassuring: the Content Lake does not enforce a schema. If you remove a field from the Studio, the data does not vanish; it shows up as an unknown field. So you can change the Studio locally without breaking production, then publish it with a single command.
GROQ queries
To read content, Sanity has its own language, GROQ. It is used to describe exactly the information a page needs, joining several documents where required. To list the French articles from newest to oldest, with their title, slug and excerpt, the query fits on one line. It starts with an asterisk, which stands for every document; a filter in square brackets keeps the "article" type and the "fr" language; and a projection in braces picks the three fields to return. For a marketing lead, the benefit is indirect: the site only loads what it displays.
Rich text is not HTML
An article's body comes back from the API as Portable Text, a series of structured blocks, rather than HTML or Markdown as in many other CMSs. The site turns those blocks into paragraphs, headings and lists when it displays them. It is a little more work at the start, but a heading stays a heading, not a tag pasted in by hand with a random font size.
03Connecting Sanity to Next.js without serving stale pages
Next.js caches the pages and data it has already built, which keeps the site fast. The downside: when an article changes in Sanity, the site can keep serving the old version. I learnt to watch for this on client work. A site can look fine to the logged-in team and be out of date, or broken, for visitors.
On this site, I wrote a revalidation route protected by a secret. Each time something is published, my content machine calls it, and it does two things. It invalidates the articles cache tag with revalidateTag and immediate expiry (the "expire: 0" option). The documentation says that in this mode stale content is never served: the next visit waits for the new version. Then it invalidates the blog paths with revalidatePath, in case the page cache outlives the data cache.
The comment I left in the code explains why: without immediate expiry, the first visit after publication still serves the old version. Not a disaster on a blog, but exactly the kind of detail you miss when you test while logged in, just after clicking "publish". So after each publication, I check the page as a visitor would.
04My content model for this blog
Here, simplified, is the schema of an article on this site. I share it because it shows what a headless CMS allows when you start from the real work rather than a generic template.
- Reading fields: title, slug, excerpt, image and its alt text, body in Portable Text, FAQ.
- Language and the link between versions: each article carries its language and a reference to the original, so the French and English versions stay linked.
- Sources: a list of titles and URLs, shown at the end of the article.
- Search: a title and a description for search engines.
- Editorial tracking: a "to review" or "Reviewed" status, the verdict of the automated check, the justification for any flagged points and the date sent, the last three read-only.
The fifth block is the one I could not have got as simply elsewhere. My content machine checks each article, then publishes it straight into Sanity through the API with the "to review" status. I read it on the site and switch it to "Reviewed" in the Studio, which lists the articles still waiting. I have written about why I automated publishing before producing more: the bottleneck was getting content online, not writing it.
This model has a cost, and I would rather say so. Every new field means touching the schema, the code that displays it and sometimes the documents already published. The Content Lake keeps old data, so you do not lose an article, but it does not do the update work for you.
05When I would not choose Sanity
Sanity is not the right choice for everyone, and I would rather say so before anyone asks.
If your team wants to lay out its own pages, drag a block, see the result and publish without a developer, a visual tool will be quicker. I have made that choice for B2B sites, and I explain when I go for Webflow for a B2B website. Sanity offers a live preview of the site inside the Studio, but the layout is still written by a developer.
If nobody will be able to maintain the site's code after handover, headless becomes a dependency. The content will be well organised, but every new page type will need someone to write the schema and the component that displays it.
Finally, if you are changing CMS only for speed or SEO, look at the current site first. A well-run migration keeps every URL and redirect; I set out the method in migrating to Next.js and Sanity without losing pages. Done badly, it costs more than it brings in.
06Where to start if you are unsure
Before comparing tools, I would spend an hour on this with your team:
- list the site's content types (article, service page, case study, product sheet) and, for each, its fields;
- note who writes each type and who approves it;
- note whether a program needs to create or change content (an import, a content machine, a catalogue);
- note whether the team needs to lay out pages freely, or only to fill in templates.
If the list is long and structured, and a program writes into it, Sanity holds up very well. If the team mainly wants to build pages, a visual tool will suit it better. In between, it is a conversation. Moonworkers, shown among my projects, is an example of the first case: a marketing site with calculators and automated publishing.
If you would like to look at your case together, my services describe how I work. Happy to talk it through.