Migrating from Fern
How supported docs.yml fields map to docs.json
Reed ships an importer for Fern specifically. It reads fern/docs.yml, writes docs.json, copies pages and assets, and warns on unsupported top-level fields. Below is that result, field by field.
The mapping
docs.yml → docs.json, field by field
| Your fern/docs.yml | Reed docs.json | What the importer does |
|---|---|---|
| title | name | Carried over unchanged. |
| — (Fern has themes, not templates) | template | The importer sets template to "mint". |
| colors.accent-primary.{light,dark} | colors.accent-primary | Carried over when the value is a 6-digit hex. So are colors.background and colors.border. |
| — (no Fern equivalent) | colors.sidebar-background, header-background, card-background | Reed requires exactly six colour keys. The three Fern doesn’t have are filled from the mint defaults. |
| logo.{light,dark,text} | logo | Carried over. In Reed, {text} and {light,dark} are mutually exclusive — declaring both is a schema error. |
| favicon | favicon | Copied only if the path resolves inside your project directory. A symlink pointing outside is reported, not followed. |
| navigation: - page: / - section: | navigation.tabs[].groups[].pages[] | Restructured. Reed always has a tab level, so a bare page at layout level gets wrapped in a group named after it. |
| tabs.<id>.display-name | the tab’s label | Carried over; the tab id itself is used if no display-name is set. |
| navigation: - api: "API Reference" | api.specs + a page {label, api: true, spec} | Each API becomes its own tab. Reed requires an API reference page to be the only page of its group and the only group of its tab. |
| navbar-links[].{type,text,href} | navbar-links[].{style,label,url} | Renamed one-to-one. Reed’s styles are minimal | filled | outlined. |
| styles.css | customCss: ["styles.css"] | Copied under that fixed name. Reed accepts CSS from tenants — never JavaScript. |
| — (implied by the dialect you wrote in) | content.dialect: "fern" | Written for you by the importer. Read the next section before you delete it. |
Fern column reads a fern/docs.yml; Reed column reads a docs.json at your repository root.
Not carried over
What the importer will not carry over
Reed’s Fern parser knows seven top-level keys: title, tabs, navigation, colors, logo, favicon, navbar-links. Anything else in your docs.yml comes back as a warning, one line per field:
That covers footer-links, layout, typography, redirects, metadata, analytics, instances, versions, products, and Fern’s custom React header/footer. Each unsupported top-level field produces a warning during import. Reed does not execute tenant JavaScript or accept React components; its supported MDX catalog contains 37 component names.
One field, one error code
The one field that decides whether your MDX compiles
<ParamField path="limit"> is valid in Fern and valid in Mintlify, and the path attribute means a different thing in each. In Fern, the attribute’s value is the parameter’s name and no location is implied. In Mintlify, the attribute name supplies the location and its value supplies the parameter name, so the same tag is a parameter named limit with location path. Reed’s own ParamField requires name, so with the dialect left at its "reed" default, a page carried over from Fern fails a real reed check run with:
"content": {"dialect": "fern"} switches the prop mapping so Fern’s path is read as the parameter name, and the same page passes. reed import --from fern writes that line into your docs.json for you. Valid values are exactly "reed", "fern" and "mintlify"; a typo such as "mint" is rejected by the schema rather than ignored.
Evidence
Repository test fixture and build counts
examples/fern-import-trackly is a converted Fern project retained as a test fixture. The test suite asserts 314 Management API operation pages, 12 Ingestion API operation pages, and 39 tag-derived sidebar groups. It also asserts the navbar link target, the #0e7490 accent, and the text logo rendered with no image file. The built site is available at retidal.com/docs.
Live at retidal.com/docs.
Ownership
Fern became a Postman company on 8 January 2026
Reed writes static build output into your project, which you can host independently.
What the importer does not do
The importer translates supported configuration fields and reports unsupported ones. It does not rewrite prose, redesign navigation, or create a redirect strategy.
Run the import on a branch
Then run reed check locally before changing the live site.