skills/content-strategy/references/headless-cms.md
Reference for choosing, modeling, and implementing a headless CMS for marketing content.
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.
A headless CMS separates content management from presentation. Content is stored in a structured backend and delivered via API to any frontend.
| 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 |
| 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 |
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 overrideAll major headless CMS platforms support draft previews:
useLiveQuery or Presentation toolpreview.contentful.com) with separate access tokenstatus=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.
| 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.
| 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 |
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.
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.
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.
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.
CMS content models enforce consistent structure. Define fields that match your copy frameworks (headline, subheadline, social proof, CTA). See copywriting skill.
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.
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.