How to migrate from Mintlify to ThallyHow to migrate from Mintlify to Thally

Your Mintlify repository contains MDX, so moving the docs looks like a file copy. Then the preview opens with a missing snippet, a different navigation tree, or an old link that no longer redirects. The pages arrived, but the documentation workflow is not ready to switch.

To migrate from Mintlify to Thally, import a preserved source into a new project, inspect the conversion report, and validate the destination before changing public URLs. This guide follows that path with a pinned CLI and small local examples. It is for the engineer or documentation owner responsible for the move. We build Thally. Our checks below are limited migration exercises, not a customer migration or a production cutover.

1. Preserve the source and choose a starting point

Record the Mintlify repository, deployment branch, documentation directory, and source commit. Keep an untouched copy while you work in a separate destination. Use the Mintlify export guide to collect pages, configuration, assets, snippets, and API descriptions.

If Mintlify hosts the source, its Git Settings flow can clone it into your organization. Read that flow carefully. Mintlify warns that completing manual repository setup permanently deletes the Mintlify-hosted content. Verify the backup first.

Prefer a source repository or an authorized local checkout. A live URL import is a fallback when you cannot obtain source. It captures published material and can expose less than the authoring project. It is a snapshot, not an ongoing synchronization. The URL migration overview explains those boundaries.

Before importing, list anything that must survive outside the page files: access rules, versions, languages, custom components, API specifications, search behavior, analytics, and integrations. A repository does not reveal every dashboard setting. In particular, do not assume a copied page retains its original access restrictions.

2. Import into a new local project

You need Node.js 22 or later and Git, according to the current migration prerequisites. The commands here were exercised on Node.js 24.1.0 with @thallylabs/cli 0.8.129 on October 29, 2026. The generated projects used Next.js 16.4.1. Pinning the CLI identifies our test, but its downloaded scaffold and dependencies can change, so retain the generated lockfile and starter-release.json too.

Migration validation executes imported MDX and components locally. Use a source you own or trust. Choose a destination that does not exist yet. From the directory that will hold the new project, run:

npx --yes @thallylabs/cli@0.8.129 migrate ./mintlify-source thally-docs --platform mintlify --yes

Replace ./mintlify-source with your local documentation checkout. Use the docs subdirectory when the project is in a monorepo. The CLI reference also supports a GitHub repository URL, a tree/<branch>/<dir> URL, and explicit --branch or --docs-dir overrides. Confirm the selected branch and directory rather than relying on detection.

The normal new-project flow converts content, installs dependencies, runs content checks and a production build, and initializes Git. It writes migration-report.json in the destination. --yes accepts prompts. It does not approve a public launch. Avoid --into for this trial because that option merges into an existing project.

If you intentionally use --skip-validation, the result is an import awaiting validation. Install dependencies and run the content check and build yourself before treating it as a working destination.

3. Read the report and compare the output

Open thally-docs/migration-report.json. Check page and asset totals, warnings, conflicts, quarantined material, and validation results. A passed build means the generated project builds. It does not prove that every source page, audience, or integration survived.

Review the Mintlify adapter guide alongside the generated files:

Source material	Destination review
docs.json or older mint.json navigation	Compare tabs, groups, nesting, order, versions and languages in the new docs.json, then open them in the preview
Authored MDX and reusable snippets	Compare rendered text, links, code languages and snippet content, including pages outside the main navigation
Built-in components	Check callouts, tabs, cards, fields and code groups visually. Matching component names alone do not establish matching behavior
Custom JSX or TSX	Inspect migrated files under src/mdx/migrated/, imports and package requirements. Resolve missing dependencies or replace the component without changing its meaning
Images and downloads	Open local assets and verify authorized remote dependencies. A successful page render can still hide a missing download
OpenAPI descriptions and API pages	Check operation paths, methods, schemas, examples, authentication instructions and version scope. A build does not exercise the live API
Branding and service settings	Review src/data/site.ts, docs.json, dashboard configuration and each integration separately

For missing pages, check the source directory and navigation scope before rerunning into another empty destination. For an unresolved snippet, recover its source and compare the complete included content. For a custom component that fails the build, inspect the import and required package. Do not suppress the error by deleting the explanation the reader needs.

Access settings need a separate decision. The importer warns that Mintlify dashboard access controls are not visible in the repository. Configure the intended destination restrictions and test allowed and denied readers before any deployment containing private content. Review versions and languages individually rather than treating one working quickstart as acceptance of the whole site.

What our small migration checks established

We ran the pinned command against the official Mintlify starter and a separate synthetic local fixture. Both imports completed content validation and a production build. The starter run imported 2 pages and 3 assets. Its report warned that unsupported page-menu options were dropped and that dashboard access settings require review.

The synthetic fixture contained two pages, a reusable snippet, a marker image, an internal link, <Check> and <Tile> components, and a redirect without an explicit permanence value. We inspected the generated configuration and content, then checked the served output. The fixture is available with this article's source and receipts.

These exercises cover a small repository import. They do not establish custom-package compatibility, private-reader enforcement, a live API request, a URL crawl, or production hosting and DNS behavior. Record those as separate acceptance cases when they apply to your site.

4. Check old URLs and redirect semantics

Start with a map of current paths to destination paths. Preserve URLs where practical, and keep historical redirects as well as newly renamed pages. Test a deep link and an anchor from outside the site, not only links reached through the new sidebar.

Defaults matter. Mintlify redirects are permanent by default. Thally's redirect configuration defaults to temporary unless permanent is set. In our synthetic import, the source /start redirect became an explicit permanent: true entry targeting /quickstart. Inspect that value in your generated project and verify the HTTP response on the intended host. Do not infer behavior from the configuration file alone.

Mintlify says its redirect sources cannot include anchors or query parameters. Preserve important heading IDs or provide a clear replacement at the destination. Avoid sending every removed page to the homepage, which can leave the original question unanswered. Review temporary versus permanent routing with the people responsible for the launch and rollback.

5. Preview, repair, and rerun validation

From the generated project, run the content check and production build after your edits:

cd thally-docs
npx --yes @thallylabs/cli@0.8.129 check
npm run build
npm run dev

Open the local address printed by the dev server, normally on port 3040. Stop the preview with Ctrl+C when finished. Do not skip a failed check because the homepage looks right.

Compare source and destination for a quickstart, a deeply nested page, every primary navigation section, a component-heavy page, an API page, and each supported version or language. At desktop and narrow mobile widths, read code blocks and tables, switch tabs, follow cards, inspect images and downloads, and use the keyboard. Check old paths, anchors, page titles, canonical URLs and search results.

For our fixture, the served-page check confirmed the reusable sentence, code example, marker image and internal link. The old /start path returned a permanent redirect to /quickstart. Those are fixture observations, not evidence about your site's routes.

Also verify the machine-readable outputs your readers use. Search, Markdown exports, llms.txt and MCP access need the intended content, version and audience. Our agent-readable documentation guide explains the different surfaces. Test private content with an unauthorized reader too, where applicable.

6. Plan publication and rollback as separate work

Keep Mintlify serving the existing site while you review the destination. Choose managed or self-hosted deployment using the Thally deployment guide. For managed hosting, the documented repository connection leads to publication, so finish the content and access review before selecting Publish site. Check the generated repository's edit links and configure repoUrl in src/data/site.ts for the destination repository.

Before changing the custom domain, record the current DNS values, destination values, responsible owner, approval point and rollback conditions. Follow the host's account-specific instructions. Thally's managed hosting guide says to add the hostname in Settings → Domains, apply the records it provides, and wait for verified status. Keep the managed address available while the domain is pending.

After an authorized cutover, check the certificate, old paths and redirects, navigation, representative content, access restrictions and machine-readable outputs at the real hostname. Allow for DNS caching when interpreting what readers see. If acceptance fails, use the prepared routing rollback and verify that the old site is reachable again. Keep the source and original hosting available until the migration owner accepts the result.

Restoring a previous Thally deployment is a different action from routing the domain back to Mintlify. The managed hosting guide documents deployment rollback and its publishing pause. Record which recovery action your team intends, rather than assuming one fixes every failure.

Use the documentation migration checklist to assign these decisions. If you are still choosing a platform, the Mintlify alternatives comparison belongs before this procedure. When the source and acceptance cases are ready, create a Thally workspace to evaluate managed hosting, or continue locally with the open-source project.

Sources and verification

Reviewed October 29, 2026 against the official Thally migration, CLI, redirects, deployment and managed-hosting guides, and Mintlify's repository and redirect documentation linked above. Local checks used CLI 0.8.129 on Node.js 24.1.0. The fixture source and daily report retain the scope and results. Cutover and rollback instructions are a planning procedure. No account connection, deployment, DNS change, paid service or customer migration was executed for this article. Read the editorial policy for sourcing and correction standards.