Migrate from Mintlify

There are two ways to bring a Mintlify project into DocsLit, depending on how clean a break you want.

Drop in: no conversion needed

DocsLit recognises Mintlify-style PascalCase tags directly in your Markdown. <Tip>, <Card>, <Steps>, <CardGroup>, and friends are rewritten to wc-* at build time, so most projects just work.

What's recognised

Every Mintlify component below works without any changes to your .md files:

Font Awesome icon names on <Card icon="..."> and similar are mapped to built-in Lucide icons where a match exists.

Convention fallback

Any other PascalCase tag is rewritten by convention to wc-kebab-case. So <MyCustomThing> becomes <wc-my-custom-thing>. If you don't have a matching built-in or custom component, docslit validate will warn you so you can register it before shipping.

What isn't supported

DocsLit converts tag syntax, not full MDX semantics:

• JSX expressions — {props.foo}, {frontmatter.title}, {<Inline />} aren't evaluated. Strip them out, or use editable variables for runtime values.
• import / export statements — not executed. Remove them from the top of your files.
• JavaScript-valued attributes — <Card cols={2 + 1}> works (numeric literal); <Card cols={someVar}> doesn't.

If your files lean heavily on these features, run the deep import below for an automated pass that strips them.

Deep import

For projects with lots of frontmatter quirks, JSX expressions, or other Mintlify-isms, the import command runs a thorough pass: rewrites every component, strips imports/exports, normalises frontmatter, and copies assets.

This creates a -docslit/ directory with your converted documentation.

What import does on top of the bridge

• Rewrites tags eagerly — every component is converted in your source files instead of at build time, so the result is canonical wc-* Markdown you can read and edit directly.
• Strips MDX imports and exports — removes import and export statements from the top of every page.
• Strips JSX expressions — removes {...} interpolations that have no Markdown equivalent.
• Normalises frontmatter — renames Mintlify-only keys (e.g., sidebarTitle → sidebar_title) and drops fields DocsLit doesn't use (openapi, mode, noindex, deprecated).
• Generates the sidebar — translates navigation from mint.json/docs.json into docslit.json's sidebar.
• Handles versioned docs — detects navigation.versions and offers four migration strategies (branch-per-version, latest-only, merge-all, or skip).
• Copies assets — images, screenshots, and other files referenced from pages.

Custom output directory

After import

Which path should I pick?