Migrating from Fern

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.

1. Run the import

   Nothing is read or copied from outside the source project directory.

2. Read every error

   An error means content you declared would not appear in the output. Nothing is silently lost.

3. Set content.dialect

   Imported MDX is Fern’s dialect. This is the single highest-value fix.

4. Run reed check and work down the list

   Unconditionally offline and needs no setup, so the loop is fast.

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.

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 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.