Engineering teams are rethinking how they build documentation. For years, the default advice for scaling teams was to pick a traditional Headless CMS to empower non-technical contributors. However, managing a CMS for technical documentation has become more complex. Sites now require interactive components, AI integration, and deep product linking. Under this weight, the traditional database-driven abstraction has started to break down.

Recently, Lee Robinson, VP of Developer Education at Cursor, shared why he migrated the documentation and marketing site for Cursor away from a Headless CMS back to raw Markdown. The reasoning was clear: for developer-focused content, database abstractions often create more friction than they solve.

He details this architectural shift in his analysis, Coding Agents & Complexity Budgets, explaining how removing the CMS layer allowed his team to iterate faster using AI agents.

This represents a broader move toward Docs-as-Code. In this model, teams treat documentation exactly like software. While this architecture solves the engineering problem, it introduces a collaboration challenge. This guide explores the architectural choices for modern documentation and why a Markdown CMS is the emerging solution.

1. The Headless CMS: Built for marketing, not docs

Headless CMS platforms like Contentful or Sanity deliver structured content via API. They excel at marketing pages built from text blocks, hero images, and testimonials. However, using a general-purpose platform as a CMS for technical documentation often leads to technical debt.

The component limit. Modern documentation is interactive. A standard CMS rich-text editor cannot easily handle multi-language code tabs, API playgrounds, or React components inside Markdown (MDX). Storing docs in a traditional database reduces your content to static text and images, losing the interactivity that makes modern docs valuable.

Version control limitations. Traditional CMSs lack native Git integration. This makes it difficult to track changes, review diffs, or roll back to previous versions. Engineers rely on Pull Request workflows to ensure quality. A CMS that bypasses this creates a disconnect between how you manage code and how you manage documentation.

2. Hosted docs platforms: Great editing, high lock-in

"All-in-one" platforms like GitBook or Mintlify offer a tempting promise: a beautiful site in minutes. They provide hosting, search, and editors out of the box. For early-stage startups with standard requirements, this is often the right choice.

However, relying on a hosted platform is effectively "renting" your infrastructure. As your product matures, the rigid structure of a rented platform often becomes a liability.

The customization ceiling. Hosted platforms impose strict limits on frontend architecture. If you need a custom authentication flow, deep analytics integration, or a unique layout, you will hit a wall. You cannot simply "eject" to a custom React app because your content is tightly coupled to the platform’s proprietary rendering logic.

The "source of truth" ambiguity. While many hosted platforms offer Git syncing, it is frequently fragile or unidirectional. The authoritative version of your content usually lives in the vendor’s database, not your repository. If the vendor changes their pricing or pivots their roadmap, your documentation is trapped within their ecosystem.

3. Static MDX sites: The engineering ideal

This is the current industry standard. Documentation frameworks like Docusaurus, Fumadocs, and Starlight, and even general-purpose frameworks like Next.js and Astro, allow teams to build sites that are:

Fast: Pre-rendered static HTML.

Flexible: Fully customizable React frontends.

AI-Ready: Flat files are the easiest dataset for LLMs and coding agents to consume.

In this model, Git is the single source of truth. Documentation lives alongside the code. A developer can update a feature and the documentation in the same Pull Request to ensure they never drift apart.

The hidden cost: Collaboration friction While engineers prefer this setup, it alienates everyone else.

The maintenance burden: When a Product Manager or Technical Writer wants to fix a typo, they must clone a repo, run npm install, and navigate a complex directory structure. 1.

Fear of conflicts: Non-technical contributors often fear breaking the build or causing merge conflicts. 1.

Asset management: Adding an image usually involves manually placing a file in a /public folder and writing the correct relative path in Markdown.

The result is that developers become the bottleneck. They spend valuable time acting as "copy-paste janitors" for the rest of the team, applying edits sent via Slack or Google Docs.

4. Bridging the gap: The Markdown CMS

The solution is not to return to a database CMS. It is to layer a better interface over your existing Git workflow.

This is the philosophy behind Dhub: it empowers non-technical writers to contribute directly without forcing engineers to abandon their preferred tools. It functions as a Markdown CMS that respects your repository as the single source of truth.

Unify your team’s workflow. The biggest friction in documentation is the tool divide. Writers need a visual editor, while developers prefer to work in VS Code. Dhub bridges this with a seamless two-way GitHub sync.

For writers: A Notion-like editing experience. They can write content, manage tables, and embed images without ever touching a command line.

For developers: The repository stays standard. You can refactor components or reorganize structure in your code editor, and Dhub syncs those changes automatically.

Flexible Git integration. You do not need to simplify your review process just to accommodate a CMS. Dhub integrates directly with your existing GitHub flow.

Pull Requests: Writers can submit changes as a Pull Request directly from the editor. This allows engineers to review content updates alongside code changes in GitHub.

Direct Push: For quick fixes or internal documentation, you can configure Dhub to commit directly to the working branch for instant updates.

No lock-in, just Markdown Because Dhub acts as a layer on top of your repo, you never lose ownership of your content. If you stop using Dhub, you are left with clean Markdown/MDX files in your own repository—not a proprietary database export.

Summary: Choosing where complexity lives

The migration away from traditional CMSs is about choosing where the complexity lives.

Headless CMS: Complexity lives in the API and data synchronization.

Hosted Platform: Complexity is hidden, but you lose control.

Static MDX (The Standard): Complexity lives in the file system, where developers can manage it.

The goal is to maintain engineering control without sacrificing the writing experience. By pairing a static site generator with a Markdown CMS like Dhub, teams can close the gap between ideal architecture and real-world workflows.