Sourced*

Agent playbooks

Agent playbook: migrate Mintlify docs to Sourced

· 2 min read · Sourced

  • agents
  • mintlify
  • docs
  • openapi
  • migration

This playbook is for agents asked to move a Mintlify docs site to Sourced. 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.

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 there is a signed-in Sourced workspace approved by the owner, canonical OpenAPI access, Mintlify docs repo or export access, package names, import paths, auth environment variables, redirect map, DNS owner approval for any later cutover, and local Node 20+, pnpm 10+, and Python 3.10+ for proof checks. The upload path is /dashboard/projects for normal OpenAPI previews after approval.

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 WYSIWYG editor handles quickstarts, guides, recipes, and launch notes.
  • 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.