headless-cms

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

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

When Traditional Works Better

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

  1. 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.
  2. Separate content from presentation. Store the headline text, not the styled headline. Presentation belongs in the frontend.
  3. Design for reuse. If testimonials appear on 5 pages, create a Testimonial type and reference it — don't duplicate.
  4. 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:

Editorial Workflows

Draft → Review → Publish Cycle

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

Preview APIs

All major headless CMS platforms support draft previews:

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

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

Relevant Integration Guides