marketingskills/skills/content-strategy/references/headless-cms.md

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

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:

• 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

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:

• 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 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