How we migrated docs from Docusaurus to Mintlify
It started with a missing feature. I was trying to add cwd support to our MCP implementation when I realized, this isn't documented anywhere. As I dug deeper into PR #6280, I discovered more gaps. Before I knew it, I was staring at our entire documentation structure, wondering if we needed more than just a few updates.
Docusaurus had served us well. It's been the reliable workhorse of the open source world, and honestly, it still is. But in this new era of AI-powered development, I kept hitting walls. Our CTO was reviewing our docs one day and casually mentioned, "Have you tried Mintlify?"
That question changed everything.
The Features We Didn't Have Time to Build
Here's what sold me: Mintlify ships with AI capabilities that would've taken our small team months to implement:
AI Assistant: Not just search, but an actual assistant that understands context. Users can ask "How do I configure context providers?" and get real answers from our docs.
Copy Page for LLMs: This one's genius. A button that formats the entire page for LLM consumption. Perfect for when you're context engineering and need clean documentation input.
MCP Server Conversion: Your docs literally become an MCP server. The same protocol we were documenting could now serve our documentation. Meta? Yes. Useful? Absolutely.
You can read about our new MCP in the docs, of course.
The AI-powered search alone cut our support burden in half. But the real game-changer was how these features work together; creating a documentation experience that actively helps developers build.
The Migration Playbook (That Actually Worked)
First rule of documentation migrations: write a plan. Just like in my offline context engineering post, you need to map your current state before moving anything.
I started with Mintlify's scrape CLI, but quickly realized I needed more control. With hundreds of pages to migrate, I wrote custom scripts to handle the heavy lifting. Each script moved content locally, letting me verify changes before pushing. Could I have used an MCP server for this? Probably. But sometimes the old ways work just fine.
The redirect strategy saved us from SEO disaster:
// content-mapping.md
# Content Mapping: Docusaurus to Mintlify
## Overview
This document maps the current Docusaurus content structure to the new Mintlify 4-tab organization while preserving all existing URLs.
## Tab 1: User Guide
**Purpose**: Getting started, core features, and practical guides
### Mapped Content:
- **Introduction** → `/index` (homepage)
- **Getting Started**
- `/getting-started/overview`
- `/getting-started/install`
- **Features**
- `/features/overview`
- `/features/chat/*` (quick-start, how-it-works)
- `/features/autocomplete/*` (quick-start, how-it-works)
- `/features/edit/*` (quick-start, how-it-works)
- `/features/agent/*` (quick-start, how-it-works)
//...truncated for the blog post
prompt: "Create a markdown file that list all routes and potential redirects for this migration"
see the full file from my pull request: CONTENT_MAPPING.md
The actual migration followed a simple pattern which started with generating breaking down the migration into steps, like migrate all code block files, while updating to the updated Mintlify syntax:
# script to fix all code blocks
#!/bin/bash
# Fix code blocks for better Mintlify syntax highlighting
# This script adds language specifications to code blocks where appropriate
echo "🔍 Analyzing code blocks..."
# Count current code blocks
echo "📊 Current code block stats:"
echo "Total code blocks: $(find . -name "*.mdx" -exec grep -c "^\`\`\`" {} + | awk '{sum+=$1} END {print sum}')"
...
# Show updated stats
echo "📊 Updated code block stats:"
echo "Total code blocks: $(find . -name "*.mdx" -exec grep -c "^\`\`\`" {} +|prompt: "search through /docs folder and apply mintlify required language identifier"
see the full file from my pull request: fix-codeblocks.sh
Having everything local meant I could grep for patterns, test transformations, and catch edge cases before they became production issues.
Pro tip: Mintlify requires opening and closing HTML tags on the same line. Learn from my debugging sessions.
What We're Betting On
We literally just shipped this. The PR merged, the docs are live, and I'm writing this post while the deployment is still warm. So instead of made-up metrics, here's what we're excited about:
Instant Answers: The AI assistant should handle those repetitive setup questions that flood our Discord. Every "how do I configure X" that gets answered by AI is time we get back for building.
Developer Experience: The feedback features means no more context switching when trying to get feedback to the team. If things are out of date or need extra context, developers can send us a quick 👍or 👎. Having this information in a clean Analytics dashboard will do wonders for prioritizing future docs content updates.
Contribution Barriers: With the web editor, our DevRel team and community can fix typos and add examples without wrestling with Git. More contributors means better docs.
What I'm most curious about? How developers will use the "Copy for LLMs" feature. We're all context engineering these days, and having clean, LLM-ready documentation feels like a superpower we didn't know we needed.
Open Source Means Sharing the Journey
Our docs are open source, just like Continue itself. Every page has an "Edit this page" button that takes you straight to GitHub. Want to fix a typo? Add an example? Improve an explanation? Just click and PR.
What's beautiful about Mintlify is how it preserves this workflow. Contributors can still submit PRs through GitHub, and we can watch them roll in. But now they also have the option to use Mintlify's web editor for quick fixes. It's not about replacing the Git workflow, it's adding options for different types of contributors.
The migration scripts? They're public. The patterns we discovered? Documented. The gotchas we hit? All in the gist. Because that's what open source is about—not just sharing code, but sharing the entire journey.
Your Documentation Deserves Better
If you're maintaining docs that feel stuck in 2015, ask yourself: could AI make this better? Not AI for AI's sake, but AI that genuinely helps developers succeed.
Start small. Pick one section. Run the migration scripts. See if your community responds like ours did. And when you discover that one undocumented feature that sends you down the rabbit hole, maybe that's your sign it's time for something new.
The future of documentation isn't just about storing information. It's about creating intelligent systems that help developers build amazing things. And with tools like Mintlify, that future is surprisingly accessible.
I could not have done this migration without the help my team review this with me. If you want to review it yourself, check out PR#6500.
Check out the new experience at docs.continue.dev and let us know what you think!