Documentation is not the same thing as blogging.
Docs are a product. People rely on them to unblock themselves, integrate with you, debug issues, and understand how your system actually works. So the tools you'd use for blog posts don't always work for docs.
Docs need structure, navigation, versioning, API examples, sidebars, and searchable knowledge. They also need to be maintainable by a real team — engineers, PMs, support, devrel — not just whoever has access to the CMS.
This post breaks down what tools you should consider in 2025 if you're building developer documentation from scratch.
There Are Really Only Five Kinds of Docs Systems
Every modern docs system falls into one of these:
-
Pure File-Based (MD/MDX)
→ Docusaurus, Nextra, Mintlify Open Source, MkDocs, Astro + MDX -
Git-Based CMS Layer on Top
→ Keystatic, TinaCMS, Decap -
Headless CMS with Docs Frontend
→ Sanity, Payload, Contentful powering a docs UI -
Hosted Docs Platforms
→ GitBook, Readme.com, Mintlify Cloud, Archbee, Notion (light docs) -
Custom, In-Product Documentation
→ Your own framework + components (what many top devtools do)
Each has a different cost model, maintenance profile, and failure mode.
1. Pure File-Based Docs (MDX) — The Default for Technical Teams
This includes Docusaurus, Nextra, MkDocs / Material for MkDocs, Astro + MDX, and TanStack Start + MDX. This is the modern "docs-as-code" standard.
Pros
- Lives in Git → versioned, diffable, PR-reviewable
- MD/MDX gives you unlimited flexibility
- Easy to automate (scripts, linting, link checking, TOC generation)
- Works perfectly with CI + preview deployments
- No vendor lock-in
- Very low maintenance overhead
- Free
Cons
- Requires engineers to maintain structure
- Non-technical contributors may need training
- No built-in search unless you configure it
- No built-in analytics, roles, review workflows
When to Use It
Use this if you're a technical team that wants control without premature complexity. It works well if you don't have 15 PMs writing docs every day.
For 80% of startups, file-based MDX docs will be the right answer. Vercel, Supabase, Clerk, Planetscale, PostHog, and most modern OSS projects use this approach.
2. Git-Based CMS Layer — Best Middle Ground
Tools like Keystatic, TinaCMS, and Decap CMS give you a visual UI for editing docs while still using Markdown/MDX in Git.
Pros
- Non-engineers can safely edit docs
- Still uses your repo as the source of truth
- No database migrations or content lakes
- Easy to adopt later (minimal migration)
Cons
- Another admin app to host and maintain
- UI may not support advanced MDX patterns
- Contributors still need to understand the repo structure
- Slight complexity overhead
When to Use It
Use this when your PMs, DevRel, Support, or Marketing team needs to contribute regularly, but you want to maintain the "content lives in Git" principle. It's the best middle ground.
3. Headless CMS for Docs — Powerful but Often Overkill
Using Sanity, Payload, or Contentful to power docs.
Pros
- Strong content modeling
- Great for enterprises with localization, versioning, workflows
- Good structured content for advanced API docs
- Great for multi-surface (web, app, internal tools)
Cons
- Massive configuration overhead
- Schema migrations become a real job
- Docs UI is never as natural as MDX
- Lock-in increases over time
- You maintain a CMS backend indefinitely
When to Use It
Use this if you're a larger organization with multiple products, multiple locales, and multiple teams updating docs. Think Stripe-level documentation needs. If you're under 100 employees, this is almost always unnecessary.
4. Hosted Docs Platforms — Fastest to Deploy, Most Lock-In
Examples include GitBook, Mintlify Cloud, Readme.com, Archbee, and Notion (for light docs).
Pros
- Beautiful out of the box
- Built-in search, analytics, versioning
- Great WYSIWYG editors
- Good for non-technical writers
- Fastest path to "we have docs"
Cons
- Hard to integrate tightly with your product or marketing site
- Proprietary content format (exports are messy)
- Limited MDX component support
- Outgrows you once you want custom layouts
- You become dependent on their roadmap
When to Use It
Use this if you need docs fast, your team is mixed-technical, and you don't mind platform reliance. This works well for teams in a hurry or companies without deep frontend capabilities.
5. Custom In-Product Docs — The Future for Some Teams
Many modern companies (Linear, Raycast, Warp, Replit) embed docs directly into their product or create heavily customized documentation systems with React/MDX component libraries, interactive playgrounds, copyable codeblocks, live components, search tied into product data, custom navigation patterns, and AI-assisted docs generation.
Pros
- Total control
- Can be integrated tightly with your app
- Interactive demos, live sandboxes, code runners
- Enables AI-native experiences
- Perfect branding
Cons
- Highest build & maintenance cost
- Requires strong frontend & infra engineering
- Docs become a product, not just content
When to Use It
Use this if you're building a developer platform and your docs are part of your differentiation. This is the final evolution stage.
So… Which Should You Use in 2025?
If your writers are engineers: use file-based MDX docs. You'll ship faster than with any CMS.
If non-engineers need to edit: add Keystatic or Tina. Don't jump to a headless CMS.
If you're large with multiple products and locales: consider Sanity or Payload, but only when structure becomes real pain.
If you need something live tomorrow: use GitBook or Mintlify Cloud. Accept the lock-in for speed.
If your docs are part of your product: build custom. This is where world-class developer tooling systems end up.
Things Most Teams Don't Realize About Docs
Docs age faster than blogs. They need pruning, refactoring, and maintenance. MDX makes this infinitely easier than any CMS.
Versioning is non-negotiable. If your API or SDK evolves, you need doc versioning. The simplest approach is a folder per version in Git. A CMS makes this a nightmare.
Search matters more than design. Your docs UI can be plain, but your search must be excellent. Algolia DocSearch, Pagefind, or a custom hybrid all work well.
Docs need to survive your future rewrites. Your framework will change. Your content shouldn't break with it. This is why MDX in Git is the gold standard.
What We're Betting On at Char
We're building our docs on TanStack Start + MDX, with a GitHub PR workflow, custom MDX components (callouts, tabs, code demos), automatic TOC + search, Keystatic as our team grows, and future interactive "live notebooks" tied to Char.
The principle is simple: docs are code. The best way to maintain code is with tools you already love.
This is Part 5 of our publishing series.
