Previewing CMS Content in Gatsby Workflows

Hero image for Previewing CMS Content in Gatsby Workflows. Image by Brad Helmink.
Hero image for 'Previewing CMS Content in Gatsby Workflows.' Image by Brad Helmink.

Preview is where static‑site architecture meets editorial reality.

Editors do not only need to publish content. They need to see what they are about to publish. They need to check headings, images, rich text, links, embedded entries, and page layout before the public site changes.

With Gatsby and a headless CMS, that preview workflow needs to be planned. It is not automatic just because the production site builds from CMS data.

Separate Published Builds from Preview Builds

The production Gatsby build should usually use published content.

Preview needs draft content. That may mean using a preview API, a separate token, a preview environment, or a deployment that is protected from public indexing.

Do not casually mix draft data into the production build. If a draft API token leaks into production generation, unpublished content can appear in static output.

The article on why Gatsby and Contentful work well together covers the production pairing. Preview is the extra workflow layer that makes editors confident.

Make Editor Expectations Explicit

Preview can mean different things:

  • an instant draft preview
  • a preview build after saving
  • a deploy preview for a branch
  • a staging site
  • a local developer preview

Those are not interchangeable. An editor expecting instant preview will not be happy with a five‑minute build, even if the build is technically correct.

Define:

  • how preview is opened
  • how fresh the content is
  • whether unpublished references appear
  • whether preview is password protected
  • whether search engines can reach it
  • who fixes failed previews

Handle Rich Text and References Properly

Preview should exercise the same rendering rules as production.

If production uses custom rich text renderers, embedded entries, code blocks, responsive images, and internal link resolution, preview should use them too. Otherwise editors are not previewing the real page.

The article on rendering CMS rich text safely in Gatsby and React explains why those renderers need deliberate rules.

Draft references are especially important. A draft article may link to a draft author, category, image, or related entry. The preview path needs to decide whether to show those drafts or fail clearly.

Use Webhooks for Build‑Based Preview Carefully

If preview depends on a build, CMS webhooks can trigger it.

That is similar to production publishing, but with different data and different visibility. Preview builds may be more frequent, and they may be triggered by draft saves rather than publish events.

Consider:

  • build queue noise
  • failed preview notifications
  • stale preview deployments
  • token permissions
  • preview URL stability
  • who can access preview links

The workflow should feel predictable to editors, not like a hidden deployment system.

Protect Preview from Indexing

Preview pages should not appear in search results.

Use appropriate protection:

  • authentication
  • noindex headers or meta tags
  • robots rules
  • unguessable URLs are not enough on their own

If the preview site includes draft content, treat it as private. Search engines are not the only concern. Preview URLs can be shared, logged, or found in browser history.

Test Preview as an Editor

Developer‑focused testing often misses preview friction.

Test:

  • save draft
  • open preview
  • update title
  • update image
  • add an embedded entry
  • remove a required field
  • preview an unpublished reference
  • publish
  • confirm production rebuild

This is a workflow test, not only a rendering test.

Preview becomes even more important during platform changes. CMS preview should be a migration requirement covers why preview belongs in the scope before a team changes framework, CMS, or hosting model.

Wrapping Up

Gatsby preview works best when it is treated as its own publishing workflow.

Keep preview data separate from production, define freshness expectations, reuse production renderers, protect draft output, and test the path as an editor. A static site can have a good editorial experience, but it needs deliberate preview design.

Key Takeaways

  • Preview and production builds should use separate content access rules.
  • Editors need to know how fresh preview is and what it represents.
  • Rich text, images, links, and embedded entries should render like production.
  • Preview builds need access control and indexing protection.
  • Test preview by following the editor workflow end to end.

Relevant Services

Want to find out more?

If you need senior hands‑on support with a complex React or Next.js platform, migration, performance issue, or technical SEO problem, send me the context and I'll tell you where I can help.

Get in touch