Headless CMS Guide¶

Reference for choosing, modeling, and implementing a headless CMS for marketing content.

When to Use This Reference¶

Use this when selecting a CMS for a new project, designing content models for marketing sites, setting up editorial workflows, or connecting CMS content to programmatic pages.

Headless vs Traditional CMS¶

A headless CMS separates content management from presentation. Content is stored in a structured backend and delivered via API to any frontend.

When Headless Makes Sense¶

Multiple frontends consume the same content (web, mobile, email)
Developers want full control over the frontend stack
Content needs to be reused across channels
You're building with a modern framework (Next.js, Remix, Astro)
Marketing needs structured, reusable content blocks

When Traditional Works Better¶

Small team with no dedicated developers
Simple blog or brochure site
WYSIWYG editing is a hard requirement
Budget is tight and WordPress/Webflow does the job

Decision Checklist¶

Factor	Headless	Traditional
Multi-channel delivery	Yes	Limited
Developer control	Full	Constrained
Non-technical editing	Requires setup	Built-in
Time to launch	Longer	Faster
Content reuse	Native	Manual
Hosting flexibility	Any frontend	Platform-dependent

Content Modeling for Marketing¶

Core Principles¶

Think in types, not pages. A "Landing Page" is a content type with fields not an HTML file. This lets you reuse components across pages.
Separate content from presentation. Store the headline text, not the styled headline. Presentation belongs in the frontend.
Design for reuse. If testimonials appear on 5 pages, create a Testimonial type and reference it don't duplicate.
Keep models flat. Deeply nested structures are hard to query and maintain. Prefer references over nesting.

Common Marketing Content Types¶

Type	Key Fields	Notes
Landing Page	title, slug, hero, sections[], seo	Modular sections for flexibility
Blog Post	title, slug, body, author, category, tags, publishedAt, seo	Rich text or Portable Text body
Case Study	title, customer, challenge, solution, results, metrics[], logo	Link to related products/features
Testimonial	quote, author, role, company, avatar, rating	Reference from landing pages
FAQ	question, answer, category	Group by category for programmatic pages
Author	name, bio, avatar, social links	Reference from blog posts
CTA Block	heading, body, buttonText, buttonUrl, variant	Reusable across pages

SEO Fields Checklist¶

Every page-level content type needs:

metaTitle 50-60 characters
metaDescription 150-160 characters
ogImage 1200x630px social preview
slug URL path segment
canonicalUrl optional override
noIndex boolean for excluding from search
structuredData optional JSON-LD override

Editorial Workflows¶

Draft Review Publish Cycle¶

Draft Author creates or edits content
Review Editor reviews for accuracy, brand voice, SEO
Approve Stakeholder signs off
Schedule Set publish date/time
Publish Content goes live via API

Preview APIs¶

All major headless CMS platforms support draft previews:

Sanity: Real-time preview with useLiveQuery or Presentation tool
Contentful: Preview API (preview.contentful.com) with separate access token
Strapi: Draft & Publish system with status=draft query parameter (v5; replaces v4's publicationState)

Set up a preview route in your frontend (e.g., /api/preview) that authenticates and renders draft content.

Roles and Permissions¶

Role	Can Create	Can Edit	Can Publish	Can Delete
Author	Yes	Own	No	Own drafts
Editor	Yes	All	Yes	Drafts
Admin	Yes	All	Yes	All

Exact permission models vary by platform. Sanity uses role-based access. Contentful has space-level roles. Strapi has granular RBAC.

Platform Comparison¶

Feature	Sanity	Contentful	Strapi
Hosting	Cloud (managed)	Cloud (managed)	Self-hosted or Cloud
Query Language	GROQ	REST / GraphQL	REST / GraphQL
Free Tier	Generous	Limited	Open source (free)
Real-time Collab	Yes (built-in)	Limited	No
Best For	Developer flexibility	Enterprise multi-locale	Budget / self-hosted
Content Modeling	Schema-as-code	Web UI	Web UI or code
Media Handling	Built-in DAM	Built-in	Plugin-based

Sanity¶

Strengths: GROQ query language is powerful and flexible. Schema defined in code (version-controlled). Real-time collaborative editing. Portable Text for rich content. Generous free tier.

Considerations: Steeper learning curve for non-developers. Studio customization requires React knowledge. Vendor lock-in on GROQ queries.

Marketing fit: Best when developers and marketers collaborate closely. Strong for content-heavy sites with complex models.

Contentful¶

Strengths: Mature enterprise platform. Excellent multi-locale support. Strong ecosystem of integrations. Composable content with Studio. Well-documented APIs.

Considerations: Pricing scales with content types and locales. Two separate APIs (Delivery and Management). Rate limits can be tight on lower plans.

Marketing fit: Best for enterprises with multi-market content needs. Good when you need established vendor reliability.

Strapi¶

Strengths: Open source, self-hosted option. Full control over data. No per-seat pricing. Customizable admin panel. Plugin ecosystem. REST by default, GraphQL via plugin.

Considerations: Self-hosting means you handle infrastructure. Smaller ecosystem than Sanity/Contentful. V5 migration can be significant from V4.

Marketing fit: Best for teams with DevOps capability who want full control and no vendor lock-in. Good for budget-conscious projects.

Others Worth Knowing¶

Hygraph GraphQL-native, strong for federation and multi-source content
Keystatic Git-based, good for developer-content hybrid workflows
Payload TypeScript-first, self-hosted, code-configured like Sanity
Builder.io Visual editor with headless backend, good for non-technical marketers
Prismic Slice-based content modeling, strong Next.js integration

Integration with Marketing Skills¶

Programmatic SEO¶

Use CMS as the data source for programmatic pages. Store structured data (FAQs, comparisons, city pages) as content types and generate pages from queries. See programmatic-seo skill.

Copywriting¶

CMS content models enforce consistent structure. Define fields that match your copy frameworks (headline, subheadline, social proof, CTA). See copywriting skill.

Site Architecture¶

URL structure, navigation hierarchy, and internal linking all depend on how content is organized in the CMS. Plan your content model and site architecture together. See site-architecture skill.

Email Sequences¶

Pull CMS content into email templates for consistent messaging across web and email. Case studies, testimonials, and blog posts can feed email nurture sequences. See email-sequence skill.

Implementation Checklist¶

[ ] Define content types based on page types and reusable blocks
[ ] Add SEO fields to every page-level content type
[ ] Set up preview/draft mode in your frontend
[ ] Configure roles and permissions for your team
[ ] Create sample content for each type before building frontend
[ ] Set up webhook notifications for content changes (rebuild triggers)
[ ] Document content guidelines for editors (field descriptions, character limits)
[ ] Test content delivery performance (CDN, caching, ISR)
[ ] Plan migration strategy if moving from existing CMS

Relevant Integration Guides¶

Sanity GROQ queries, mutations, CLI
Contentful Delivery/Management APIs, publishing
Strapi REST CRUD, filters, document API

2026 Galyarder Labs. Galyarder Framework.