Once a team decides their static site needs a CMS, the first real choice is where the content should live: in the git repository with the rest of the site, or in a separate content service. I have a preference, which I will get to at the end, but both are sensible and the right answer depends on the site.

Two ways to store content

A git-based CMS treats your repository as the database. Content is stored as Markdown, YAML or JSON files, the same files a developer would edit by hand. The CMS gives editors a friendly screen and commits their changes.

A headless API CMS has its own database. Editors work in its web app, and your static site generator fetches content from its API at build time. “Headless” means it manages content but does not produce the website itself.

Everything else in this comparison follows from that one difference.

How a git-based CMS works

An editor signs in to the CMS and opens a post.
The CMS reads the Markdown file from your repository and shows it as a form: title, date, body, image.
The editor saves. The CMS writes the file back and makes a commit.
Your host sees the new commit and rebuilds the site.

Because the content is files, developers, designers working with AI assistants and editors all change the same source. A template change and a content change sit side by side in the same history.

Some git-based tools run as an admin page you host within your site. Others are hosted services that connect to your git provider and handle sign-in, roles and images for you.

How a headless API CMS works

A developer defines a content model in the CMS: a “post” has a title, date, body and image.
Editors create and edit entries in the CMS’s web app. They are stored in the vendor’s database.
At build time, the static site generator calls the CMS API, gets the entries and renders pages.
When an editor publishes, the CMS sends a webhook to trigger a rebuild.

The templates live in git; the content does not. The two are connected by the content model and the API.

Editing and previews

Both approaches can give editors a good writing experience. Differences in practice:

Previews. Headless CMSs often have built-in preview features, though they take setup work. Git-based tools can show a rendered preview of the content and rely on your host’s branch previews for the full page.
Rich fields. Headless CMSs tend to have more field types and validation out of the box. Git-based tools map to front matter, which is flexible but simpler.
Media. Headless CMSs usually serve images from their own asset service. Git-based tools commit images to the repository, which keeps everything together but grows the repo over time.
Speed to live. Both trigger a rebuild, so both take as long as your build.

Developer workflow

This is where the two differ most.

With a git-based CMS, developers keep their normal workflow. Content is in files they can grep, diff and change in bulk. A designer can ask an AI assistant to restructure a page and see both the template and its content in one place. Branches and pull requests work for content too.

With a headless CMS, content changes happen in another system. Bulk changes go through the CMS’s interface or API. Local development needs API access or a content export. Changing the content model means changing it in the CMS and in the templates together. None of this is hard, but it is more coordination.

Content in git also suits AI-assisted work well, because an assistant can read the actual content when it changes a template. See static sites in the agentic age.

History, backup and audit

Git-based: every content change is a commit. Full history, author, rollback, and your content is backed up anywhere the repository is cloned.
Headless: history and backup depend on the vendor. Many keep revisions, but often for a limited time or on higher plans. Exports are possible but need planning.

Cost and lock-in

Headless API CMS pricing commonly scales with seats, content entries, locales or API usage. That is reasonable for large content operations and can be expensive for many small sites.

Git-based tools vary. Self-hosted ones may be free but leave you to run sign-in and hosting. Hosted ones charge per site or per user.

On lock-in, git-based tools have a clear advantage. If you stop using one, your content is still plain files in your repository and the site keeps building. Leaving a headless CMS means exporting content, transforming it and rewiring templates.

Which to choose

Choose a git-based CMS when:

The site is a marketing site, brochure site or blog with a handful of editors.
You want one source of truth and one history.
Developers or designers will keep working on templates directly, often with AI help.
You look after many small sites and want each to stand alone.

Choose a headless API CMS when:

The same content feeds several sites, apps or channels.
A large editorial team needs complex workflows, localisation or approvals.
Content volume is large enough that files become unwieldy.

For a wider look at setting up either, see the complete guide to adding a CMS to a static site.

My take

For the sites most agencies and in-house teams run, I think git-based wins. Keeping content in the repository keeps the whole site in one place, with one history and nothing extra to back up or migrate. Headless CMSs are excellent at what they are built for, which is content shared across many channels, but most marketing sites are not that. Mabel is a git-based CMS for Jekyll, so I am biased. Weigh my view with that in mind.