Known import gaps
Every diagnostic the importer emits, what it means, and what you must fix by hand.
The importer reports what it could not carry across. This page is that list.
The severity rule
Section titled “The severity rule”One rule decides every diagnostic’s severity, and it is worth knowing because it tells you what you can safely ignore:
Content or config you explicitly declared would never appear in the output → error. Presentation degrades to a default while the content itself is retained → warning.
An error means something would go missing. A warning means something looks different. Neither is silently dropped, and the first class cannot exit zero.
fern-conversion-error — errors
Section titled “fern-conversion-error — errors”Conversion stops. Fix these before anything else.
| Case | Meaning |
|---|---|
A docs.yml field references a path outside the Fern project |
Absolute paths, .. traversal and project-escaping symlinks are refused. No file outside the source project is read or copied. |
| Navigation that cannot be represented | The declared structure has no equivalent in Reed’s tab/group/page model. |
fern-unsupported-field — warnings
Section titled “fern-unsupported-field — warnings”Converted, with something dropped.
| Case | What happens |
|---|---|
| A referenced file does not exist in the Fern project | The field is dropped. |
styles.css resolves outside the project via a symlink |
Not copied; no customCss entry is emitted. Your custom styling is simply absent. |
An unrecognized top-level docs.yml key |
Ignored. |
An unrecognized colors key or mode |
That colour degrades to the template default. |
A tabs.<id> key other than display-name |
Ignored. |
The styles.css case deserves attention: it is classified a warning because your content
survives, but a site whose entire custom stylesheet vanished will not look like the one you
migrated from. Check for this specifically.
fern-path-disambiguated — warnings
Section titled “fern-path-disambiguated — warnings”Two things collided and the second was renamed.
| Case | What happens |
|---|---|
| Two Fern pages normalize to the same page path | The second is renamed. Any link pointing at it is now wrong. |
| Two assets share a basename | The second is copied under a different name. |
Page-path collisions are the most expensive warning in this list. The page still exists, so nothing errors — but inbound links, cross-references and any external link to the original path now resolve to the wrong page or to nothing. Grep your content for links to every disambiguated path.
Component-level gaps come later
Section titled “Component-level gaps come later”Import produces MDX; whether that MDX renders is a separate question answered by
reed check. Expect DS-* diagnostics on top of the import diagnostics, especially
DS-S03 before you set content.dialect, and DS-D08 where a Fern prop has no
representation in Reed’s component contract.
DS-D08 is a warning that means a prop you wrote is being discarded. Read every one of
them — the page renders, but not with everything you asked for. See
Diagnostics.
Accent colour derivation
Section titled “Accent colour derivation”Fern derives a family of colours from a single accent. Reed takes six explicit colour keys instead, so a Fern accent does not carry its derived ramp across — you set the six keys yourself. The result is a site that is close but not identical, and the difference is in the derived shades rather than the primary colour.
What none of this covers
Section titled “What none of this covers”The importer converts a Fern project’s structure and config. It does not review your information architecture, rewrite prose written for another platform’s components, or tell you which pages are now redundant. Those are editorial decisions, and a migration is a good moment to make them rather than carry them forward.