The Markdown vs CMS decision comes down to who edits the content. If the people writing are comfortable with Git and a text editor, Markdown files in an Astro content collection are the simplest and most durable option. If editors need a web interface but the site is small, a Git-based CMS adds that interface while content stays in your repository. If several editors, workflows, scheduled publishing or multiple channels are involved, use an API-based headless CMS.
Key Takeaways
- Markdown in Git: no cost, no lock-in, versioned with code. Needs Git-comfortable editors.
- Git-based CMS (Decap, Keystatic, TinaCMS): web editing, content still in the repo.
- API-based CMS (Sanity, Storyblok, Contentful, Payload): roles, workflows, media library, multi-channel.
- All three plug into the same
getCollection()API in Astro, so you can move later.
Decision flow
- Do all editors use Git? Yes → Markdown.
- Is it one site with a handful of non-technical editors? Yes → Git-based CMS.
- Do you need roles, approval workflows or scheduled publishing? Yes → API-based CMS.
- Is the content reused in an app, emails or other sites? Yes → API-based CMS.
- Do editors need live visual editing on the page? Yes → API-based CMS with preview support (and on-demand rendering for previews).
- Otherwise → Markdown, and revisit when the team grows.
Compared
| Markdown in Git | Git-based CMS | API-based CMS | |
|---|---|---|---|
| Editing | Text editor, Git | Web UI, commits behind the scenes | Web UI |
| Content lives | Your repo | Your repo | Vendor’s database |
| Cost | Free | Usually free / low | Free tier, then per seat or usage |
| Preview | Local dev server, preview deploys | Preview deploys | Built-in previews, visual editing |
| Roles and workflows | Git permissions | Basic | Full |
| Media library | Folders | Basic | Full, with image CDN |
| Lock-in | None | Low | Higher |
| Astro integration | glob() loader |
glob() loader |
Loader package or fetch() |
| Publishing | Commit → deploy | Save → commit → deploy | Webhook → rebuild, or live fetch |
Common situations
| Situation | Choose |
|---|---|
| Developer’s personal blog | Markdown |
| Startup marketing site, founders edit copy occasionally | Markdown or Git-based CMS |
| Agency site handed to a client’s marketing person | Git-based CMS |
| Publication with five writers and an editor | API-based CMS |
| Docs maintained by engineers | Markdown (Starlight) |
| Product catalogue shared with an app | API-based CMS |
Moving later is easier than you think
Because Astro reads every source through content collections, switching from Markdown to a CMS mostly means swapping the loader in src/content.config.ts. Pages that call getCollection('blog') don’t change, as long as the new source produces the same fields. Keep your schema as the contract, use slugs as ids, and store rich text as Markdown or HTML so it exports cleanly.
The detailed comparison of CMS products is in choosing a headless CMS for Astro, and loaders are covered in the Astro content collections guide.
Komal blog and editorial themes keep content in Markdown collections, so you can start with files and add a CMS later. Browse blog and editorial themes.
FAQ
Is Markdown enough for a business website?
Often, yes, if the people updating it can edit files or are happy to send changes to a developer. Add a Git-based CMS when that becomes a bottleneck.
Can I use a CMS and Markdown in the same Astro site?
Yes. Define one collection per source; for example, blog posts from a CMS and docs from Markdown.
Astro maintains setup guides for many CMSs.