---
title: Migrate to Thally
description: Move your existing docs to Thally with one command, then run them locally.
url: https://docs.thally.io/guides/migrating
---

# Migrate to Thally

Move your existing docs to Thally with one command, then run them locally.

One command imports an existing documentation site into a new Thally project. Pick the guide for the platform you use today, or start with the generic version below.

You need Node.js 22 or later and Git. Prefer a source GitHub repository when available; it preserves authored content and configuration. Migration validation executes imported MDX and components locally, so use sources you own or trust.

## Migrate and run locally

```bash
npx --yes @thallylabs/cli@latest migrate https://github.com/example/product --platform auto --yes
```

```bash
cd product-docs
npm run dev
```

Open the URL printed by the dev server, normally [http://localhost:3040](http://localhost:3040), to review your docs.

The command clones the repository, detects the platform, converts the pages, installs dependencies, runs the checks and a production build, and makes an initial Git commit. Add an output directory after the URL to change the default `<repo>-docs` name.

Read `migration-report.json` before publishing. Installation or validation failures retain the imported files; fix reported failures and rerun `npx --yes @thallylabs/cli@latest check` and `npm run build`. With `--skip-validation`, install dependencies and run both checks yourself.

## Choose your platform

#### [Mintlify](/guides/migrate-from-mintlify)

    Dedicated adapter for `docs.json` or `mint.json` projects.

#### [Docusaurus](/guides/migrate-from-docusaurus)

    Dedicated adapter for repositories and live sites.

#### [Fern](/guides/migrate-from-fern)

    Dedicated adapter for Fern navigation and OpenAPI sources.

Mintlify, Docusaurus, and Fern have dedicated adapters. Other Markdown and MDX sources use detected configuration or folder-based navigation. Fern imports navigation-referenced pages; review the report for skipped or access-restricted content.

For a live source, pass its public URL. Review the imported hierarchy and assets: deployed output may expose less than a repository. `--yes` or `--platform auto` accepts these limitations without pausing.

## Options

| Flag | Description |
|------|-------------|
| `--platform <name>` | `mintlify`, `docusaurus`, `fern`, or `auto`. Without it, an interactive CLI asks; non-interactive shells use auto-detection. |
| `--yes`, `-y` | Skip all prompts |
| `--branch <name>` | Override the detected branch |
| `--docs-dir <path>` | Override the detected docs folder. A `tree/<branch>/<dir>` URL sets both. |
| `--max-pages <count>` | Cap a live-site crawl at 1 to 1,000 pages |
| `--into <dir>` | Merge into an existing Thally project instead of creating one |
| `--api-key <key>` | Anthropic API key for converting non-Markdown files such as `.rst` |
| `--skip-validation` | Import only; skip install, checks, and build |

Repository auto-detection recognizes:

| Configuration | Platform |
| --- | --- |
| `mint.json` or Mintlify `docs.json` | Mintlify |
| `docs.yml` and `fern.config.json` together | Fern |
| Thally `docs.json` with `tabs` | Thally |
| `docusaurus.config.*` | Docusaurus |
| `SUMMARY.md` | GitBook |
| `.vitepress/` | VitePress |
| `astro.config.*` | Starlight |
| `_meta.json` | Nextra |
| No recognized configuration | Markdown |

## Publish

Commit your edits, push the project to a new GitHub repository, and connect it in [Thally Cloud](https://app.thally.io) with **Create site** and then **Connect an existing repository**:

```bash
git add -A
git commit -m "docs: review migrated content"
git branch -M main
gh repo create product-docs --private --source=. --remote=origin --push
```

Choose the generated repository and its production branch, normally `main`. Leave **Docs directory** empty for a project at the repository root, or enter its relative directory in a monorepo. Review the source summary and select **Publish site**.

Set `repoUrl` in `src/data/site.ts` to the new repository so edit links work. To host it yourself, see [Deploy your documentation site](/guides/deploying).

## Use an agent instead

With the [Thally MCP server](/guides/mcp-server) connected, ask your coding agent to run `migrate_docs` with the source URL and a new target directory. Or paste this prompt into any agent with shell access:

Migrate SOURCE_URL into a new Thally project at TARGET_DIRECTORY. You are done when the source has been imported into a fresh Thally project, important navigation and assets survive the move, validation and the production build pass, and I have an evidence-backed review of anything that still needs human work.

Before writing files, read repository instructions in the current workspace and inspect TARGET_DIRECTORY. Stop if the target exists and is not empty. Prefer the source GitHub repository when it is available because it preserves authored MDX, configuration, redirects, and assets. Confirm ambiguous sources or destinations with me rather than substituting one.

Use the local Thally MCP migrate_docs tool if connected; otherwise run npx --yes @thallylabs/cli@latest migrate SOURCE_URL TARGET_DIRECTORY. Never use import_docs or --into unless I explicitly request an in-place merge. Preserve the importer output and warnings.

After migration, read migration-report.json, then compare source and destination page counts, top-level navigation, redirects, assets, code languages, custom components, and API references. Start the local site and inspect the homepage, every primary navigation tab, representative shallow and deep pages, links, code blocks, images, tables, callouts, and any API reference in light and dark mode plus a narrow viewport.

Fix safe mechanical issues that do not change product meaning. Flag unsupported components, ambiguous navigation, and claims that need a product owner instead of inventing replacements. After your edits, run npx --yes @thallylabs/cli@latest check and npm run build again. Report exact commands, files changed, checks, warnings, and next actions. Do not overwrite a non-empty directory, delete source content, deploy, commit, push, or change public URLs without asking.

## Troubleshooting

- **Pages are missing.** For a repository, pass `--docs-dir` or a `tree/<branch>/<dir>` URL. For a live site, raise `--max-pages` and rerun into an empty directory.
- **The build failed.** Open `migration-report.json` and the build output. The usual causes are imports of packages Thally does not ship, template syntax MDX cannot parse, and components with no Thally equivalent. Fix the page, then run `npx --yes @thallylabs/cli@latest check` and `npm run build`.
- **Thally Cloud cannot see the repository.** Grant the Thally GitHub App access to it from the source step, then reload the repository list.
- **The repository is rejected as incompatible.** Commit every generated file, including `package-lock.json`, `wrangler.jsonc`, and `open-next.config.ts`.