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](../../../tools/integrations/sanity.md) — GROQ queries, mutations, CLI
- [Contentful](../../../tools/integrations/contentful.md) — Delivery/Management APIs, publishing
- [Strapi](../../../tools/integrations/strapi.md) — REST CRUD, filters, document API
Add headless CMS reference and integration guides (#174 ) 2026-03-09 23:21:58 -07:00			`# 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`

feat: v2.0 skill renames and CRO consolidation (#291 ) 2026-05-13 22:05:15 -07:00			`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.`
Add headless CMS reference and integration guides (#174 ) 2026-03-09 23:21:58 -07:00
			`---`

			`## 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](../../../tools/integrations/sanity.md) — GROQ queries, mutations, CLI`
			`- [Contentful](../../../tools/integrations/contentful.md) — Delivery/Management APIs, publishing`
			`- [Strapi](../../../tools/integrations/strapi.md) — REST CRUD, filters, document API`