The CMS Tax

Every CMS comes with overhead. WordPress needs PHP, a database, regular security updates, plugin management, and hosting that can run all of it. Drupal adds layers of abstraction and configuration complexity. Even headless CMS platforms like Contentful or Sanity introduce API dependencies, vendor lock-in, and monthly costs that scale with usage.

For a corporate website with 20-50 pages, a blog with weekly posts, and a team of 2-3 people who edit content, this overhead is difficult to justify. The CMS doesn’t make the content better — it just makes the infrastructure more complex.

There’s an alternative that’s been quietly powering technical documentation, developer blogs, and increasingly, business websites: Markdown files managed in a Git repository.

How the Markdown Approach Works

The concept is straightforward. Content lives as .md files in your project’s source code repository. Each file contains frontmatter (structured metadata) and body content written in Markdown syntax. A static site generator processes these files at build time and produces HTML pages.

---
title: "Our Approach to Web Development"
description: "How we build websites that perform, scale, and last."
date: 2025-05-15
author: "Fevzi Günalp"
---

## Architecture First

We start every project with architecture decisions, not design
mockups. The technology choices you make in week one determine
the maintenance burden you carry for years.

### Why This Matters

Most agencies start with a template and work backward...

The static site generator (Astro, Hugo, Eleventy, or similar) reads these files, applies layout templates, and outputs a complete website. The workflow is:

  1. Author writes or edits a Markdown file
  2. Changes are committed to Git
  3. A CI/CD pipeline triggers a build
  4. The built site deploys to the hosting platform
  5. The updated content is live within minutes

Why Markdown Wins for Most Content

Version Control

Every change to every piece of content is tracked in Git. You can see who changed what, when, and why. You can revert any change instantly. You can review content changes with the same pull request workflow you use for code.

Try getting this from WordPress. You’ll find a revision history buried in the admin panel that tracks changes per-post but lacks the comprehensive audit trail and branching capabilities of Git.

No Database

Markdown files are text. They don’t need a database to store them, a connection pool to access them, or a backup strategy to protect them. They sit alongside your code in a Git repository that’s already backed up to a remote origin (GitHub, GitLab, or similar).

This eliminates an entire class of infrastructure concerns: database hosting, migration management, backup verification, and the ever-present risk of data loss from a corrupted or compromised database.

Portability

Your content is not locked into any platform. If you switch from Astro to Hugo, from Netlify to Cloudflare Pages, or from one developer to another, your content moves with zero migration effort. It’s text files. Any tool can read them.

Compare this to migrating content out of WordPress (database export, content transformation, media file extraction) or from one headless CMS to another (API mapping, schema translation, asset migration). Vendor lock-in with Markdown is essentially zero.

Performance

There’s no runtime content retrieval. No API call to fetch content. No database query. The content is compiled into HTML at build time and served as static files. This is as fast as web content delivery gets.

Editing Experience

This is where the CMS advocates push back: “But non-technical people can’t edit Markdown!” This objection was valid five years ago. Today, several tools make Markdown editing accessible to non-developers:

  • Prose.io and Netlify CMS (now Decap CMS): Browser-based editors that commit Markdown files to Git through a visual interface
  • Forestry (now Tina CMS): A visual editing layer on top of Git-based Markdown content
  • VS Code with Markdown preview: For team members comfortable with a code editor, the side-by-side preview makes Markdown editing approachable
  • Obsidian or Typora: Desktop Markdown editors with rich formatting toolbars

The gap between CMS editing and Markdown editing has narrowed to the point where it’s a minor workflow adjustment, not a fundamental barrier.

Content Architecture with Markdown

Markdown files become truly powerful when combined with structured frontmatter and a content schema system. Modern static site generators like Astro provide content collections that validate your content structure at build time.

// src/content/config.ts — Astro content collection schema
import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    summary: z.string(),
    date: z.date(),
    author: z.string(),
    category: z.enum([
      'Engineering',
      'Design',
      'Strategy',
      'Culture'
    ]),
    featured: z.boolean().default(false),
    draft: z.boolean().default(false),
  }),
});

const services = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    description: z.string(),
    icon: z.string(),
    order: z.number(),
  }),
});

export const collections = { blog, services };

This schema definition ensures that every blog post has the required fields with the correct types. If an author creates a post without a title or with an invalid category, the build fails with a clear error message. This is compile-time content validation — something most CMS platforms don’t offer.

Organizing Content

File system structure maps naturally to content types:

src/content/
├── blog/
│   ├── static-first-architecture.md
│   ├── automation-with-n8n.md
│   └── edge-computing.md
├── services/
│   ├── web-development.md
│   ├── automation.md
│   └── infrastructure.md
├── team/
│   ├── fevzi-gunalp.md
│   └── ...
└── case-studies/
    ├── client-a-redesign.md
    └── client-b-automation.md

Each directory is a content collection with its own schema. No database tables, no CMS configuration panels — just directories and files.

Handling Media

The main legitimate challenge with Markdown-based content is media management. A CMS typically provides an asset library with upload, cropping, and optimization features. With Markdown, you need an alternative approach:

  • Optimized at build time: Tools like astro:assets or @11ty/eleventy-img process and optimize images during the build step
  • External media: Use a dedicated image CDN (Cloudinary, imgix) for images that need dynamic transformations
  • Co-located assets: Store images alongside their content files for simple projects
<!-- Using Astro's image optimization -->
![Team meeting](/src/assets/images/team-meeting.jpg)

<!-- Using an external image CDN -->
![Office](https://res.cloudinary.com/yoursite/image/upload/w_800,q_auto/office.jpg)

When You Actually Need a CMS

There are scenarios where a traditional or headless CMS is the right choice:

  • Large editorial teams with complex publishing workflows (review, approval, scheduling)
  • Non-technical content teams who publish multiple times daily and can’t adopt a Markdown workflow
  • Content-heavy applications with thousands of entries and complex relational data
  • Multi-language content with translation management requirements
  • Real-time content updates where build-time rendering is too slow

For these cases, a headless CMS like Sanity or Storyblok, used as a data source at build time, gives you CMS authoring with static output. It’s the best of both worlds, though it adds complexity and cost.

Making the Decision

Ask these questions about your project:

  1. How many people edit content? If fewer than 5, Markdown workflows are manageable.
  2. How often does content change? Daily or less frequently favors Markdown + build. Multiple times per hour favors a CMS.
  3. How technical is the content team? Markdown requires basic comfort with text formatting. If that’s a non-starter, a CMS is necessary.
  4. How much do you value portability? If avoiding vendor lock-in matters, Markdown is unmatched.
  5. What’s the content volume? Under 1,000 pages, Markdown is comfortable. Above that, build times and file management may favor a CMS.

For the majority of corporate websites we build, Markdown is the right answer. It’s simpler, more portable, more performant, and less expensive than any CMS. The editing experience gap has closed enough that it’s no longer a compelling counterargument for small teams.

Your content is text. Store it as text.