1# Headless CMS Guide
2 
3Reference for choosing, modeling, and implementing a headless CMS for marketing content.
4 
5## When to Use This Reference
6 
7Use 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.
8 
9---
10 
11## Headless vs Traditional CMS
12 
13A headless CMS separates content management from presentation. Content is stored in a structured backend and delivered via API to any frontend.
14 
15### When Headless Makes Sense
16 
17- Multiple frontends consume the same content (web, mobile, email)
18- Developers want full control over the frontend stack
19- Content needs to be reused across channels
20- You're building with a modern framework (Next.js, Remix, Astro)
21- Marketing needs structured, reusable content blocks
22 
23### When Traditional Works Better
24 
25- Small team with no dedicated developers
26- Simple blog or brochure site
27- WYSIWYG editing is a hard requirement
28- Budget is tight and WordPress/Webflow does the job
29 
30### Decision Checklist
31 
32| Factor | Headless | Traditional |
33|--------|----------|-------------|
34| Multi-channel delivery | Yes | Limited |
35| Developer control | Full | Constrained |
36| Non-technical editing | Requires setup | Built-in |
37| Time to launch | Longer | Faster |
38| Content reuse | Native | Manual |
39| Hosting flexibility | Any frontend | Platform-dependent |
40 
41---
42 
43## Content Modeling for Marketing
44 
45### Core Principles
46 
471. **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.
482. **Separate content from presentation.** Store the headline text, not the styled headline. Presentation belongs in the frontend.
493. **Design for reuse.** If testimonials appear on 5 pages, create a Testimonial type and reference it — don't duplicate.
504. **Keep models flat.** Deeply nested structures are hard to query and maintain. Prefer references over nesting.
51 
52### Common Marketing Content Types
53 
54| Type | Key Fields | Notes |
55|------|-----------|-------|
56| **Landing Page** | title, slug, hero, sections[], seo | Modular sections for flexibility |
57| **Blog Post** | title, slug, body, author, category, tags, publishedAt, seo | Rich text or Portable Text body |
58| **Case Study** | title, customer, challenge, solution, results, metrics[], logo | Link to related products/features |
59| **Testimonial** | quote, author, role, company, avatar, rating | Reference from landing pages |
60| **FAQ** | question, answer, category | Group by category for programmatic pages |
61| **Author** | name, bio, avatar, social links | Reference from blog posts |
62| **CTA Block** | heading, body, buttonText, buttonUrl, variant | Reusable across pages |
63 
64### SEO Fields Checklist
65 
66Every page-level content type needs:
67 
68- `metaTitle` — 50-60 characters
69- `metaDescription` — 150-160 characters
70- `ogImage` — 1200x630px social preview
71- `slug` — URL path segment
72- `canonicalUrl` — optional override
73- `noIndex` — boolean for excluding from search
74- `structuredData` — optional JSON-LD override
75 
76---
77 
78## Editorial Workflows
79 
80### Draft → Review → Publish Cycle
81 
821. **Draft** — Author creates or edits content
832. **Review** — Editor reviews for accuracy, brand voice, SEO
843. **Approve** — Stakeholder signs off
854. **Schedule** — Set publish date/time
865. **Publish** — Content goes live via API
87 
88### Preview APIs
89 
90All major headless CMS platforms support draft previews:
91 
92- **Sanity**: Real-time preview with `useLiveQuery` or Presentation tool
93- **Contentful**: Preview API (`preview.contentful.com`) with separate access token
94- **Strapi**: Draft & Publish system with `status=draft` query parameter (v5; replaces v4's `publicationState`)
95 
96Set up a preview route in your frontend (e.g., `/api/preview`) that authenticates and renders draft content.
97 
98### Roles and Permissions
99 
100| Role | Can Create | Can Edit | Can Publish | Can Delete |
101|------|:----------:|:--------:|:-----------:|:----------:|
102| Author | Yes | Own | No | Own drafts |
103| Editor | Yes | All | Yes | Drafts |
104| Admin | Yes | All | Yes | All |
105 
106Exact permission models vary by platform. Sanity uses role-based access. Contentful has space-level roles. Strapi has granular RBAC.
107 
108---
109 
110## Platform Comparison
111 
112| Feature | Sanity | Contentful | Strapi |
113|---------|--------|------------|--------|
114| Hosting | Cloud (managed) | Cloud (managed) | Self-hosted or Cloud |
115| Query Language | GROQ | REST / GraphQL | REST / GraphQL |
116| Free Tier | Generous | Limited | Open source (free) |
117| Real-time Collab | Yes (built-in) | Limited | No |
118| Best For | Developer flexibility | Enterprise multi-locale | Budget / self-hosted |
119| Content Modeling | Schema-as-code | Web UI | Web UI or code |
120| Media Handling | Built-in DAM | Built-in | Plugin-based |
121 
122### Sanity
123 
124**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.
125 
126**Considerations**: Steeper learning curve for non-developers. Studio customization requires React knowledge. Vendor lock-in on GROQ queries.
127 
128**Marketing fit**: Best when developers and marketers collaborate closely. Strong for content-heavy sites with complex models.
129 
130### Contentful
131 
132**Strengths**: Mature enterprise platform. Excellent multi-locale support. Strong ecosystem of integrations. Composable content with Studio. Well-documented APIs.
133 
134**Considerations**: Pricing scales with content types and locales. Two separate APIs (Delivery and Management). Rate limits can be tight on lower plans.
135 
136**Marketing fit**: Best for enterprises with multi-market content needs. Good when you need established vendor reliability.
137 
138### Strapi
139 
140**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.
141 
142**Considerations**: Self-hosting means you handle infrastructure. Smaller ecosystem than Sanity/Contentful. V5 migration can be significant from V4.
143 
144**Marketing fit**: Best for teams with DevOps capability who want full control and no vendor lock-in. Good for budget-conscious projects.
145 
146### Others Worth Knowing
147 
148- **Hygraph** — GraphQL-native, strong for federation and multi-source content
149- **Keystatic** — Git-based, good for developer-content hybrid workflows
150- **Payload** — TypeScript-first, self-hosted, code-configured like Sanity
151- **Builder.io** — Visual editor with headless backend, good for non-technical marketers
152- **Prismic** — Slice-based content modeling, strong Next.js integration
153 
154---
155 
156## Integration with Marketing Skills
157 
158### Programmatic SEO
159 
160Use 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.
161 
162### Copywriting
163 
164CMS content models enforce consistent structure. Define fields that match your copy frameworks (headline, subheadline, social proof, CTA). See **copywriting** skill.
165 
166### Site Architecture
167 
168URL 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.
169 
170### Email Sequences
171 
172Pull 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.
173 
174---
175 
176## Implementation Checklist
177 
178- [ ] Define content types based on page types and reusable blocks
179- [ ] Add SEO fields to every page-level content type
180- [ ] Set up preview/draft mode in your frontend
181- [ ] Configure roles and permissions for your team
182- [ ] Create sample content for each type before building frontend
183- [ ] Set up webhook notifications for content changes (rebuild triggers)
184- [ ] Document content guidelines for editors (field descriptions, character limits)
185- [ ] Test content delivery performance (CDN, caching, ISR)
186- [ ] Plan migration strategy if moving from existing CMS
187 
188---
189 
190## Relevant Integration Guides
191 
192- [Sanity](../../../tools/integrations/sanity.md) — GROQ queries, mutations, CLI
193- [Contentful](../../../tools/integrations/contentful.md) — Delivery/Management APIs, publishing
194- [Strapi](../../../tools/integrations/strapi.md) — REST CRUD, filters, document API
195