WritedocsWritedocs

Migrating from Mintlify

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page
Connect to CursorUse these docs in CursorConnect to VS CodeUse these docs in VS Code

Most Mintlify pages build in writedocs with no changes: the components, props, code-block syntax, and frontmatter below are accepted under Mintlify’s own names. Copy your MDX files over, then check the known differences.

Converting docs.json

In your Mintlify project’s folder, run:

writedocs convert --mintlify

It writes writedocs.json from docs.json and lists everything that couldn’t be carried over as-is, then checks your pages - see writedocs convert. Pass --dry-run first to review the result without writing anything.

What it converts:

docs.jsonwritedocs.json
name, descriptionSame fields.
colors.primary, colors.lightstyles.colors.primary, styles.colors.dark.primary.
logo, favicon, fonts, background, styling.codeblocksThe matching styles fields.
navigation - pages, groups, tabs, dropdowns, products, versions, languagesThe same structure. A group’s root becomes its page.
navigation anchorsTabs.
A tab’s or product’s menuDropdowns inside it.
navigation.global anchors, tabs and dropdownsGlobal dropdowns - or topbar links, when the navigation is a plain list of pages.
Groups with an openapi specOpenAPI groups. A group that listed individual endpoints now shows every endpoint in its spec.
navbar.links, navbar.primaryTopbar links.
footer.socials, footer.linkssocials, footer.columns.
banner, errors.404, redirects, variablesbanner, notFound, redirects, variables.
seo.metatags (og:image, og:type, twitter:card, keywords)seo.
contextual.optionscontextMenu.
integrations - GA4, Google Tag Manager, Plausible, Fathom, PostHogintegrations.
api.playground.proxyapi.proxy.

Everything else is listed in the report, with the field it came from. Hidden tabs and groups are left out of the navigation - their pages still build, reachable by URL. After converting, set domain in writedocs.json to your site’s address: Mintlify sets it in its dashboard, not docs.json.

CLI commands

Mintlifywritedocs
mint devwritedocs dev
mint broken-linkswritedocs broken-links - also checks #anchors.
mint openapi-checkwritedocs validate - checks every spec in the navigation, and every page’s openapi operation, with the rest of the project.
mint a11ywritedocs a11y

Components

MintlifyIn writedocs
Note, Info, Tip, Warning, Danger, CheckSame names. See Callout.
Callout with icon / colorSame props.
Card with icon, img, href, color, horizontal, cta, arrowSame props. See Card.
Columns, Column, CardGroupSame names.
Tabs / Tab with defaultTabIndex, iconSame props. See Tabs.
CodeGroupSame name. Tab labels come from each block’s title.
Accordion / AccordionGroup with icon, description, defaultOpenSame props. See Accordion.
Steps / Step with icon, stepNumber, titleSizeSame props. See Steps.
Frame with caption, hintSame props. See Frame.
Tooltip with tip, headline, cta, hrefSame props. Also available as Hint. See Hint.
ParamField (path / query / body / header), ResponseFieldSame props, including deprecated, pre, post. See Parameter.
Expandable, RequestExample, ResponseExample, Badge, IconSame names.
UpdateSame props. See Update.
Tree / FileTree, Tree.Folder, Tree.File - component or Markdown-list formSame props and keyboard navigation. See Tree.
TileSame props. See Tile.
PanelSame behavior. See Panel.
Prompt with description, icon, actionsSame props. See Prompt.
View with title, iconSame props, and the table of contents follows the selected view. See View.
Color, Color.Row, Color.ItemSame props, including light/dark values. See Color.
GitHub.RepoSame props. See GitHub repository.
VisibilitySame behavior on the site and in the page’s Markdown version. See Visibility.
className on any componentSame - added to the component’s outermost element.
CodeBlockSame props. See Code blocks.
Snippets imported from /snippets/...Same path. See Snippets.
React hooks without imports, components defined in a pageWork as on Mintlify, interactive. See Snippets.
openapi: "/spec.json GET /path" page frontmatterSame form - the page shows that operation. See OpenAPI.

Icons

A bare icon name is looked up in Lucide first, then Font Awesome Solid, then Font Awesome Brands. Mintlify’s default library is Font Awesome, so names like gear, circle-info, or discord work as-is. See Icons.

Code blocks

Mintlify’s code-block options work as written: an inline title (```bash Install), title="...", highlight={1,3-5}, focus={2}, icon="...", lines, wrap, expandable, and nocopy. See Code blocks.

Frontmatter

title, description, and openapi mean the same thing, and a page without a title gets one from its file name, as on Mintlify. A page doesn’t need frontmatter at all if the navigation lists it. These Mintlify fields are also accepted:

  • sidebarTitle, icon, tag, and deprecated - how the page appears in the sidebar.
  • hidden - leaves the page out of navigation but keeps its URL working, and noindexes it.
  • url - makes the sidebar entry an external link, and redirects the page’s URL there.
  • hideFooterPagination and hideApiMarker - hide the previous/next links, or the sidebar’s HTTP method badge.
  • noindex, keywords, og:image, og:type, twitter:card - the same as writedocs’ seo fields.

See Frontmatter for each one.

  • mode: wide and mode: custom - the same modes. mode: center renders as writedocs’ frame mode (no sidebar, no table of contents). mode: assistant renders as a normal page.

Tailwind classes

Tailwind utility classes in your MDX are generated as they are on Mintlify, and dark: follows the site’s light/dark toggle. Mintlify’s light/dark image pair works unchanged:

<img className="block dark:hidden" src="/images/light.png" />
<img className="hidden dark:block" src="/images/dark.png" />

Known differences

Run writedocs validate first#

After copying your pages over, run writedocs validate. It lists everything that needs attention in one pass, with file and line - pages that would fail the build, and components or icons writedocs doesn’t have. Then run writedocs broken-links to find links that don’t lead anywhere.

  • Components writedocs doesn’t have - every component in Mintlify’s documentation is available. Anything else, like a custom React component from your Mintlify project, doesn’t fail the build: it shows only the content inside it, with a warning naming the file and line. Move it into a snippet, or remove it.

  • mode: frame - Mintlify’s frame is a blank canvas that keeps the sidebar. writedocs’ frame has no sidebar and keeps the page’s title and normal layout. The page builds, but looks different - a custom landing page with its own hero shows writedocs’ title above it.

  • Components inside a page’s own React component - in a page component that uses React hooks or is passed to a snippet, Card, Callout and the other writedocs components render just their content, Icon renders nothing, and CodeBlock renders unhighlighted. writedocs validate lists each one. A component passed to a snippet as a prop renders, but isn’t interactive.

  • Font Awesome Pro and iconType - only the free Font Awesome Solid and Brands sets are installed. iconType is ignored, so the icon renders from whichever set has the name (Lucide first), and a Pro-only icon name is left out, with a warning.

  • Frontmatter with no equivalent - searchable, boost, related, contextual, groups, timestamp, lastUpdatedDate, and SEO keys other than the five above (for example "twitter:image") are ignored for now.

  • Update and RSS - writedocs doesn’t generate an RSS feed from Update entries, so their rss prop does nothing. The tag filters appear above the first entry, not in a side panel.

  • Panel outside the default mode - on Mintlify, a page mode without a table of contents also hides its Panel. In writedocs, the Panel stays in the page instead.

  • Variables - {{name}} works for names made of letters, digits and underscores. A name with a hyphen isn’t valid in MDX - write it as [[name]].

  • Relative links - writedocs page URLs end in a slash (/docs/guides/setup/), so a relative link resolves one level deeper than on Mintlify: [Install](install) on that page points to /docs/guides/setup/install/. Write links from the site root instead (/docs/guides/install/). writedocs broken-links finds each one and says what to write.

  • Redirects with a pattern - Mintlify’s /old/:slug and /old/* redirects aren’t supported; writedocs redirects match one exact path. convert leaves them out and says how many.

  • noindex and on-site search - on Mintlify, noindex (and hidden) also removes the page from the site’s own search. In writedocs, the page still shows up in on-site search.