> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate from Fern

> Migrate a Fern to Mintlify. Convert MDX content, docs.yml navigation, products, versions, assets, API references, and components.

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.

<Note>
  The Mintlify scraper does not currently support Fern.
</Note>

## 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`

<Note>
  Fern reserves the `fern` and `changelog` folder names. Every other folder name is configurable, so confirm your directory names against `docs.yml` before you move files.
</Note>

## Recreate navigation

Fern defines navigation in `docs.yml` or in separate files for products and versions. Mintlify defines navigation in `docs.json`.

| Fern                | Mintlify                                                        |
| ------------------- | --------------------------------------------------------------- |
| `page` with `path`  | Page path in a `pages` array                                    |
| `section`           | Navigation group                                                |
| Section with `path` | Group with a `root` page                                        |
| `folder`            | Navigation group with its pages listed explicitly               |
| `link`              | Navigation link, anchor, menu item, or card                     |
| `tabs`              | Tabs in `docs.json`                                             |
| `products`          | Products in `docs.json`                                         |
| Site-wide versions  | Versions in `docs.json`                                         |
| `hidden: true`      | `hidden: true` in page frontmatter or a hidden navigation entry |

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.

| Fern content                                     | Mintlify treatment                                                                                                            |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| Callouts                                         | Convert to [`Note`, `Tip`, `Info`, `Warning`, or `Danger`](/docs/components/callouts).                                             |
| `Tabs` and `Tab`                                 | Convert properties and labels to [`Tabs` and `Tab`](/docs/components/tabs).                                                        |
| Steps                                            | Convert to [`Steps` and `Step`](/docs/components/steps).                                                                           |
| Accordions                                       | Convert to [`AccordionGroup` and `Accordion`](/docs/components/accordions).                                                        |
| Cards and buttons                                | Map to [Mintlify cards](/docs/components/cards) and supported links.                                                               |
| `Versions` blocks                                | Use tabs or separate versioned pages, depending on whether the selection should affect one block or the site.                 |
| `If` blocks                                      | Split content by product or version, or use a supported custom component when conditional rendering is essential.             |
| API schema and endpoint snippet components       | Generate the reference from the original API specification and move supplemental prose into guides or operation descriptions. |
| Reusable MDX snippets from `fern/docs/snippets/` | Convert to [Mintlify snippets](/docs/create/reusable-snippets) and update each import path.                                        |
| Custom MDX components                            | Rebuild with a [React component](/docs/customize/react-components) or replace with a built-in component.                           |

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](/docs/api-playground/openapi-setup).
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](/docs/organize/navigation).

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](https://app.mintlify.com/settings/deployment/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](/docs/organize/settings-seo).
* Install any required [analytics integrations](/docs/integrations/analytics/overview), and optionally add a [custom 404 page](/docs/customize/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](/docs/deploy/preview-deployments). 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](/docs/customize/custom-domain), 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](https://buildwithfern.com/learn/docs/getting-started/project-structure)
* [Navigation](https://buildwithfern.com/learn/docs/configuration/navigation)
* [Products](https://buildwithfern.com/learn/docs/configuration/products)
* [Versions](https://buildwithfern.com/learn/docs/configuration/versions)
* [Components](https://buildwithfern.com/learn/docs/writing-content/components/overview)
* [Custom CSS and JavaScript](https://buildwithfern.com/learn/docs/customization/custom-css-js)
* [CLI commands](https://buildwithfern.com/learn/cli-api-reference/cli-reference/commands)


## Related topics

- [Migration overview](/docs/migration/index.md)
- [Migrate from Docusaurus](/docs/migration/docusaurus.md)
- [Migrate from Document360](/docs/migration/document360.md)