Learn Gatsby - Headless CMS & Content Platforms

#Introduction

A headless CMS separates content from presentation: editors manage content in a dashboard, while Gatsby pulls it via an API and renders it at build time. One piece of content can be used across many surfaces without duplication.

Episode 21 covers integrating multiple content sources, best practices for headless setups, preview workflows and content updates, and the approach of managing content as code.

#Integrating Multiple Content Sources

#Source Plugins for CMSs

Each CMS provides a source plugin that pulls the data and maps it into GraphQL. An example with Contentful:

npm install gatsby-source-contentful

Configure the plugin in gatsby-config with the access token from an environment variable:

Configure gatsby-source-contentful

module.exports = {
  plugins: [
    {
      resolve: "gatsby-source-contentful",
      options: {
        spaceId: process.env.CONTENTFUL_SPACE_ID,
        accessToken: process.env.CONTENTFUL_ACCESS_TOKEN,
      },
    },
  ],
}

process.env.CONTENTFUL_SPACE_ID reads the value from an environment variable so the token is never written in code. Without this convention, every team member risks leaking secrets into the repository. The same pattern applies to Sanity and Strapi — only the plugin name and options differ.

Initially the plugin reads all content on the first build. For large projects, check the available options — such as downloadLocal when components need image files locally — and read the plugin documentation before adjusting. The options you pick affect the number of API requests and the amount of data entering the build.

#Combining Multiple Sources

Gatsby can merge many sources at once: markdown from the repo, content from Contentful, and products from an e-commerce API. Gatsby's GraphQL unifies them into a single schema, so a page can pull data from several sources in one query. This model is called the unified content graph — one reason Gatsby suits architectures that use many content platforms.

Another benefit: relationships between sources form automatically. A post can use an image from the CMS and metadata from the repo on one page without manually syncing data between the two systems.

The more sources there are, the more consistency matters. Watch each CMS's API rate limits and align fetching times across sources. Regularly verify that slugs and key fields don't collide between sources, because hidden data duplication often surfaces later.

#Best Practices for Headless Setups

#Consistent Content Modeling

Design the content model before writing lots of content. Clear field definitions keep editorial work consistent and keep Gatsby queries simple. Avoid duplicating the same type across many CMSs unless it's genuinely needed — for instance, one type for marketing content and another for technical content. Involve editors from the modeling stage so the field names used actually make sense to non-technical team members.

#Mapping to GraphQL

If a CMS's default field names don't fit, use gatsby-plugin-graphql-config with custom resolvers, or transform them in gatsby-node via onCreateNode to normalize the structure before pages are created. Normalizing in one place makes every component read a consistent data shape. Keep this normalization documented so anyone can trace where a field comes from.

If several CMSs share a similar schema, consider union or interface types in Gatsby GraphQL. That way, a component renders any content with the same shape, regardless of its source. This pattern keeps components simple as the list of sources grows.

#Per-Environment Content Variants

Many CMSs provide separate environments for development and production. Use the development environment for local previews and store the environment ID in an environment variable, so the source plugin always pulls the data that matches the environment. Remember, preview environments often contain draft data — make sure that data doesn't leak into production pages.

#Preview Workflows and Content Updates

#Preview Builds

A preview workflow builds the site from draft data so editors can see the result before publishing. Platforms like Gatsby Cloud support per-content previews; every time a draft changes, a new preview build runs and the editor sees a preview URL. This flow bridges the gap between the editors writing content and the developers building the view. Ideally, previews use unpublished data so the publishing decision stays entirely with the editors.

#Webhooks and Updates

When content is published, the CMS sends a webhook that triggers a production build. For large content, enable incremental builds so only the changed pages are rebuilt, avoiding a full build every time. Make sure the webhook can only be called by the CMS — hosting platforms usually provide a token to secure this endpoint. Add logging for every triggered build so it's easy to trace issues when content doesn't appear in production.

#Managing Content as Code

#Markdown and MDX in Git

An alternative to a headless CMS is storing content as Markdown or MDX files in the repository. Content gets versioned, reviewed through pull requests, and deployed together with code. This approach is called content as code.

Markdown content frontmatter

---
title: "Contoh Artikel"
published_date: "2026-08-10"
tags: [gatsby, cms]
---
 
Ini adalah isi artikel dalam Markdown.

With content as code, content changes are never scattered: everything is recorded in git, complete with the same review and tests as code changes. Choose a headless CMS when the editorial team needs a visual dashboard, and content as code when the team is already comfortable with git.

#When to Choose Which Approach

There's no universal answer. A CMS suits non-technical teams and large content volumes, while Markdown files suit developers and content that rarely changes. Both can coexist in a single Gatsby project — for example, a landing page from Markdown and long-form articles from a CMS. Re-evaluate this choice as team size and content volume grow.

#Conclusion

Key takeaways:

• Source plugins map CMS content into GraphQL.
• Access tokens must go through environment variables.
• Gatsby unifies many sources into one schema.
• Preview builds allow draft review before publishing.
• Webhooks trigger builds when content is published.
• Content as code leverages git versioning.

In the next episode, episode 22, we'll discuss observability and monitoring — monitoring site performance with analytics, tracking build metrics, client-side error reporting, and user behavior analysis.