Migrating from Mintlify
Same filename, different schema
Mintlify and Reed both use docs.json, but their schemas differ. A Mintlify config must be translated before Reed can validate it. This page lists the field-level differences.
Reed has no Mintlify importer
Reed currently imports Fern only; there is no --from mintlify command. The tables below describe schema differences, not the result of an automated or completed customer migration.
The mapping
Mintlify docs.json → Reed docs.json
| Mintlify docs.json | Reed docs.json | What changes |
|---|---|---|
| name | name | Same key. Reed constrains it to 1–100 characters. |
| theme: "mint" | template: "mint" | "rapide" | "black" | Different key, different value set. Reed has three templates; the key theme does not exist. |
| colors.{primary,light,dark} | colors | Reed requires exactly six keys — accent-primary, background, border, sidebar-background, header-background, card-background — each a {light,dark} pair of 6-digit hex. Five keys is an error; seven is an error. |
| logo | logo | Either {light, dark} or {text}. Declaring both is a schema error. |
| navigation.groups[].{group,pages[]} | navigation.tabs[].groups[].pages[] | Reed always has a tab level above groups. Pages nest at most five deep, and a page id carries no .mdx extension. |
| api.{openapi,playground,examples,params,mdx} | api.specs + a page {api: true, spec} | Reed registers specs by name and renders each through one API reference page, which must be the only page of its group and the only group of its tab. |
| fonts | typography.{headings,body,code} | Family names only. Reed takes no font file paths. |
| redirects | redirects[].{source,destination,permanent?} | Real 301/302 responses. Two entries with the same source is a schema error, not a last-one-wins. |
| seo | seo.* plus site and base | site is your absolute origin and is never inferred; base is the subpath the site is mounted at. |
| integrations | analytics.{provider,options} | A closed registry — ga4, plausible, posthog, fathom, umami, matomo. You give a provider name, never script text. |
| Custom CSS and JS | customCss | CSS only. Reed runs no tenant JavaScript, and has no head.script or raw head injection; head.link’s rel values are an allowlist. |
| navigation.versions / languages / dropdowns | versions, products, languages | Accepted by the schema and currently not implemented. They will not render anything yet. |
| any other key | — nothing | Reed’s schema is Zod .strict(). A leftover Mintlify-only key is a hard error, not a silent no-op. |
The strict schema is the reason a Mintlify docs.json cannot be renamed into place. Strict validation rejects unsupported configuration keys before the build starts.
One field, one error code
ParamField path is interpreted differently
For Mintlify content, Reed maps <ParamField path="limit"> to a parameter named limit with location path. The attribute name supplies the location and its value supplies the parameter name. Fern’s identical-looking tag uses the attribute’s value as the parameter’s name and implies no location. Reed’s own ParamField requires name, so under the default "reed" dialect your pages fail a real reed check run with:
Set "content": {"dialect": "mintlify"} so Reed applies its Mintlify ParamField mapping. This resolves the missing-name validation error shown above. Valid values are exactly "reed", "fern" and "mintlify"; a typo such as "mint" (the template name) is rejected by the schema rather than ignored.
Failing loudly
The checker runs the validation the build runs
reed check runs schema and static-content validation without building the site or accessing the network. It reports documented DS-* diagnostics for failures including missing navigation targets, unknown top-level keys, and unsupported components.
Translate docs.json on a branch
Your MDX files can stay at their existing paths, but unsupported components may require edits. Translate docs.json manually, set content.dialect to mintlify, and run reed check.