Markdown vs Headless CMS
January 10, 2025 2 min read
By Jamie Lee
markdown cms architecture
The core question
Should you store content as Markdown files or in a Headless CMS?
The answer depends on who writes content and how often it changes.
Markdown vs Headless CMS (Sanity, Contentful)
High-level positioning
| Aspect | Markdown (.md / .mdx) | Headless CMS (Sanity / Contentful) |
|---|---|---|
| Primary audience | Developers | Non-technical editors |
| Content location | Git repo | External service |
| Update model | Git commit → deploy | Live publishing |
| Build model | Build-time | Build-time or runtime |
| Infra cost | Free | Paid (at scale) |
| Complexity | Very low | Medium → high |
| SEO | Excellent | Excellent |
| Best for | Blogs, docs, marketing | Editorial, product content |
Authoring Experience
Markdown
✅ Pros:
- GitHub-native
- Easy PR reviews
- No CMS UI needed
- Offline editing
- Perfect for dev teams
❌ Cons:
- Not editor-friendly
- No previews without tooling
- No role-based permissions
Sanity / Contentful
✅ Pros:
- Visual editor
- Rich previews
- Permissions & roles
- Structured relationships
- Image pipelines
❌ Cons:
- Setup time
- Learning curve
- Vendor lock-in
Rule of thumb
If developers write content → Markdown
If editors write content → CMS