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 Hyprnote.
This post is my attempt to map the territory so you don’t have to burn as many cycles.

I’m not going to tell you “X is the best CMS.”
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 Hyprnote's Publishing Stack

Step 0: Decide What Problem You’re Actually Solving

“Which CMS should we use?” is the wrong first question.

Better questions:

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

Let’s define the buckets first:

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.)

We’ll walk through each, then I’ll give you a “when to pick which” section.

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

This is what we do at Hyprnote:

• 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, etc.

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. Your content is still Markdown/MDX/JSON/YAML in the repository, but non-technical people get a web UI.

Keystatic is a good example of the modern version of this: it 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 in this space include TinaCMS, Decap, etc., which a lot of devs compare as “Git-based CMS for React/Next.” "Git-based CMS for React/Next"

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 in Git), no proprietary content lake
• good fit for Next.js / Remix / Astro setups

Cons:

• another admin app to host/configure
• the UI still has limits vs raw MDX
• you’re tied into their config models and upgrade cycle
• not as “enterprise omnichannel” as big headless CMSs

When to use this:

You like our Git + MDX approach, but you want PMs / designers / marketing to be able to tweak copy and metadata without opening an IDE.

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

Headless CMS = content backend with APIs. Frontend is up to you.

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

Sanity

Sanity is one of the big names here:

• it offers a composable “Content Cloud” with an open-source Studio built in React/TypeScript, highly customizable, and aimed at flexible content modeling. Sanity
• content is stored in their Content Lake as structured JSON, not HTML, so you can reuse it across multiple frontends. Content Lake
• it provides real-time collaboration, visual editing, and omnichannel delivery.

This is great when you have multiple frontends, lots of content types, and non-technical editors who need good UX.

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), self-hostable, and can double as a headless CMS, app framework, or digital asset management layer. open-source
• it fits naturally into a modern JS/TS stack with Next.js-based projects. Next.js-based projects

Pros of headless CMS:

• powerful schema & content modeling
• omnichannel delivery (web, mobile, internal tools)
• good editorial UIs, roles, workflows
• often built-in localization, scheduling, etc. localization, scheduling, etc.

Cons:

• more infra complexity (hosting, API auth, migrations)
• content now 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”

When to use this:

You’re not just running a blog. 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’s very good if you want:

• a hosted, beautiful docs site
• search, navigation, versioning, and collaboration
• optional Git synchronization for teams that still want Markdown in repos Git synchronization

Notion, Confluence, etc. live in the same general category (less dev-focused, more general knowledge management).

Pros:

• fastest path to a nice-looking docs/knowledge base
• low setup cost, almost no infra
• very friendly for non-tech stakeholders
• often have built-in AI-assisted search/summary now AI-assisted search/summary

Cons:

• content portability is limited (exports often messy)
• integrating tightly into your product site can be harder
• you’re living inside someone else’s product roadmap

When to use this:

You want a docs site 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/blog sites with Markdown/MDX and opinionated themes. Nextra

Think of Nextra as:

• prebuilt docs/blog UI (sidebar, nav, search glue)
• MDX-first authoring
• great for developer docs & personal blogs

You still choose how to manage content (just files, Git-based CMS, headless CMS feeding MDX remotely, etc.).

This is the category Hyprnote’s stack rhymes with: modern React/MDX front-end, but content-first in Git.

A Simple Decision Matrix (So You Don’t Overthink It)

You can ignore everything above and just use this:

If you’re not sure, default to:

Git + MDX now.
Add a Git-based or headless CMS later if reality forces you to.

Most teams overestimate how much “CMS” they need for the first 2–3 years.

Things People Don’t Talk About Enough

A few non-obvious things we learned while thinking about this for Hyprnote:

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 “founder + engineers.”
In two years, it might be “devrel + marketing + product + support.”

Choosing a stack that can evolve from IDE-only → Git-based CMS → headless CMS with minimal rewriting is underrated.

Git + MDX is a good foundation for that.

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

If I were a technical founder starting a new product today:

• 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 ever 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 and not overthink it. GitBook

That’s basically our philosophy behind Hyprnote’s own stack:
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 Hyprnote's Publishing Stack