Migrate from Fern

Migrate a Fern site from its Git repository. Fern stores documentation as Markdown or MDX alongside docs.yml, assets, and API specifications, so the source repository is more complete and reliable than the published HTML.

​

Collect your source content

Create a migration branch or copy of your documentation repository. Locate all of the following items:

• fern/docs.yml, which defines site settings and navigation
• MDX pages, commonly in fern/docs/pages/
• Image, video, favicon, and logo assets, commonly in fern/docs/assets/
• Reusable MDX snippets, commonly in fern/docs/snippets/
• Changelog entries in fern/docs/changelog/
• fern/styles.css and any other custom CSS or JavaScript
• fern/fern.config.json and the pinned Fern CLI version
• OpenAPI, AsyncAPI, and Fern definition files
• generators.yml and scripts that retrieve or generate API specifications
• Product, version, and tab configuration files referenced by docs.yml
• Custom MDX components
• Any environment variables, remote specifications, generated files, or private packages required when you run fern check or fern docs dev

​

Recreate navigation

Fern defines navigation in docs.yml or in separate files for products and versions. Mintlify defines navigation in docs.json. Fern constructs routes from the slugs of sections, folders, tabs, versions, products, and pages. Do not infer the old URL from the source filename alone. Export the published sitemap and resolve slug, skip-slug, and page-level path overrides before creating redirects. When a Fern folder uses index.mdx as its overview, use that page as the Mintlify group’s root. Preserve deliberate navigation order rather than relying on Fern’s alphabetical folder discovery.

​

Convert pages and frontmatter

Most standard Markdown and MDX can move directly. Every Mintlify page needs a title. Retain descriptions, keywords, and other useful SEO metadata. Review Fern-specific frontmatter such as:

• slug and path overrides
• availability badges
• Page layout and table-of-contents settings
• Visibility and indexing controls
• API reference associations

Recreate behavior with Mintlify frontmatter, navigation, or content. Add a callout for availability states that do not have an equivalent presentation.

​

Convert components

Fern and Mintlify both use MDX components, but component names and properties are not interchangeable. Search every page for JSX tags and imports instead of assuming they render unchanged. Remove Fern-only imports after conversion. Preview pages that use nested components because valid syntax and supported properties can differ even when both platforms use the same component name.

​

Migrate API references

Use your API specification to create your new API reference pages.

1. Trace each api navigation entry to its OpenAPI, AsyncAPI, or Fern definition source.
2. Download specifications that the build retrieves from a URL or another repository.
3. Preserve overlays, generated examples, authentication configuration, and custom endpoint prose.
4. Add the source specification to the Mintlify repository and configure API reference pages.
5. Compare endpoint grouping, servers, security schemes, examples, and SDK snippets with the Fern site.

Fern definitions can contain information that is not represented directly in an OpenAPI document. Review the generated OpenAPI output and move any missing descriptions or examples before retiring your Fern build.

​

Migrate products and versions

Fern can place navigation in product-specific or version-specific YAML files. Inventory every referenced file and map each maintained product and version to the corresponding Mintlify navigation structure. Check for:

• A landing page outside the product navigation
• Products or versions with different page trees
• Slugs added by product, version, or tab levels
• Version-specific API specifications
• Hidden, deprecated, or pre-release sections
• External products that link to another site

​

Migrate assets and site settings

Copy files from the configured asset directories and update relative paths after moving pages. Do not leave required production assets on your former deployment unless you plan to keep that hosting after your migration. Review docs.yml for logos, favicons, social images, fonts, colors, navbar links, announcement banners, redirects, analytics, custom CSS, and custom JavaScript. Recreate supported settings in docs.json. Treat CSS and JavaScript as requirements to evaluate, not files to copy blindly, because their selectors and runtime assumptions are platform-specific.

​

Review your migration

Compare every docs.yml navigation entry and discovered folder page against docs.json, then validate every product, version, and tab. Search your converted files for leftover Fern syntax: component imports, unsupported JSX properties, and Versions or If blocks.

​

Launch your new site

• Set a content freeze on your former site and track every change made to it after your migration snapshot.
• Confirm your production branch and repository on the Git settings page of your dashboard.
• Record your existing DNS records and keep your former site running until you verify your Mintlify deployment is live.
• Review the navbar, footer, favicon, logo, colors, and typography.
• Review site and page metadata, canonical URLs, and indexing preferences. See SEO and search settings.
• Install any required analytics integrations, and optionally add a custom 404 page.
• If you migrated an API reference, compare endpoint pages, navigation structure, server URLs, authentication schemes, and examples with your former site.
• Preview your exact launch commit in a preview deployment. Check desktop and mobile layouts, pages from every navigation section, search, and your redirects.
• Check the browser console and network tab for any errors on pages that use custom components or scripts.
• Switch your domain with the custom domain guide, which covers the zero-downtime cutover for a domain that already serves documentation.
• After launch, monitor for 404 errors, redirect failures, and build failures.

​

Fern references

• Project structure
• Navigation
• Products
• Versions
• Components
• Custom CSS and JavaScript
• CLI commands