fern.md

Migrate from Fern

Migrate a Fern site 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.

The Mintlify scraper does not currently support Fern.

Collect your source content

Create a migration branch or copy of your documentation repository.

Locate all of the following items:

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.

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:

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.
Tabs and Tab Convert properties and labels to Tabs and Tab.
Steps Convert to Steps and Step.
Accordions Convert to AccordionGroup and Accordion.
Cards and buttons Map to Mintlify 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 and update each import path.
Custom MDX components Rebuild with a React component 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.
  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:

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

Fern references