The Sanity Way

What's a Headless CMS, and why should I care?

It used to be that content management systems came in a big box: a service running on dedicated hardware where editors wrangled content, a simple database stored the results and a templating engine output fully formed web pages.

For some websites this is still just fine. It's not very complicated. You describe pages that people then can come look at. The pages have a hierarchy. They have breadcrumbs. One of them is kind of at the front. It's called index. Many of us feel comfortable now with this way of thinking about digital content.

The drawback though is that your content is bound to a single context. Many text editors will for example put markup in your documents that might mess up any other page you publish it to. The most problematic though is that everything will be structured around pages. Pages. Pages. Pages. What goes on the front page the designers ask in the first meeting. What do we put on the employee page?

There is no way of expressing how content is structured that cuts across the page metaphor. It's rigid. And pretty expensive when you want to change anything.

This might have been fine before, but it's increasingly making everyone's day a lot worse. The reason for this is that we know fewer and fewer things about where content will be used and how it will appear.

A timeline is super illustrative

  • 2001 – Responsive design (
    You no longer know the size of the screen
  • 2005 – Front-end Javascript Apps (Google Maps)
    You no longer need your content as HTML, but as structured data
  • 2005 – Microformats, RDFa, JSON-LD
    Your content becomes more useful if its accompanied by rich metadata
  • 2008 – Mobile apps
    Apps don't want your HTML, they want structured data
  • 2014 – Multiplication of touchpoints, devices, services
    Perhaps it's a chatbot or Amazon Alexa, an automatic translation services or other third party services. Flowing content as data across services should be easy, well defined and expected.

So even though the web was conceived as a collection of linked documents, most websites shouldn’t just be a bunch of pages. Theres’s always underlying logic you could capture, a model.

Therefore headless CMS' present editing interfaces for structured data and make your content available over an API. They don't do templating for web pages. And this should make you rejoice as it means you get clean separation of concerns. Your CMS structures your data. Technologists get to choose whatever framework they like to present it to people.

If your data is well structured it will be forward compatible and you should be able to retarget it to new touch-points and services. Swap out your website without touching your data. Distribute to in-store screens. Integrate with other systems over APIs.

This is why you should care about the headless CMS.

PS: Just to be clear, this way of thinking about content isn't very new at all. People have been building bespoke relational databases with custom forms on top since forever. But it has been time consuming and also pretty hard to get totally right. It's free form in data structure, but expensive to change. What Sanity does is let front-end developers quickly describe complex data structures in JSON and get an instant real-time editing interface to go with it that they then can go on to customise in React. That's the totally new part.

Thinking About Content as Data

So instead of thinking about pages you need to think about objects and properties. What are the things that exist in the domain you're modelling? What are their properties?

Ok, a bit abstract perhaps. So say you're structuring content for a company, what do we then know about say, projects, what are their properties?

Perhaps they have start and end date. Perhaps they have people who worked on them, the people are probably modelled as separate objects, but the reference that runs between them might need a role for that specific project. There's probably a textual description. What formatting of the text do you want to allow? The list goes on.

This is how the thinking generally runs. Of course it helps to have sketches of mobile screens and web pages when imagining the data you will need. But often we find ourselves also including properties that aren't for pure digital display, but rather are useful when your data is sent to other systems. Like adding an extra checkbox to an image to tell the PDF conversion pipeline that the image looks really nice in portrait when printed in a book.

We think that it should take minutes to sketch out a data model in your schema, see it reflect in a user interface that you can instantly deploy as a production ready solution to editors.

So what then is Sanity?

The headless paradigm has lots of implications for the design of publishing systems and we believe that Sanity is the headless CMS done just right.

Develop locally – You want to let people use their front-end skills to customise the editing environment so the Content Studio runs on your laptop as a javascript bundle written in React.js. It deploys with a single line in the CLI.

Straight to production – Backing the content studio is a platform as a service comprising a real-time database and an asset pipeline, both edge cached.

Together the two allow you to craft better user experiences for editors as well as quickly shift into production on a solid, globally edge cached platform.

Rich data model – In order to capture content as structure you need to have a rich data model. So in addition to the standard fields we built polymorphic arrays, compound objects and hard references.

Developer Friendly – The data model is described in code and immediately reflects in a comfortable user interface that editors can get to work on. The UI adapts to any data structure you can express. Command line tools push and pull data sets and deploys the editor in a single line of code.

Powerful query language – You want to be able to get all the data to render a page through a single query that traverses references. You can re-project fields to get objects that are perfect for your display logic. You might also want to listen for changes so we have a real-time API that allows you to persist queries and stream changes to documents. This is also used to make the editing environment real-time collaborative.

Structured Text – You want rich text to have strict schemas and to be stored as a data structure. You also need to be able to intersperse text with objects that have friendly editing interfaces. Don't store a map as an image – simply allow map-objects in your text and store them as coordinates and a zoom-factor. Users simply click on the map and get the interface.

Full freedom – You also want full freedom to change the editing interface to best suit the needs of the people doing the editing. Perhaps you should display data from a third party API to populate some fields? Maybe integrate with a machine learning platform and surface insights in real-time? Sanity is built in React and plug-ins allow you to provide components that compose or override existing functionality.

Deploy with confidence – the Sanity platform runs on Google Cloud Services. In addition to using Google's edge cache to speed asset delivery we also provide our own edge cache for API calls.

Previous: Getting startedNext: Content Studio