Sourced*

Migration

Migrate from Mintlify to Sourced: docs migration checklist

· 3 min read · Sourced

  • agents
  • mintlify
  • docs
  • openapi
  • migration

This guide is for teams moving a Mintlify docs site to Sourced. It also works as a Mintlify alternative checklist for teams comparing API docs migration tools. Mintlify is a strong docs surface. Do not frame the migration as "delete Mintlify." Frame it as: keep the useful guide content, move API reference and release workflow to OpenAPI.

As of August 31, 2026, Mintlify's public pricing includes a free Starter plan, a paid Pro plan, and Enterprise conversations. Sourced uses a different boundary: unlimited free previews and up to 2 hosted noindex docs review sites, then Launch at $99/month per API project for production docs on Sourced-controlled URLs, repo sync, registry readiness/approved publishing, and team review. Scale is $349/month and adds more API projects, more hosted docs sites, more team capacity, and production custom domains.

First inventory

Find:

  • docs.json or legacy mint.json.
  • OpenAPI source used by the API reference.
  • MDX pages, snippets, reusable components, tabs, cards, and code groups.
  • Custom domain and redirect rules.
  • Search, analytics, and AI chat settings.
  • SDK examples embedded in docs.

If the API reference is not driven by a current OpenAPI file, make that the first blocker.

Prerequisites

Before using Sourced, confirm:

  • a signed-in Sourced workspace approved by the API owner
  • canonical OpenAPI access
  • Mintlify docs repo or export access
  • package names, import paths, and auth environment variables
  • redirect map and docs domain owner
  • local Node 20+, pnpm 10+, and Python 3.10+ for proof checks

The upload path is /dashboard/projects once the API owner confirms the OpenAPI file is safe to upload.

Hard part: MDX components are not the contract

Mintlify docs often use cards, tabs, accordions, snippets, and custom MDX components. Those components matter to presentation, but they are not the durable API contract. Preserve the endpoint semantics, auth guidance, examples, SDK install snippets, redirects, and search behavior. Rebuild the presentation only where it helps readers.

Manual path

  1. Export Mintlify navigation and MDX pages.
  2. Identify pages that are true API reference vs narrative guides.
  3. Move examples and auth details into OpenAPI where possible.
  4. Generate docs reference from OpenAPI.
  5. Convert useful MDX guides into portable Markdown.
  6. Build llms.txt, sitemap, and redirects.
  7. Generate SDK previews separately.
  8. Generate MCP server and skill file separately.

Manual migration is doable, but agents often get confused by Mintlify-only components. Preserve content intent, not component syntax.

Sourced path

Use Sourced when the team wants one workflow:

  • OpenAPI generates reference docs.
  • The docs editor can draft quickstarts, guides, recipes, and launch notes, with publishing still handled through review/approval.
  • TypeScript and Python client packages are generated from the same OpenAPI.
  • Standalone skill-file and MCP tools can turn the same OpenAPI context into agent instructions and an MCP starter.
  • Sourced-hosted noindex review URLs stay noindex until production custom-domain cutover is explicitly enabled and approved.

Agent prompt

Migrate this Mintlify API docs site to Sourced.
Inventory docs.json or mint.json, MDX pages, OpenAPI source, custom domain, redirects, analytics, search, SDK examples, and AI docs surfaces.
Confirm Sourced workspace access, docs repo/export access, package names/import paths/auth env vars, redirect map, DNS owner approval, and local Node/pnpm/Python proof tools.
Keep narrative guides editable. Move API reference to OpenAPI-generated docs.
Generate or request Sourced previews for docs, SDK packages, and llms.txt; use separate Sourced skill-file and MCP tools if needed.
Do not change DNS, publish packages, or upload private API material until the owner approves that exact action.

Watch for confusion

Agents commonly mistake Mintlify cards and tabs for product semantics. They are presentation. The durable semantics are endpoint docs, auth instructions, examples, SDK snippets, and redirect URLs.

If content is mostly product docs or marketing pages, keep those pages in a general docs CMS. If content is mostly API reference, SDK examples, and launch checks, Sourced is the better home.

Compare Mintlify pricing, read the Mintlify alternative page, or start free and upgrade only when publishing or production docs go live.