Static sites have a content problem. Developers love them... fast, secure, cheap to host, easy to reason about. But hand someone from the marketing team a Git repository and ask them to write a blog post in Markdown, and you will get a very specific look. The one that says "I did not sign up for this."
That is the problem Netlify CMS set out to solve. Give non-technical content editors a friendly admin interface while keeping the entire content layer in Git. No database. No server-side CMS. Just files in a repository with a nice UI on top.
It was a clever idea. And while the project has evolved (it is now called Decap CMS after Netlify handed it off to the community in 2023), the core concept remains relevant for anyone building content-driven static sites.
The Git-Based CMS Model
Traditional CMS platforms like WordPress store content in a database. When someone visits your site, the server queries the database, assembles the page, and sends it to the browser. That works, but it introduces a running server, a database, and the entire security and performance surface area that comes with them.
Netlify CMS took a different approach. Content lives as flat files (Markdown, JSON, YAML) in your Git repository. The CMS is a single-page React application that sits at /admin on your site. When an editor creates or updates content, the CMS commits the change directly to your repository. That commit triggers a rebuild of your static site, and the updated content goes live.
The entire content history is in Git. Every change is a commit. Every version is recoverable. There is no database to back up because there is no database.
For teams already working in Git, this model is elegant. Content and code live in the same repository, go through the same review process, and deploy through the same pipeline. Content changes can go through pull requests just like code changes, which is genuinely useful for teams that need editorial review workflows.
How the Architecture Works
The setup is straightforward. You add two files to your project:
- An
index.htmlfile in your/admindirectory that loads the CMS application from a CDN - A
config.ymlfile that defines your content model... what fields each content type has, where the files are stored, and how they are formatted
The content model in config.yml maps directly to your file structure. If you define a "blog" collection with title, date, and body fields, the CMS creates Markdown files with those fields in YAML frontmatter. Your static site generator reads those files and builds pages from them.
Authentication happens through Netlify Identity (their built-in auth service) and Git Gateway, which proxies Git API calls so editors do not need direct repository access. An editor logs in, writes content through the admin UI, and the CMS handles the Git operations transparently.
This is important: the editor never sees Git. They see a form with text fields, rich text editors, image uploaders, and dropdown menus. The Git layer is invisible to them.
What It Does Well
The strengths of this approach are real:
- No vendor lock-in. Your content is Markdown and YAML files in a Git repository. If you want to switch CMS tools tomorrow, your content is already in the most portable format possible.
- Version control for free. Every content change is a Git commit with full history, diffs, and the ability to revert. Try getting that from a database-backed CMS without custom tooling.
- No infrastructure to manage. The CMS is a static JavaScript file. There is no server, no database, no admin panel to secure and patch.
- Editorial workflow support. The CMS can create draft branches and pull requests, giving teams a review-and-approve process for content changes.
- Works with any static site generator. Hugo, Jekyll, Gatsby, Eleventy, Astro... if your generator reads files from a directory, the CMS can manage them.
For small to medium sites with a handful of content editors, this setup works well. A company blog, a documentation site, a simple marketing site with a few pages... these are the sweet spots.
Where It Struggles
Honesty time. The Git-based CMS model has real limitations that you should understand before committing to it.
Scale is the first issue. Every content update triggers a full site rebuild. On a site with 50 pages, that rebuild takes seconds. On a site with 5,000 pages, it can take minutes. Content editors waiting several minutes to see their changes live is a poor experience compared to platforms where publishing is instant.
Rich content modeling is limited. The config.yml content model supports basic field types... strings, text, images, lists, nested objects. But if you need complex relationships between content types, conditional fields, or custom validation logic, you are going to hit the ceiling quickly. Purpose-built headless CMS platforms like Contentful or Sanity handle complex content modeling far better.
Real-time collaboration does not exist. Two editors working on the same content can create merge conflicts, just like two developers editing the same file. The CMS does not have real-time locking or conflict resolution.
Media handling is basic. Image uploads go into a folder in your repository. There is no image processing pipeline, no automatic resizing, no CDN-based image optimization built in. For image-heavy sites, you will need to bolt on a separate media management solution.
The Transition to Decap CMS
In February 2023, Netlify announced that Netlify CMS would be renamed to Decap CMS and handed to the community for ongoing development. The code is the same; the npm packages changed from netlify-cms to decap-cms, and the project moved to a community-maintained GitHub organization.
This transition matters for a practical reason: Netlify is no longer investing engineering resources into the CMS. It is community-maintained now. That is not inherently bad... some of the best open-source tools are community-maintained... but it does mean the pace of feature development and bug fixes depends on volunteer contributors.
If you are starting a new project today, you should evaluate whether Decap CMS is actively maintained enough for your needs, or whether a more actively developed alternative like TinaCMS (which also uses a Git-based approach but with a more modern architecture) would be a better fit.
When to Use a Git-Based CMS vs. a Headless CMS
The decision comes down to complexity and team size.
| Factor | Git-Based CMS (Decap/Netlify CMS) | Headless CMS (Contentful, Sanity) |
|---|---|---|
| Content editors | 1-5 people | 5+ people or multiple teams |
| Content model complexity | Simple (blog posts, basic pages) | Complex (relationships, variants, localization) |
| Publishing speed | Minutes (rebuild required) | Seconds (API-driven) |
| Hosting cost | Free (no backend) | $0-$500+/month depending on tier |
| Vendor lock-in risk | None (files in Git) | Moderate (proprietary API) |
If you are building a developer blog, a small business site, or a documentation portal with a small editorial team, a Git-based CMS is hard to beat on simplicity and cost. If you are building a multi-language marketing site with 20 content editors, structured content that feeds multiple channels, and real-time publishing requirements... you need a headless CMS.
Making It Work Today
If you decide a Git-based CMS is right for your project, here is how to set it up for success:
- Keep your content model flat. Avoid deeply nested structures. The simpler your
config.yml, the fewer edge cases you will encounter. - Use a modern static site generator. Astro, Hugo, and Eleventy all work well with file-based content and have fast build times that minimize the publish delay.
- Set up editorial workflows. Use the CMS draft/review feature to route content through approval before it goes live. This is especially important if non-technical editors are publishing directly.
- Handle media externally. Use Cloudinary, Imgix, or your CDN's image processing for media management instead of relying on Git-stored images. (Note: Netlify Large Media, which previously offered Git LFS-based media handling, has been deprecated.) Large media files in Git repositories create performance problems.
- Monitor build times. As your site grows, build times will increase. Incremental builds (available in some generators) can help, but plan for this from the start.
The Git-based CMS model is not glamorous, but it is practical. For the right use case... small team, simple content, budget-conscious... it removes an entire layer of infrastructure from your stack. And in web development, every layer you can remove is a layer you do not have to maintain.
Choosing the right CMS is one of the most important architectural decisions for a content-driven site. If you are weighing your options, let's talk through what fits your situation.