Hybrid Content Architecture: Adding Markdown to a Contentful Workflow
Contentful handles the structured parts of my site. It publishes fast, it triggers GitHub Actions, and it works well for content that needs fields or assets.
But not all content needs that. A lot of what I write now starts with AI, changes often, and fits better in a code-driven workflow. Markdown gives me a way to work at that speed without touching a CMS.
So I added Markdown as a second content path—because it fits how I actually build.
Why Markdown?
Markdown solves three problems at once.
AI output fits Markdown
AI generates Markdown by default. It’s already structured and ready to drop into the repo. No copying into fields. No formatting cleanup.
Markdown fits code-driven workflows
Since Markdown lives in Git, it enables:
- version control and history
- branch-based content workflows
- AI-assisted editing in code
- direct file manipulation
- automated deployments via Git
This lets content evolve naturally with the rest of the codebase.
No unnecessary CMS use
AI drafts change fast.
Putting every version into a CMS would create noise, API usage, and clutter.
In Markdown, drafts are just Git commits. Simple and cheap.
Why Contentful Stays in the Mix
Some content still benefits from a CMS:
- structured pieces
- assets
- content models
- things that need a UI
- content that editors might touch later
Contentful remains responsible for those items, and it still triggers builds the moment something is published.
Markdown doesn’t replace Contentful.
It just handles a different part of the workflow.
Ownership Rules (Simple)
Ownership is determined by where the content lives.
Contentful owns its content
If something is created in Contentful and stays there, Contentful controls it. The hybrid resolver loads it directly from Contentful when no Markdown file exists.
Markdown owns its content
If content starts in Markdown, it's owned in Markdown.
The hybrid resolver prefers Markdown files and only falls back to Contentful if no Markdown file exists.
No dual-editing
There is no scenario where both systems edit the same item.
The hybrid resolver enforces this: if a Markdown file exists for a slug, it uses that file and ignores the Contentful version entirely.
Content Flow
The system handles two distinct paths:
Contentful → Site
When Contentful publishes, a webhook fires.
GitHub Action triggers a Vercel redeploy, which:
- builds the site
- hybrid resolver checks for Markdown first
- falls back to Contentful if no Markdown exists
- deploys the result
Note: Contentful content is not automatically synced to Markdown. To create a Markdown file from Contentful, you run npm run pull:contentful manually. Once synced, Markdown becomes the source of truth.
Markdown → Site
Markdown content lives in the repo, so:
- commit and push to GitHub
- Vercel automatically builds and deploys
- hybrid resolver uses the Markdown file
- no CMS interaction needed
Both paths converge at deployment, but they have different workflows.
AI in the Workflow
This is the real benefit of adding Markdown.
Because content is in code, you can use AI tools to:
- generate new posts directly in Markdown
- edit and refine content with AI assistance
- use version control for AI-generated drafts
- generate hero images (via
npm run generate:images) - iterate quickly without CMS overhead
This workflow fits naturally with AI-assisted development.
In Markdown, AI becomes part of your editing process, not a separate system.
Publishing Flow
Both paths converge into the same deployment pipeline:
Contentful → Webhook → GitHub Action → Vercel → App
Markdown → Git Push → Vercel → App
Same deploy target.
Different creation paths.
Summary
I added Markdown to make room for AI-assisted workflows and faster iteration.
Contentful still handles the structured pieces and triggers automated deployments.
Markdown handles the code-driven and AI-assisted content creation.
Two systems.
Clear ownership.
Hybrid resolution that prefers Markdown, falls back to Contentful.