Markdown, CMS or code: how content gets into a modern website
Content and code are separate on a modern site. Files, a content system or an API can feed it. Which fits which team, and what changes for editors.
The short answer
On a modern website, the content and the code that displays it are separate things. The code is a set of templates and components; the content is text, images and data that flow into them. That separation means the content can come from wherever suits the people who write it: files kept next to the code, a headless content system with a friendly editor, or an API of a system where the content already lives, such as a shop platform. The visitors always get the same fast static site. The choice is about the editors.
The three sources
| Source | How editing works | Fits | Watch out for |
|---|---|---|---|
| Files (Markdown) next to the code | Edit a text file with a light syntax; publish through the repository | Small teams, technical editors, documentation, knowledge bases | Non-technical editors find it awkward |
| Headless content system | A web editor with fields, previews, roles and media handling | Marketing teams, frequent publishing, several editors | Another subscription; choose one you can leave |
| An API of an existing system | Content managed where it already lives; the site reads it | Product data from a shop platform, listings from a property system, events from a calendar | The source’s speed and limits become yours |
Many sites use two: files for the pages that rarely change, a content system for the blog and campaigns, and an API for products.
What is the same whichever you choose
- Publishing triggers a build. The changed pages are produced and deployed within minutes.
- Previews before publishing. Editors see the page on a preview address before it goes live.
- Strict validation. Required fields, lengths and formats are checked at build time. A missing description or an oversized image is caught before anything is live. This knowledge base refuses to build if an article breaks its rules.
- Nothing runs in front of visitors. The editor is not the public site. Whatever happens in the content system, the live pages are finished files.
Choosing for your team
- Two or three people, comfortable with text and structure, publishing occasionally: files. No subscription, versioned by nature, fastest to set up.
- A marketing team publishing weekly, with images, drafts and approvals: a headless content system with a good editor and clean exports.
- Content that already lives in a system of record: read it from that system’s API; do not copy it.
What this means for you
The question is not “which CMS” but “where should our content live so the people who write it are comfortable and we can always take it with us”. Files, a headless system or an API are all fine sources for a fast static site. Pick for the editors, insist on a clean export, and let the build do the rest.
Frequently asked questions
Do our editors need to learn Markdown?
Only if files are the right choice for your team, which they are for small, technical teams. For a marketing team a content system with a familiar editor is the right choice, and Markdown never appears. The developer decides the plumbing; the editors' experience decides the source.
Can we keep WordPress as the editor?
Yes, as a headless content source: editors keep the WordPress editor, the site is built and served as static pages from that content, and WordPress itself is no longer the public site. Familiar editing, none of the public-facing risks.
What happens when an editor publishes?
A build runs automatically, producing the changed pages, and they go live within minutes. Previews are available before publishing on most setups. Nobody logs into a server, and nothing runs in front of visitors.
Sources
- Astro documentation: Connect a CMS to Astro (accessed 2026-09-11)