Intro
You may have seen the terms structured content and content modeling a lot in recent years, often in semi-technical or non-technical publications.
Some developers may find it funny that these concepts are presented as a novelty: we've been working this way since forever! Relational databases are indeed all about schema and always have been. Take any monolith CMS such as WordPress or Drupal, and you will find a complex schema behind the scenes.
So why the renewed talk about structured content?
If you’re a techie, consider it from a Content Team member’s point of view: when working with a monolith CMS you don’t have to think much about the underlying schema. You could focus on knowing the tool and its intricacies. With headless CMSs, the content model is now explicitly visible to content editors - in all its deeply nested, cross-referenced glory.
Headless CMSs’ marketing efforts also focus on the cross-device adaptability of content, which translates into yet another level of content abstraction. The gospel of structured content is now front and center, starting with the sales pitch.
In practice, however, navigating in & editing nested content in its raw form is hard work. Here is the author going about adding a button to a page element, in super fast-forward:
Real-Life Hardships
Working with customers & prospects, we found that the hardships begin when the content model is still in its early stages, even before it blows up in complexity.
Say that you've launched a cool modern website based on structured content. The dev team worked hard on it, and it looks great. Assume that a few tech-savvy marketing team members have been taught to find their way around the CMS UI reasonably well.
One major issue that is soon to come up is that the page rendering code is still hard-coded in most parts. Too many visual changes the content team is asking for still require engineering time, which is always hard to come by. The site and page structure is rigid and not easy to change.
Over time, this inflexibility is tackled piecemeal, with more features added to the content model to allow for more editor control - while also making the model more complex.
When content editors want to create a new page, they have to go through a type of reverse engineering: while the actual outcome they seek is a visual layout, they have to mentally work out how the content model works, what it allows for, and what the limitations are.
As the model grows in complexity, this analysis becomes harder. It also gets harder as an editor to discover what tools you have at your disposal, and get inspired from all the ways you could use them for your needs.
Simply put, simplicity and flexibility seem to be contradicting.
A More Content-Driven Approach
Over time, we’ve adopted a system that we believe is striking a good balance between these two ends. It stands on two pillars: one is how the model and code are designed & developed. The second is how the editing environment should work.
First, design the content model to be inherently flexible from the get-go. Don't try to dumb it down to the most rigid structure. A useful inspiration for this step is Atomic Design. If you look into the code of our starters, you will find that we've made almost everything into editable, configurable content. Of course, a flexible model needs to be supported by flexible code. More on that in a minute.
Second, the editing environment needs to make this model usable by mortals. But this should not mean confining editors to a small box. Instead, here is what we focus on in our visual editor:
Enabling content editors to work visually, so the gap from the “picture in their head” to the actual tooling they use is much smaller. This applies not only to composing new content but also to editing existing parts: to edit a deeply-nested component, editors should be able to simply click and select it, rather than navigate down the content structure in the CMS backend UI.
Emphasizing presets at the page and component level. Rather than making editors start from a blank slate every time or duplicate an existing full page for the nth time, have a full gallery of templates showing them how components can be put to use. Editors should always have the ability to take a snapshot of an existing component and save it as a preset (see guide).
Making things more familiar by reusing the same components as possible, grouping related fields together, and customizing the editing experience (e.g. here and here).
How Modeling & Coding Are Affected
The following is a very concise version of a process that’s covered in detail in our documentation.
First, model your pages to be composable by design, all the way from their basic controls up to page sections and the full layout. Your model should let editors build pages by stacking sections of various types and re-order them as they like. Reuse sections between page layouts, and components within sections.
Next, adapt your components for composability: rather than allowing only hard-coded child components, make your code dynamically resolve the actual component from the content. Here’s a simplified example:
These principles are not specific to Stackbit, a specific CMS, or a certain web framework. They cover the first step: making your model & code truly modular. However, your content model is not yet a joy to use if you only use the CMS UI.
Making It Visual with Stackbit
The next step is to make the editing experience human-friendly, by enabling our visual editor to work over your content.
The technical steps to take are outlined in our tutorials and the guide to adding Stackbit to an existing site. One important note is that this process is often gradual:
First, add a simple configuration file that enables our visual editor to read your content schema and provide page-level editing. With this file alone, editors navigating the site within the visual editor will already be able to edit content fields in a side panel. However, in-page elements are not clickable yet at this stage.
To enable direct visual selection of page elements, and creating presets from components, the visual editor needs to know which DOM elements on the page correspond to which content pieces. This is done by adding HTML data attributes to these elements. Here’s what these look like:
<div data-sb-object-id="object id in the content source">
<h2 data-sb-field-path="title">{ title }</h2>
</div>Annotations are often the only type of modification to your code that's needed for Stackbit. It is important to note that you don’t have to - and really shouldn’t - try to annotate each and every component and field on your site. Instead, focus on the components & fields that matter most.
There are of course additional power features to unlock, which require some more work. For example, see style fields and sidebar customization. These are capabilities that you should normally add only after content editors can already start working.
To learn more, here is our recommendation:
Go through the Getting Started tutorial. It covers both working with a CMS and with simple files.
Read the conceptual guides to How Stackbit Works and Structured Content.
