Migrate from Fern

Move Fern documentation to ReadMe by selecting the right import path and deciding what happens to SDK generation before cutover. Fern already gives you an interactive, OpenAPI-generated reference — moving to ReadMe means running your Guides and API Reference on one platform, with content review through Branches and Reviews and usage data tied to individual developers in My Developers.

Choose the easiest migration path

Your situation	Recommended path
You want to evaluate public documentation quickly	Use the Importer.
Your Fern documentation is ready in a repository	Prepare the supported repository structure and use Git-based import.
You need scripted or CI-based uploads	Convert a copy of the repository and upload it with `rdme@10`.
You have a small content set	Create and review pages in the ReadMe editor.
You have SDKs, generated documentation, custom components, or complex governance needs	Ask about Enterprise migration assistance.

Use bi-directional Git Sync after migration for ongoing two-way editing. It requires a new, empty GitHub or GitLab repository and does not import an existing Fern repository.

Decide what happens to SDKs

Fern can generate SDKs, snippets, and documentation from generators.yml and docs.yml. ReadMe creates interactive API Reference content from OpenAPI definitions but does not generate client SDKs.

Before moving content, decide whether you will keep Fern for SDK generation, use another SDK generator, or stop publishing generated SDKs. Include generated MDX and SDK snippets in your migration inventory.

What doesn't transfer, and what replaces it

What doesn't transfer	Rebuild it with
SDK generation and `generators.yml`	Keep Fern for SDKs, switch generators, or retire generated SDKs — ReadMe does not generate client SDKs
Theming, custom CSS, and navigation styling from `docs.yml`	Themes and Appearance settings
Custom components you wrote yourself	Custom MDX components

Inventory and convert content

Copy the repository and keep the original unchanged.
Review docs.yml for navigation, API definitions, pages, and site configuration.
Review generators.yml for SDK generation, generated content, and publishing workflows.
Inventory MDX pages, assets, snippets, custom components, CSS, and header or footer code.
Export or create the OpenAPI definition you will upload to ReadMe.

Map title, descriptions, images, indexing settings, slugs, and navigation metadata to ReadMe equivalents. Convert standard MDX components only after checking the supported ReadMe syntax and props. Rebuild custom components where appropriate, and rewrite content that depends on Fern-specific rendering or generated output.

For CLI uploads, each new Guide requires title and category.uri; use position and parent.uri to recreate navigation from docs.yml. For Git-based import, prepare the documented folder structure and _order.yaml files.

Upload and review

Validate and upload your OpenAPI definition, then preview the Guide upload:

npx rdme@10 openapi validate ./openapi.yaml
npx rdme@10 openapi upload ./openapi.yaml --key="$README_API_KEY"
npx rdme@10 docs upload ./docs --key="$README_API_KEY" --dry-run

Resolve errors before publishing the Guides upload. Uploading OpenAPI creates API Reference content from the operations in the definition. Configure authentication before testing Try It!, and integrate the Metrics SDK separately when you need API-log data in the Developer Dashboard.

Set up redirects and cut over

Build redirects from the published Fern URLs, navigation, and traffic data. Under Admin Settings > Error Pages, enter redirects as oldurl -> newurl, one per line. Verify the ReadMe navigation, components, assets, generated API Reference, SDK publishing path, and high-traffic redirects before changing your domain.

Keep Fern available while you verify the migration and complete cutover.

Optional: continue in Git

After migration, connect a new empty repository through Settings > Git Connection to enable bi-directional Git Sync. Use Git Sync folders and _order.yaml files to manage navigation, and align repository branches with ReadMe versions.

After you migrate

Run a Docs Audit to check content quality, build guided walkthroughs with Recipes, and use My Developers to see how developers use your API once your Metrics integration is live.

Frequently asked questions

Can we use Fern for SDKs and ReadMe for docs?

Yes. Keep Fern's generator configuration and publishing workflow for SDKs, and upload the OpenAPI definition to ReadMe for API Reference content.

Does ReadMe support AsyncAPI?

Yes, ReadMe supports AsyncAPI alongside OpenAPI, Swagger, and Postman collections.

Should we remove hand-written endpoint pages?

Compare each page with the generated API Reference first. Keep explanations, workflows, and examples that the OpenAPI definition does not contain as Guides.