Skip to content



Should I build my website in markdown?

Should you build your website in Markdown/MDX or stick with a headless CMS like Sanity? We've shipped both - here's an honest look at the trade-offs, the hidden costs, and which approach actually f…

Frequently asked questions

What is MDX and how does it differ from traditional CMS?
MDX is markdown with the ability to embed React components inside of it, allowing you to build dynamic page builder blocks directly in your content files. Unlike traditional headless CMS platforms like Sanity that use drag-and-drop builders or form-based editors, MDX lets you create rich, interactive pages while storing everything in GitHub, giving you a more developer-centric approach to content management.
Should every team build their website with markdown and MDX?
Honestly, no. About 99% of teams don't understand the trade-offs involved, and most won't have the capacity to edit and maintain it long-term. However, if your team is willing to invest three to six months training everyone on AI tools, MCPs, and AI-driven workflows, it could be worth it. It really depends on whether you have skilled developers and whether your team embraces AI-augmented development as a core workflow.
What are the main challenges with building in markdown?
The biggest challenges are managing media assets (images shouldn't be stored directly in GitHub), needing to build or integrate a custom asset management solution, requiring team members to work through AI prompts rather than visual editors, and losing the ability to make quick manual edits like you would in a traditional CMS. You're essentially trading ease-of-use for performance and AI-readiness.
How does content creation differ between markdown and Sanity?
With Sanity, you use a visual interface to click, drag, and manually edit content like you would in Word. With markdown, you're primarily working through AI chat prompts to generate and modify pages. This is a fundamental paradigm shift that requires your entire team to think differently about content creation and to become comfortable working conversationally with AI systems.
Why would Cursor choose markdown over a traditional CMS?
Cursor's team chose markdown because they're highly skilled developers who use AI agents constantly and understand the trade-offs. They get a stripped-down, optimized system that performs exceptionally well and is ready for agentic interactions, similar to how a kit car might out-accelerate a Tesla in a straight line. For a team like theirs, the benefits outweigh the complexity costs.
What is an AI harness and why does it matter?
An AI harness is your personalized setup for how you use AI to generate content—it's your opinions, preferences, and workflows built into the way you prompt and interact with AI systems. It's extremely important because raw AI outputs need significant customization to match your brand voice and content style, and without a thoughtful harness, you'll spend a lot of time refining what AI generates.
Can you use AI agents with traditional CMS like Sanity?
Absolutely. Sanity offers MCPs (Model Context Protocols) that let you work with AI agents while keeping your content in a robust, user-friendly CMS. This gives you the benefits of AI-augmented workflows without forcing non-technical team members to work entirely through prompts, making it a practical middle ground for most teams exploring agentic workflows.
What's the main advantage of markdown websites for AI and performance?
Markdown-based sites are what we call agentic-ready—they're optimized for being crawled, indexed, and understood by AI systems and LLMs. They also tend to perform better technically. The trade-off is that you lose the safety rails and integrated tools of a full-featured CMS like Sanity, which functions more like a modern Tesla with all its built-in protections and conveniences.


Continue watching

Get in touch

Tell us what you're building. We reply within one working day — Jono or someone on the team picks up every message personally.