Migrating Oso’s Docs to Mintlify
Our documentation is where developers learn how Oso works. This month, we rebuilt it from the ground up, migrating from a custom Nextra/React setup to Mintlify, a hosted docs platform built for speed, collaboration, and reliability.
Why We Moved Platforms
Our old site had served us well, but it was showing its age. Nextra’s React dependencies were no longer actively maintained, which made it difficult to update or patch quickly when security advisories were released. By mid 2025, the project had a single maintainer and uncertain long-term support. As a company that builds security software, we wanted our documentation platform to meet the same standards: stable, monitored, and easy to keep current.
Beyond infrastructure, we needed to improve the content experience. The navigation had grown messy as the product evolved, making it difficult for both new and returning users to find what they needed. Pages were overly verbose, burying key information.
Our goals were clear:
- Stabilize on a secure, maintained platform.
- Reorganize the information architecture for discoverability.
- Refactor page content for clarity and scannability.
Choosing Mintlify
We evaluated Docusaurus, Fern, and Mintlify. Docusaurus offered flexibility and control but would require us to self-host and maintain CI/CD infrastructure. Fern’s API-first approach was powerful but unnecessary for our broader documentation needs.
Mintlify struck the right balance. It gave us:
- Built-in features like AI search, dark mode, redirects, and analytics
- A visual and multiplayer editor for faster iteration
- Strong design identity
- Native support for Mermaid.js diagrams and first-party analytics
- Enterprise reliability with SOC 2 certification and active development.
It also integrated directly with our Git workflows, letting us keep our docs “as code” while improving authoring and collaboration.
Workback Plan
The planned scope of the work was below:
Phase I: Platform & IA
- Evaluate platforms
- Inventory every URL; map current → future location
- Draft new top-level information architecture and left-nav
Phase II: Content Refactor & QA
- Cut repetition; front-load examples; tighten headings
- Add redirects; fix anchors; run broken-link checks
- Stand up preview deployments; review with engineers
Phase III: Cutover
- Smoke test: search, API reference, redirects.
- Monitor 404s and search queries; patch; add content fixes as needed.
Implementation
We started with a full audit of our information architecture, mapping every existing page to its future location. This became our “current → future” migration matrix.
From there, we followed a structured evaluation flow used internally for platform changes:
Feasibility → Implementation Complexity → Operational Impact → Business Case → Compliance.
This framework ensured the migration solved the right problems without introducing new risks.
Feasibility
We validated that a hosted documentation platform could meet our requirements for version control, markdown-based authoring, and CI/CD integration. Mintlify’s GitHub integration based workflow fit into our existing workflow, and supported our custom components (MDX shortcodes, callouts, and code tab groups) through its React-based system. The platform’s support for llms.txt, custom redirects, and metadata configuration matched our SEO and analytics setup, ensuring a drop-in replacement.
Implementation Complexity
We estimated the migration as a four-week effort involving two developer experience engineers. The work included reorganizing the information architecture, migrating 200+ pages, and testing redirects. Because Mintlify runs entirely from a GitHub repo, no new infrastructure or build pipelines were required.
Operational Impact
We confirmed that we could migrate with zero downtime. Mintlify’s preview deployments allowed us to test every redirect and content update before launch, and its broken link checker caught regressions automatically. We chose to serve docs from the same URL - osohq.com/docs - to preserve DomainRank. The site was already hosted on Vercel, so we updated the DOCS_URL environment variable in the same project to point to Mintlify. Vercel’s “instant rollback” feature gave us confidence that we could revert quickly if needed.
Business Case
Moving to Mintlify replaced a custom Nextra setup that required frequent dependency updates and manual security patching. We eliminated recurring DevOps overhead while gaining faster load times, built-in SEO optimization, and easier collaboration for non-engineers.
Compliance
We verified that Mintlify met Oso’s compliance and data-protection requirements, including SOC 2 Type II certification, encryption at rest and in transit, and configurable access controls for contributors.
Once we validated the framework, we began the content refactor: rewriting nearly every page for clarity and consistency using our style guide.
Mintlify’s live preview and built-in broken link checker streamlined QA, while preview deployments let developer experience engineers review structural changes before merging. The result was a clean launch with zero downtime and automatic redirects for legacy URLs.
The Result
Now the docs reflect the product’s shape instead of the repo’s history. Engineers can author, preview, and deploy changes in minutes. Users can now search across the entire knowledge base, view diagrams inline, and explore examples without losing context.
Most importantly, the new information architecture makes it easier for anyone — from first-time users to longtime customers — to find what they’re looking for.
You can see the new docs live at osohq.com/docs. We love feedback! Let us know what you think and if you have any content suggestions, send them our way on Slack.
Frequently asked questions
