Choosing a CMS in 2025: A Guide for Technical Teams

If you're building a blog, docs, or a knowledge base in 2025, the options are overwhelming.

Sanity or Payload? Nextra or GitBook? Git-based CMS like Keystatic? Or just raw MDX in GitHub with zero CMS at all?

We went through the same decision for Char. This post maps the territory so you don't have to burn as many cycles on it.

I won't tell you "X is the best CMS." Instead, I'll show you what each category is good at, what it quietly locks you into, and when you probably don't need a CMS at all.

This is Part 3 of our publishing series.

1. Why We Write Our Blog in an IDE
2. Why Our CMS Is GitHub
3. Choosing a CMS in 2025 (You are here)
4. Don't Use a CMS Until You Absolutely Need One
5. Docs Edition: What to Use for Developer Documentation
6. How We Built Char's Publishing Stack
7. Building an Editorial Workflow with GitHub and Slack

Step 0: Decide What Problem You're Actually Solving

Start by answering these questions instead:

1. Who is writing most of the content?

   • engineers only
   • mixed team (engineers + PMs + marketing)
   • non-technical people only

2. What are you publishing?

   • technical blog
   • product docs / API reference
   • internal knowledge base
   • marketing pages / landing pages

3. How often does content structure change?

   • almost never (simple posts, titles, tags)
   • sometimes (new fields, types, locales)
   • constantly (complex content models, multiple channels)

4. How long should your content survive?

   • 6 months?
   • 2–3 years?
   • 10+ years and multiple stack rewrites?

Once you answer these, the CMS choice mostly falls out.

The Four Big Buckets of CMS Options

1. No CMS, just Git + MDX
2. Git-based CMS (visual UI on top of your repo)
3. Headless CMS (API-first like Sanity, Payload)
4. Hosted doc/knowledge platforms (GitBook, Notion, etc.)

1. No CMS: Just Git + MDX (What We Use)

At Char, content lives as .mdx files in the repo. We write in Zed / Cursor / VS Code. GitHub is the CMS. PRs are drafts, merges are publish. CI handles link checking, OG generation, and so on.

Pros:

• Maximum portability. Plain files last decades.
• Works perfectly with modern frameworks (Next.js, TanStack Start, Astro) via MDX support
• Diffable, reviewable, scriptable
• No vendor lock-in, no schema migrations
• Ideal if your writers are engineers

Cons:

• Non-technical teammates need training or another surface
• No drag-and-drop media UI out of the box
• No built-in content dashboard, workflows, or roles

If your team is very technical and you're early-stage, this is almost always the correct default. You can always add a Git-based or headless CMS later without throwing anything away.

2. Git-Based CMS: "UI for Your Repo" (Keystatic & Friends)

Git-based CMS tools give you a visual editor that talks directly to your Git repo. Content stays as Markdown/MDX/JSON/YAML in the repository, but non-technical people get a web UI.

Keystatic makes Markdown, JSON, and YAML content in your codebase editable via a browser UI, and syncs changes directly to GitHub or the local file system without introducing a separate database.

Other players include TinaCMS, Decap, and similar tools.

Pros:

• Fits the "content as code" philosophy
• You keep all the benefits of Git: history, branches, PRs
• Non-engineers get a UI to edit content safely
• Still portable. Files stay in Git. No proprietary content lake.
• Good fit for Next.js / Remix / Astro setups

Cons:

• Another admin app to host and configure
• The UI has limits vs raw MDX
• You're tied into their config models and upgrade cycle
• Not as "enterprise omnichannel" as big headless CMSs

Use this when you like the Git + MDX approach but want PMs, designers, or marketing to tweak copy and metadata without opening an IDE.

3. Headless CMS: Sanity, Payload, and the Heavy Hitters

Headless CMS = content backend with APIs. You define schemas, models, relationships, and the CMS exposes content via REST/GraphQL to web, mobile, native apps, signage, whatever.

Sanity

Sanity offers a composable "Content Cloud" with an open-source Studio built in React/TypeScript, highly customizable for flexible content modeling. Sanity

Content is stored in their Content Lake as structured JSON, not HTML, so you can reuse it across multiple frontends. It provides real-time collaboration, visual editing, and omnichannel delivery.

Payload

Payload is a dev-first, code-first headless CMS built with Node.js, TypeScript, and React, positioning itself as a Next.js-native backend framework. Payload

You configure everything in TypeScript. It's open-source (MIT) and self-hostable. It can function as a headless CMS, app framework, or digital asset management layer. It fits naturally into a modern JS/TS stack with Next.js projects.

Pros of headless CMS:

• Powerful schema & content modeling
• Omnichannel delivery across web, mobile, internal tools
• Good editorial UIs, roles, workflows
• Often built-in localization and scheduling

Cons:

• More infrastructure complexity: hosting, API auth, migrations
• Content lives in a proprietary structure. Export is possible but not as simple as copying MDX files.
• Your team must think in terms of schemas and content models, not just posts.

Use this when you're running a content platform with multiple surfaces, locales, and non-technical editors who need structured workflows.

4. Docs / Knowledge Platforms: GitBook, Notion & Co.

Sometimes you don't need a CMS. You need a docs product.

GitBook

GitBook positions itself as a documentation + knowledge base platform for technical teams, with a polished block-based editor, site customization options, and Git Sync that lets you connect to GitHub/GitLab for a docs-as-code workflow. GitBook

It works well if you want a hosted, beautiful docs site with search, navigation, versioning, and collaboration. It supports optional Git synchronization for teams that still want Markdown in repos.

Notion, Confluence, and similar tools live in the same category but less focused on developers.

Pros:

• Fastest path to a polished docs or knowledge base
• Low setup cost, almost no infrastructure
• Very friendly for non-technical stakeholders
• Often have built-in AI-assisted search and summaries

Cons:

• Content portability is limited. Exports are often messy.
• Integrating tightly into your product site can be harder
• Your roadmap depends on someone else's product decisions

Use this when you want a docs site ready tomorrow, UX matters more than control, and you don't mind long-term platform dependency.

Summary: The Four Buckets at a Glance

5. Special Case: Nextra & Friends (Frameworks, Not CMSs)

Tools like Nextra are not CMS platforms but content-focused frameworks built on Next.js that make it easy to build docs and blog sites with Markdown/MDX and opinionated themes. Nextra

Nextra gives you prebuilt docs/blog UI (sidebar, nav, search glue), MDX-first authoring, and works well for developer docs and personal blogs.

You still choose how to manage content: plain files, a Git-based CMS, a headless CMS feeding MDX remotely, etc.

This is the category Char's stack resembles: modern React/MDX frontend with content-first in Git.

A Simple Decision Matrix

If you're not sure, default to Git + MDX now. Add a Git-based or headless CMS later only if reality forces you to.

Most teams overestimate how much CMS infrastructure they need in the first 2–3 years.

Things People Don't Talk About Enough

1. Lock-in doesn't hurt until you're tired and busy

Headless CMS and hosted doc platforms feel great in the first year. Export and migration problems show up right when you least want to deal with them: when the product is working and you're stretched thin.

Plain files in Git are boring. Boring is good.

2. Editors become culture

If your team writes in Markdown/MDX in Git, your culture becomes "open a PR," "leave a comment," "fix it in the repo."

If your team writes in a SaaS editor, your culture becomes "who has access?", "which space is that in?", "did the integration break again?"

Neither is inherently right, but they lead to different organizations.

3. Your writers will change over time

Today your blog might be the founder and engineers. In two years, it might be devrel, marketing, product, and support.

Choosing a stack that evolves from IDE-only → Git-based CMS → headless CMS with minimal rewriting matters.

Git + MDX is a good foundation for that.

So… What Would I Use If I Were Starting Today?

For a technical founder starting a new product:

• For blog + marketing + simple docs, I'd start with Next.js or TanStack Start + MDX + GitHub, no CMS.
• When non-engineers need to edit regularly, I'd add a Git-based CMS like Keystatic on top. Keystatic
• If I hit real omnichannel, multi-locale complexity, I'd consider Sanity or Payload and accept the trade-offs. Sanity or Payload
• For standalone internal knowledge bases, I'd probably just use GitBook. GitBook

That's basically Char's philosophy: start with the simplest thing that respects developer workflows, portability, and long-term ownership.

The tools will change. Your content shouldn't have to.

This is Part 3 of our publishing series.

1. Why We Write Our Blog in an IDE
2. Why Our CMS Is GitHub
3. Choosing a CMS in 2025 (You are here)
4. Don't Use a CMS Until You Absolutely Need One
5. Docs Edition: What to Use for Developer Documentation
6. How We Built Char's Publishing Stack
7. Building an Editorial Workflow with GitHub and Slack