Structured Content

How Stackbit works with structured content, along with content modeling basics.

Stackbit's only real requirement that affects your site's code is that content must be structured and separated from code. This guide explores ways in which that requirement can be fulfilled.

This guide covers the following concepts:

Content-Driven Development

While frameworks use various different terms for what becomes a web page — routes, paths, views, etc. — Stackbit refers to these entities as pages. Following modern best practices, pages are often comprised of components.

Composable Page Overview
Composable Page Overview

Content Modeling Basics

For page content to be editable, its content must be represented by a single structured data object coming from your content source. Likewise, making components editable means their content is structured in your content source, either referenced or directly embedded in the page (more on this below).

Items of a similar structured are grouped together in the content source using a model. In other words, we can say that every editable page and component is represented by a model in your content source.

Types of Models

Stackbit uses three types of models:

  • Page: That which represents the shape of a page, as mentioned above. Example: A blog site that uses a Post model for its individual blog posts.
  • Data: Content objects which are meant either to stand alone and be accessed globally, or to be referenced from a page. Global example: A Header model that contains content for a site's main menu. Reference example: A blog site uses an Author model to apply rich attributes to Post content (via a reference field).
  • Object: Repeatable content that is embedded in another model (of any type). Component models are typically object models. See the composable page section below for a detailed example.

Here's an example of how elements on a web page may be modeled:

Modeling Elements on a Web Page
Modeling Elements on a Web Page
  • The header and footer content comes from globally-shared content objects of a data model.
  • The content specific to the page is wrapped in a page object.
  • Content for components within that page are of the object type, and are embedded within the page object.

Resolving Model Types

Most CMSs don't have this level of nuance in model types. Therefore, that resolution must be made within the Stackbit configuration. See below for how this works, based on the type of content source.

Defining API CMS Models

Stackbit automatically inherits the schema (collection of models) from the API CMS.

However, because most API CMSs don't have the concept of pages, page models must be enriched with Stackbit-specific attributes by setting type within the models property.

Whether Stackbit can resolve the distinction between the data and object type for the remaining (non-page) models depends on the behavior of the CMS.

Sanity Example: Because Sanity has the concept of documents and objects, all documents that aren't pages become data in Stackbit, which Sanity objects remain object in Stackbit.

Contentful Example: Contentful has no concept of model types. Everything is an entry. Therefore, all non-page models from Contentful are assumed to be data models.

Content Modeling for Git CMS

When using Git CMS as the content source (files in the repository), you may not have any concept of modeling, as you can technically use files as a content source without any sort of schema.

Stackbit requires that all content objects be defined by some model. Therefore, file-based content must be represented by model definitions in the Stackbit configuration file.

Composable Pages

One of the most powerful benefits of using Stackbit with a component-driven website is that you can create fully composable pages, minimizing the number of rigid templates developers need to provide.

Let's look at an example that combines structured content with composable pages.

Representing Components as Content
Representing Components as Content

Here, the page object coming from the content source is a structured object that has an id attribute (home-page), along with an embedded array of component data, as the sections property.

This sections data get mapped through your code (shown in the next graphic) to create a page made up of flexible content. This enables content editors to compose pages in any way they want.

Mapping a Page Object to Components
Mapping a Page Object to Components

This particular process varies from project to project. The simple example above is a stripped-down version of a JSX page that would handle the rendering of content in the browser shown on the right.

Template-Based Pages

Although fully-composable pages are a powerful editing tool, they may slow editors down in some instances. You aren't limited to creating composable pages with Stackbit.

For example, consider a blog post. There is generally no need to force composing the elements of the blog post on content creators. The heading, body, and other meta attributes should probably have their own position on the page.

In cases like this, you can have unique page-level models that bring their own specific fields that get mapped directly to some place in the page's template file.

Rigid Page Template Mapping
Rigid Page Template Mapping