Migrate documentation into Nibleaf

Treat an import as a conversion, not proof of parity. Keep the source available, import into a disposable project or branch, account for every warning, and move traffic only after a crawl and rollback rehearsal.

Choose the source

For a Mintlify import, enter owner/repository and an optional branch. Nibleaf prefers docs.json, resolves repository-local .json $ref files, reads languages, versions, products, tabs, menu items, groups, group roots, and pages relative to that file, imports linked internal pages omitted from navigation, and preserves existing target settings when they are already populated. Mintlify languages become Nibleaf languages, and Mintlify versions become Nibleaf documentation versions backed by branches. A single import creates at most 500 navigation nodes, including groups and pages; sources above that boundary must be split and their totals reconciled before cutover.

Nibleaf does not read a private Mintlify Cloud editor URL. If the workspace is not backed by a public GitHub repository, export or publish its source to a disposable public repository first, remove secrets and private content, and use that repository for the migration rehearsal.

For Ghost, open Settings → Labs → Import/Export in Ghost Admin and export the site content and settings as JSON. Upload that JSON and provide the publication origin, such as https://docs.example.com, so Nibleaf can resolve both __GHOST_URL__ and ordinary /content/images/... paths before copying reachable images into project storage. Nibleaf imports published public posts and pages; it skips drafts, scheduled posts, and member, paid, or tier-restricted content so protected articles cannot become public documentation. Export routes.yaml and redirects separately and recreate them in Settings → Redirects after checking each destination. Member accounts, newsletters, email delivery settings, and theme code are outside the content importer.

Establish a baseline

Before import, record:

• source revision or export timestamp;
• page and asset counts;
• navigation hierarchy and redirects;
• published and draft counts separately;
• custom domains, canonical rules, indexing, and language relationships;
• representative Markdown, MDX components, tables, diagrams, and downloads;
• search queries that must return a particular page.

Export or back up the source and choose an owner for the cutover and rollback.

Import and inspect warnings

Run the import into a new project or isolated branch. Read the summary and resolve every skipped page, asset, duplicated slug, and unsupported setting. Nibleaf may retain a source URL when an asset cannot be copied; that is not a durable migration if the source will be removed.

Search the imported source for old hostnames, /docs prefixes, source-specific component tags, embedded credentials, and absolute asset URLs.

Verify parity

Use this order:

1. Compare page count and hierarchy.
2. Preview one page for every content pattern.
3. Compare language and version partitions, menu/product navigation, and Ghost post/page separation.
4. Crawl internal links, images, downloads, redirects, and missing paths.
5. Test the baseline search queries in every language.
6. Open Settings → Languages and resolve every missing default-language page.
7. Inspect title, description, canonical, hreflang, robots, sitemap, and structured data on the initial HTML response.
8. Verify keyboard and mobile behavior on representative pages.
9. Publish to a non-primary hostname and repeat the checks while signed out.
10. Rehearse the rollback: restore the source hostname and confirm the source remains writable before scheduling the DNS change.

Do not delete the source or change DNS until the replacement has a tested rollback copy.

Export and recover

Create a Markdown export before a large migration, before closing a workspace, and after the final source freeze. Markdown portability is separate from disaster recovery: self-hosters also need synchronized Postgres and object-storage backups.

When GitHub will remain in the workflow, complete the bidirectional Git authoring setup in a disposable repository first. Name Git or Nibleaf as the authority for each phase, use a dedicated authoring branch, and rehearse conflict resolution before allowing both browser and repository edits. See known limitations for provider and recovery boundaries.