Thinking and Writing

Tips for Content Modelling with the Headless CMS Contentful

I’ve recently been working on a big project to migrate an existing website and its content over to the headless CMS Contentful. The project has been successful but its been a steep learning curve from a UX and content architecture perspective so I thought I’d share some of the things I’d learned along the way. Although this is written with Contentful in mind the same principles apply to other headless CMS platforms out there.

In a traditional CMS like Drupal you’d design content around page templates and modules in a headless CMS like Contentful you design collections of related content based around related themes called content models. The reason for this abstraction is that it allows content owners to distribute and reuse these blocks of content over a variety of different platforms without worrying about breaking templates.

This all sounds straightforward in principle but, if you’re working with an existing website, getting there can be a bit of a head scratcher!

Like with any CMS migration project we started the project with a thorough content audit to identify any pages or sections that were redundant. We followed this by scouring the site looking for examples of content blocks and referencing these in a shared Google sheet. A side benefit of this forensic approach was uncovering inconsistencies in the content which could be addressed during the migration. Armed with the content block audit we were then able to start thinking about content models and their relationships.

If you only take one piece of advice from this post make it this one. Much in the same way you wouldn’t try building a house without an architectural plan don’t try content modelling in Contentful without a content map diagram! We used Google’s to visualise our map because its easy to use, free and shareable. I did initially consider just using whiteboard but as our site was quite complex it made sense to have something we could use which could contain a lot of detail. Spreadsheets are great for listing items but useless at showing the connections between the content models. Having the high level view is really useful and, as your map grows, having something to reference back to when searching for errant fields in invaluable.


One part of a *much* larger content model diagram

When designing the content models theres a balance in Contentful between too high level or too granular. As a rule of thumb we tried to group blocks of text together along with their title and any other formatting. Images and other media was kept in separate fields. The only exception to the text block rule was if we could foresee a time when we’d want to use a subset of that text in another area then we’d break it out into another field. The whole team decided on the field names and content model labels as a group activity to ensure we had collective buy-in and understanding. Try and avoid having optional or nice to have fields in the model (trust me, it makes things easier when it comes to building the site). If you have a need for an optional field make it a separate content model and reference it.

One of the hardest things we found in the early days of the project was trying to design the IA, content map and associated models without falling back to thinking about page templates but it was worth persevering to do it the right way. When we were happy with where the model was at in the map we then began the process of building out the models in Contentful and migrating the content across from the old CMS to the new and the developers could crack on with building out the front end.

So there you go, I hope you found this post useful. Heres a summary of my top tips:

  1. Plan as much as you can before you start building content models in Contentful. Changing fields and models (especially if you have content already in the models) is a hassle.
  2. Use a mapping tool like to help visualise your content map and keep it up to date to use for reference later on.
  3. Avoid the temptation to fall back to designing around page templates. Always think about collections of content and the relationships between these collections in your site.
  4. Let the team decide the naming conventions for your models and fields collectively. Having that shared ownership helps with buy in for the new CMS and also helps reduce those “where does that bit go?” questions.
  5. If you’re working with existing content start the process with a thorough content audit and weed out any inconsistencies you have in your content. Remember garbage in garbage out!

From a UX/Content persons perspective Contentful is a great CMS and allows for lots of interesting possibilities that would be hard to achieve with a traditional CMS. Its worth considering if you have a large, content heavy website with lots of interdependencies. Finally If you decide to take the plunge with Contentful and need a hand wrangling the content give me a shout!