---
title: Migrating from Fern
description: What the importer converts, and the order to work through afterwards.
---

```sh
reed import --from fern --source ../my-fern-project
```

Reads a Fern project's `docs.yml` and content, and writes a `docs.json` plus a `content/`
tree. Fern is currently the only supported source.

## Treat it as a first pass

The importer converts structure and config. It does not finish the job on a project of any
size — expect to work through diagnostics afterwards. Plan for it as a task, not as a
command.

The work is bounded and mechanical, and the importer tells you what it is: every
conversion emits diagnostics, and the severity distinction is the useful part.

<Steps>
  <Step title="Run the import">
    Nothing is read or copied from outside the source project directory.
  </Step>
  <Step title="Read every error">
    An error means content you declared would not appear in the output. Nothing is
    silently lost.
  </Step>
  <Step title="Set content.dialect">
    Imported MDX is Fern's dialect. This is the single highest-value fix.
  </Step>
  <Step title="Run reed check and work down the list">
    Unconditionally offline and needs no setup, so the loop is fast.
  </Step>
</Steps>

## Set `content.dialect` first

```json
{ "content": { "dialect": "fern" } }
```

Leave it at the default `"reed"` and a Fern-authored project produces a wave of `DS-S03`
diagnostics about missing required props — because Fern's `<ParamField path="limit">` uses
`path` as the parameter's *name*, and Reed's canonical form expects `name`.

Setting the dialect fixes the whole class at once. Rewriting the fields by hand fixes the
same class much more slowly and loses information. See
[Content dialect](/docs/authoring/dialect).

## What converts

- `docs.yml` navigation, including tab-less `section`/`contents` and multi-API projects
- Multiple API specs, each becoming its own tab
- Colors, logo, navbar links
- MDX content, copied and referenced by page id
- `styles.css`, emitted as a `customCss` entry

## What to check by hand afterwards

Structure surviving the import is not the same as the site being right. Look at
navigation depth, at any page whose path was disambiguated, and at every asset that shares
a basename with another.

[Known gaps](/docs/migrate/fern-gaps) lists what the importer reports and what it drops,
with the severity of each.

## Nothing outside the project is read

A `docs.yml` field pointing outside the source directory — an absolute path, a `..`
traversal, or a symlink leaving the project — is refused with an error. No file outside
the imported project is read or copied.