Tangly v0.2 ships richer code blocks, page chrome, and more — see what's new

Migrate from Mintlify

Move an existing Mintlify project to Tangly without editing source files.

~ 1 min read

Migrate from Mintlify

Tangly renders Mintlify projects unmodified. Migration is mostly swapping the CLI and pointing $schema at Tangly’s schema.

Install Tangly
bash
```
bun add -D tangly
```
Run migrate
bash
```
bun x tangly migrate
```
What it does:
- If you have docs.json (Mintlify modern): validates against Tangly’s schema, updates $schema to Tangly’s URL, surfaces a notice if theme isn’t a Tangly theme. The theme field itself is not auto-rewritten — pick one yourself before running tangly dev.
- If you have mint.json (Mintlify legacy): full conversion to docs.json. Source is renamed to mint.json.bak. Use --keep-source to keep the original.
- If you have both: prefers docs.json and leaves mint.json alone.
No MDX files are touched in either case.

Replace dev/build commands

In package.json, swap Mintlify’s CLI for Tangly’s:

json

{
  "scripts": {
    "dev": "tangly dev",
    "build": "tangly build"
  }
}

Run dev
bash
```
bun run dev
```
Open http://localhost:4321. Walk every page side-by-side with mintlify dev (different port) to spot any rendering gaps.

Side-by-side compare

If you want to confirm parity before committing:

bash

# Terminal 1
mintlify dev --port 3050

# Terminal 2
tangly dev --port 4321

Browse both at the same time.

What’s compatible

Flags

--root <dir> string path default: .

Project root.

--yes boolean path

Skip confirmation prompts.

--keep-source boolean path

When migrating from mint.json, retain the original instead of renaming it to mint.json.bak.