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.
Collect your source content
Section titled “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.cssand any other custom CSS or JavaScriptfern/fern.config.jsonand the pinned Fern CLI version- OpenAPI, AsyncAPI, and Fern definition files
generators.ymland 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 checkorfern docs dev
Recreate navigation
Section titled “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
Section titled “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:
slugand path overridesavailabilitybadges- 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
Section titled “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
Section titled “Migrate API references”Use your API specification to create your new API reference pages.
- Trace each
apinavigation entry to its OpenAPI, AsyncAPI, or Fern definition source. - Download specifications that the build retrieves from a URL or another repository.
- Preserve overlays, generated examples, authentication configuration, and custom endpoint prose.
- Add the source specification to the Mintlify repository and configure API reference pages.
- 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
Section titled “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
Section titled “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
Section titled “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
Section titled “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 site 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.