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 charactersmetaDescription— 150-160 charactersogImage— 1200x630px social previewslug— URL path segmentcanonicalUrl— optional overridenoIndex— boolean for excluding from searchstructuredData— 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
useLiveQueryor Presentation tool - Contentful: Preview API (
preview.contentful.com) with separate access token - Strapi: Draft & Publish system with
status=draftquery parameter (v5; replaces v4'spublicationState)
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 emails 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