@mintlify/cli 4.0.1763 → 4.0.1765

package/migrate/sources/docus.md

@@ -0,0 +1,136 @@
+# Docus
+
+Nuxt layer for docs built on Nuxt Content (MDC Markdown in `content/`) and Nuxt UI (prose components). Generic Nuxt Content handling (`_payload.json`, `routeRules`, `/_ipx/` images): `mint migrate --from nuxt`. This guide covers the Docus repo layout and the Nuxt UI component syntax.
+
+## Detect
+
+- `docus` in `package.json` dependencies; `nuxt.config.ts` with `extends: ['docus']`, or scripts running `nuxt dev --extends docus` with no config file.
+- `content/` with numeric-prefixed names (`1.getting-started/2.installation.md`) and `.navigation.yml` files.
+- `@nuxt-themes/docus` instead means the old Docus (Nuxt Content 2, `_dir.yml`, different components). Its syntax is not covered here: follow `mint migrate --from nuxt`, flag every unmapped component and report.
+- A `docus` dependency wins over the generic Nuxt signals.
+
+## Get the source
+
+### From the repo
+
+Reference: https://docus.dev/en/getting-started/project-structure
+
+- Root is the folder whose `package.json` depends on `docus` (often `docs/` in a monorepo).
+- Pages: `content/**/*.md`. `content/index.md` is the landing page.
+- `content/docs/` present: documentation lives there and is served under `/docs/...`; other files beside it are separate site pages: ask the user whether to migrate them.
+- i18n: one folder per locale code (`content/en/`, `content/fr/`), each with its own `index.md`.
+- Read `app.config.ts` (or `app/app.config.ts`), `nuxt.config.ts`, `content.config.ts` if present (extra collections such as a blog or changelog: see `mint migrate --topic changelog`), and `app/components/content/*.vue` (custom MDC components).
+- `app/pages/*.vue` are Vue routes, not content: list them and report.
+
+### From an export
+
+None; the site is built from the repo.
+
+### From the live site
+
+`_payload.json` extraction: (`mint migrate --from nuxt`, From the live site).
+
+## Config → docs.json
+
+Reference: https://docus.dev/en/concepts/configuration
+
+| Docus                                                                                                                                                                                            | docs.json                                                                            |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| `seo.title`, else `site.name` in `nuxt.config.ts`, else `package.json` `name`                                                                                                                    | `name`                                                                               |
+| `seo.description`, else `package.json` `description`                                                                                                                                             | `description`                                                                        |
+| `header.logo.light` / `header.logo.dark`                                                                                                                                                         | `logo.light` / `logo.dark` (by key; Docus file names are often inverted)             |
+| `header.logo.display: 'wordmark'`                                                                                                                                                                | `logo` from `header.logo.wordmark.light` / `.dark`                                   |
+| `header.logo.favicon`, else `public/favicon.ico`                                                                                                                                                 | `favicon`                                                                            |
+| `ui.colors.primary` (Tailwind color name; unset means the Nuxt UI default)                                                                                                                       | `colors.primary`: read `--ui-primary` from the live site's CSS and resolve it to hex |
+| `docus.colorMode: 'light'` / `'dark'`                                                                                                                                                            | `appearance.default` + `appearance.strict: true`                                     |
+| `socials` (Simple Icons key → URL, shown in the footer)                                                                                                                                          | `footer.socials` for keys Mintlify supports; others: drop and report                 |
+| `github.url` (or the git remote when `github` is unset)                                                                                                                                          | `navbar.links` entry with `type: "github"`, only if the header showed it             |
+| `navigation.sub: 'header'`                                                                                                                                                                       | `navigation.tabs`, one per top-level folder                                          |
+| `navigation.sub: 'aside'`                                                                                                                                                                        | `navigation.anchors`, one per top-level folder                                       |
+| `nuxt.config.ts` `i18n.locales`, `defaultLocale`                                                                                                                                                 | `navigation.languages`, `default: true` on the default                               |
+| `nuxt.config.ts` `routeRules` redirects                                                                                                                                                          | `redirects` (see `mint migrate --from nuxt`)                                         |
+| `github.branch` / `rootDir` (edit and issue links), `toc.title`, `toc.bottom`, `search`, `seo.titleTemplate`, `seo.schema`, `docus.locale`, `docus.shortcuts`, other `ui.*`, `app/app.css` theme | drop and report                                                                      |
+| `assistant`, `mcp`, `llms` settings                                                                                                                                                              | drop and report                                                                      |
+
+## Navigation
+
+References: https://content.nuxt.com/docs/collections/types#ordering-files, https://content.nuxt.com/docs/utils/query-collection-navigation
+
+- The sidebar is the `content/` tree (or `content/docs/`, or `content/<locale>/`). Each folder → a group; files and subfolders → its pages and nested groups.
+- Order: siblings sort alphabetically by their full prefixed name, so `10.faq` comes before `2.setup` unless padded (`02.`). Reproduce that exact order; confirm against the live sidebar.
+- Group label and icon: the folder's `.navigation.yml` `title`, and `icon` (top-level or under `navigation:`). No `.navigation.yml`: copy the label the live sidebar shows.
+- Folder `index.md` → first page of its group.
+- Page frontmatter `navigation: false`: not in the sidebar (`mint migrate --topic navigation`, Structure rules). `navigation.title` → `sidebarTitle`; `navigation.icon` → `icon`.
+- Icons are Iconify names (`mint migrate --topic conversion`, Icons).
+- With `navigation.sub` set, each top-level folder becomes a tab or anchor holding that folder's groups.
+
+## Content conversion
+
+Syntax references: https://content.nuxt.com/docs/files/markdown, https://ui.nuxt.com/docs/typography
+
+MDC structure:
+
+- Block: `::name{key="value" flag}` ... `::`. Nested blocks add a colon (`:::tabs-item` inside `::tabs`), and each closer has its opener's colon count.
+- Props: inline `{...}`, or a YAML block between `---` lines right after the opener. `:prop='json'` binds a value. Props are data: never emit them as text.
+- Slots: `#name` lines inside a block (`#title`, `#description`, `#default`, `#code`).
+- Inline: `:name{props}`. Spans `[text]{.class #id style="..."}` → `text`. Attributes on inline code (`` `x`{lang="ts"} ``) → `` `x` ``.
+
+`::note`, `::tip`, `::warning`: `mint migrate --topic conversion`, Admonitions.
+
+| Docus / Nuxt UI                                                   | Mintlify                                                                                              |
+| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `::caution`                                                       | `<Danger>`                                                                                            |
+| `::callout{color="info"}` / `"warning"` / `"error"` / `"success"` | `<Info>` / `<Warning>` / `<Danger>` / `<Check>`                                                       |
+| `::callout` with `neutral`, `primary`, `secondary` or no color    | `<Callout icon="...">` with a Font Awesome icon, else `<Note>`                                        |
+| callout `to` / `target`                                           | add the link to the callout text; report                                                              |
+| `::tabs` + `:::tabs-item{label icon}`                             | `<Tabs>` + `<Tab title icon>`; drop `sync`, `hash`, `defaultValue`                                    |
+| `::code-group` of `[label]` fences                                | `<CodeGroup>`, label → fence title; drop `sync`                                                       |
+| `::code-tree{default-value}`                                      | `<CodeGroup>`, each fence titled with its path; report the tree view                                  |
+| `::code-collapse` around a fence                                  | the fence with `expandable`                                                                           |
+| `::code-preview` (default slot + `#code`)                         | the rendered content, then the `#code` fence; report                                                  |
+| `::steps{level="N"}` (default level 3)                            | `<Steps>`; each heading of that level → `<Step title>`, content up to the next one as body            |
+| `::card-group`                                                    | `<Columns cols={2}>`                                                                                  |
+| `::card{title icon to target color}`                              | `<Card title icon href>`; drop `color`, `target`                                                      |
+| `::accordion` + `:::accordion-item{label icon}`                   | `<AccordionGroup>` + `<Accordion title icon>`                                                         |
+| `::collapsible{name}`                                             | `<Accordion title>` with the trigger label shown on the live site                                     |
+| `::field-group` + `::field{name type required description}`       | `<ResponseField name type required>` per field, `description` or slot as body; drop the group wrapper |
+| `::badge`                                                         | `<Badge>`                                                                                             |
+| `:icon{name}`                                                     | `<Icon icon>` (`mint migrate --topic conversion`, Icons)                                              |
+| `:kbd{value}`                                                     | `<kbd>value</kbd>`                                                                                    |
+| `:video{src autoplay controls loop}`                              | `<video src controls autoPlay loop>`                                                                  |
+| `u-page-*` and other `u-*` Nuxt UI components (landing page)      | headings, paragraphs and `<Card>`s from their props and slots; report                                 |
+| custom `app/components/content/*.vue`                             | `mint migrate --topic conversion`, Components                                                         |
+
+Code fences:
+
+| Docus                                    | Mintlify                                                             |
+| ---------------------------------------- | -------------------------------------------------------------------- |
+| ` ```ts [nuxt.config.ts] `               | ` ```ts nuxt.config.ts ` (`title="..."` if the label has spaces)     |
+| ` ```ts [file.ts] {2,4-5} `              | ` ```ts file.ts highlight={2,4-5} `                                  |
+| ` ```diff [file.ts] ` with `+`/`-` lines | the file's language; strip prefixes, add `[!code ++]` / `[!code --]` |
+
+Frontmatter (https://docus.dev/en/concepts/edition):
+
+- `title` → `title`. If missing, Nuxt Content took the first `# H1`: move it into `title`.
+- `description` renders under the title: keep it.
+- `navigation` → see Navigation. `seo.title` / `seo.description` override meta only: drop and report.
+- `layout`, `links`, `sitemap`, other keys → drop and report.
+- `content/index.md` (landing) → `mode: "custom"`; leave it out of the sidebar groups.
+
+## Assets
+
+- `public/` is served at the site root; Docus pages reference it root-absolute (`mint migrate --topic conversion`, Images and files).
+- Images under `app/assets/` or referenced from Vue components: same handling.
+- Logo and favicon paths in `app.config.ts` are `public/` paths.
+
+## URLs and redirects
+
+- Path = file path under `content/` minus extension, numeric `N.` prefixes stripped from every segment, `index` dropped: `content/1.guide/2.installation.md` → `/guide/installation`. Rename files without prefixes to keep those paths.
+- With `content/docs/`, every doc path starts with `/docs/`: keep a `docs/` folder in Mintlify.
+- i18n forces a prefix on every locale, the default included (`/en/guide/...`), and `/` redirects to the default locale. Keep `en/`, `fr/` folders. Regional codes appear lowercase in URLs (`zh-TW` → `/zh-tw/`): name the folder in lowercase. Ask the user how `/` should resolve.
+- A locale listed in `nuxt.config.ts` without a `content/<code>/` folder was never published: skip it.
+- `nuxt.config.ts` `routeRules` redirects: see `mint migrate --from nuxt`.
+
+## Known gaps
+
+Report each: Docus AI assistant, MCP server and `llms.txt` settings; Studio; `code-tree` file browser and `code-preview` live rendering; callout links and colors; card colors; Iconify icons with no Font Awesome match; landing-page `u-page-*` layout; custom Vue components and `app/pages/*.vue` routes; `navigation.sub` behavior beyond tabs or anchors; `toc.bottom` links; theme CSS and `ui.*` overrides; old Docus (`@nuxt-themes/docus`) components.

package/migrate/sources/docusaurus.md

@@ -0,0 +1,143 @@
+# Docusaurus
+
+React static site generator. Content is MD/MDX under the docs plugin's `path`; navigation is executable JS/TS (`sidebars.js`) plus `_category_.json`/`.yml` files and doc front matter.
+
+## Detect
+
+- `docusaurus.config.{js,mjs,ts}` at the site root, `@docusaurus/core` in `package.json`.
+- `sidebars.{js,ts}`, `_category_.json`/`_category_.yml` in content folders, `static/`, `versioned_docs/`, `versions.json`, `i18n/`.
+- Live site: `<meta name="generator" content="Docusaurus ...">`, `__docusaurus` in the HTML, `/assets/js/runtime~main.*.js`.
+- Config file wins over everything else. Read the `@docusaurus/core` major from `package.json`: v2 (MDX 1) and v3 (MDX 3) need different content fixes (below).
+
+## Get the source
+
+Mintlify's guide for this platform: https://www.mintlify.com/docs/migration/docusaurus.md
+
+### From the repo
+
+- Read `docusaurus.config.*` first: every `@docusaurus/plugin-content-docs` instance (preset `docs` or `plugins` with an `id`) has its own `path` (default `docs`), `routeBasePath`, `sidebarPath`, `include`/`exclude`. Each instance is a separate docs tree.
+- Also inventory `src/pages/**/*.md(x)` (standalone pages) and `blog/` if the user wants them; `src/pages/*.tsx` React pages have no source to convert: report them.
+- Versions: `versioned_docs/version-<name>/` with `versioned_sidebars/version-<name>-sidebars.json`; order in `versions.json` (newest first). `docs/` is the `current` version.
+- Locales: `i18n/<locale>/docusaurus-plugin-content-docs/current/` (and `.../version-<name>/` for versions), sidebar/category label translations in `i18n/<locale>/docusaurus-plugin-content-docs/current.json`.
+- Files prefixed with `_` are partials (not pages). `draft: true` docs are not published: exclude them.
+
+### From an export
+
+None; the site is built from the repo.
+
+### From the live site
+
+Scrape with `npx -p @mintlify/scraping@latest -p puppeteer mintlify-scrape section <url>` (add `--filter=/docs` for a `routeBasePath`), then fix port artifacts E (`prism-code` fences) and F (admonition leaked into `description`) (`mint migrate --topic conversion`, Port artifacts).
+
+## Config → docs.json
+
+| Docusaurus                                                                  | docs.json                                                                        |
+| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `title`                                                                     | `name`                                                                           |
+| `tagline`                                                                   | `description`                                                                    |
+| `favicon` (path in `static/`)                                               | `favicon`                                                                        |
+| `themeConfig.navbar.logo` `src` / `srcDark` / `href`                        | `logo.light` / `logo.dark` / `logo.href`                                         |
+| `themeConfig.navbar.items` of type `doc`, `docSidebar`                      | `navigation.tabs` (one per sidebar)                                              |
+| `themeConfig.navbar.items` with `href` (external)                           | `navbar.links` (GitHub link: `type: "github"`)                                   |
+| `themeConfig.navbar.items` `docsVersionDropdown`, `localeDropdown`          | drop: replaced by `navigation.versions` / `navigation.languages` switchers       |
+| `themeConfig.navbar.items` `search`, `html`, custom types                   | drop and report                                                                  |
+| `themeConfig.footer.links` (columns)                                        | `footer.links` (`title` → `header`, `items[].to`/`href` → `href`)                |
+| `themeConfig.footer.copyright`, `footer.logo`, `footer.style`               | drop and report                                                                  |
+| `themeConfig.colorMode.defaultMode` / `disableSwitch`                       | `appearance.default` / `appearance.strict`                                       |
+| `themeConfig.prism.theme` / `darkTheme`                                     | `styling.codeblocks` only if a matching Shiki theme exists; else drop and report |
+| `themeConfig.announcementBar` `content` / `isCloseable`                     | `banner.content` (HTML → Markdown links) / `banner.dismissible`; colors drop     |
+| `themeConfig.metadata`, `themeConfig.image`                                 | `seo.metatags` (`image` → `"og:image"`)                                          |
+| `themeConfig.algolia`                                                       | drop and report                                                                  |
+| `i18n.locales` / `defaultLocale`                                            | `navigation.languages` (use a supported code)                                    |
+| preset `gtag.trackingID`                                                    | `integrations.ga4.measurementId`                                                 |
+| preset `googleTagManager.containerId`                                       | `integrations.gtm.tagId`                                                         |
+| `@docusaurus/plugin-client-redirects` `redirects`                           | `redirects` (see URLs)                                                           |
+| `@docusaurus/theme-mermaid`, `remark-math` + `rehype-katex`                 | drop (native in Mintlify); keep the fences and `$` math                          |
+| `url`, `baseUrl`, `trailingSlash`                                           | drop; use them to compute old URLs                                               |
+| `docs.editUrl`, `showLastUpdateTime`, `showLastUpdateAuthor`, `breadcrumbs` | drop and report                                                                  |
+| `theme.customCss`, swizzled `src/theme/*`                                   | drop and report                                                                  |
+| OpenAPI plugins (`docusaurus-plugin-openapi-docs`, `redocusaurus`)          | spec file; see `mint migrate --topic api`                                        |
+
+## Navigation
+
+- Resolve the sidebar, do not parse it as text: run `node -e "console.log(JSON.stringify(require('./sidebars.js'),null,2))"` (for TS or ESM, import it with `npx tsx`). If `sidebarPath` is unset, the whole sidebar is autogenerated from the docs folder.
+- One sidebar object key = one tab (or one group if there is only one sidebar). Keep item order, labels and nesting.
+- Item mapping:
+  - doc id string or `{type: 'doc', id, label}` → page path (`label` differing from the H1 → `sidebarTitle`).
+  - `{type: 'category', label, items}` → nested group with `group: label`.
+  - category `link: {type: 'doc', id}` → that doc is the group `root`.
+  - category `link: {type: 'generated-index', title, description, slug}` → create an index page from those fields (cards for the children) and make it the `root`; its old URL is `/<routeBasePath>/category/<category name>` (slugified) unless `slug` is set.
+  - `{type: 'link', href, label}` → a page whose frontmatter is `title: label` + `url: href`, listed at that position; `{type: 'html'}` → drop and report; `{type: 'ref'}` → page path.
+  - `collapsed: false` on a nested category → `expanded: true`.
+- Doc ids: default id is the file path without extension and number prefixes; front matter `id` replaces only the last segment. Map ids to files before mapping the sidebar.
+- `{type: 'autogenerated', dirName}`: expand it the way Docusaurus does. Order within a folder: `sidebar_position` (docs) and `_category_` `position` (folders) ascending, then alphabetical by file/folder name. Number prefixes (`01-intro.md`) order items and are stripped from ids, labels and URLs. Folder label: `_category_` `label`, else folder name. A folder's `index.md`, `README.md` or `<folder>/<folder>.md` is the category's linked doc (group `root`), unless `_category_` sets `link` (`mint migrate --topic conversion`, Files).
+- Labels: `sidebar_label` → `sidebarTitle`. `_category_` `className`, `customProps`, `collapsible` → drop.
+- Cross-check the result against the rendered sidebar on the live site; custom `sidebarItemsGenerator` functions change all of the above.
+- Versions: one `navigation.versions` entry per kept version, built from `versioned_sidebars/`; make the `lastVersion` (default: first in `versions.json`) the default. Keep version content in per-version folders.
+- Doc front matter `displayed_sidebar`, `pagination_*` → drop.
+
+## Content conversion
+
+Admonitions: (`mint migrate --topic conversion`, Admonitions). Docusaurus-specific mapping:
+
+| Docusaurus                                                          | Mintlify                                                                                              |
+| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `:::warning`                                                        | `<Warning>` (v2: rendered red, use `<Danger>` if the text warns of damage)                            |
+| Admonition title (v3 `:::note[Title]`, v2 `:::note Title`)          | (`mint migrate --topic conversion`, Components)                                                       |
+| `<Admonition type="...">` from `@theme/Admonition`                  | same mapping as the directive                                                                         |
+| `<Tabs>` + `<TabItem value label default>`                          | `<Tabs>` + `<Tab title={label}>` (no `label` → `value`); `default`/`defaultValue` → `defaultTabIndex` |
+| `groupId`, `queryString`, `lazy`, `values={[...]}`                  | drop (titles in `values` become `Tab` titles)                                                         |
+| Tabs whose every item is one code block                             | `<CodeGroup>` with the label as the fence title                                                       |
+| ` ```js title="a.js" `                                              | ` ```js a.js ` or keep `title="a.js"`                                                                 |
+| ` ```js {1,4-6} `                                                   | `highlight={1,4-6}`                                                                                   |
+| `// highlight-next-line`, `// highlight-start` / `// highlight-end` | remove the comment lines; put the resulting line numbers in `highlight={...}`                         |
+| `showLineNumbers` (`=N` start offset)                               | `lines` (offset drops)                                                                                |
+| ` ```bash npm2yarn `                                                | (`mint migrate --topic conversion`, Package-manager tabs)                                             |
+| ` ```jsx live ` (theme-live-codeblock)                              | static code block; report                                                                             |
+| `<CodeBlock language title>` from `@theme/CodeBlock`                | fenced block                                                                                          |
+| `import X from './_x.mdx'` + `<X />` (partial)                      | (`mint migrate --topic conversion`, Reusable content)                                                 |
+| `import Code from './file.js' with {type: 'text'}`                  | (`mint migrate --topic conversion`, Code imports)                                                     |
+| `<details><summary>T</summary>`                                     | `<Accordion title="T">`                                                                               |
+| `<DocCardList />`                                                   | `<Card>` per child page in a `<Columns cols={2}>`                                                     |
+| `<TOCInline toc={toc} />`                                           | drop and report                                                                                       |
+| `@site/src/components/*`                                            | (`mint migrate --topic conversion`, Components)                                                       |
+| `useBaseUrl(...)`, `useDocusaurusContext`, `@docusaurus/*` imports  | resolve to a literal value; drop the import                                                           |
+| `@theme/*` imports                                                  | delete after converting the component                                                                 |
+| `<!-- truncate -->` / `{/* truncate */}` (blog)                     | delete                                                                                                |
+
+Heading ids: v3 `## Title {/* #id */}` and v2/`mdx1Compat` `## Title {#id}` (`mint migrate --topic conversion`, Heading IDs).
+
+Front matter: `id` → drop (used for URLs, see below); `slug` → drop (used for URLs); `title`, `keywords` keep; `sidebar_label` → `sidebarTitle`; `unlisted: true` → `hidden: true`; `image` → `"og:image"`; `hide_title`, `hide_table_of_contents`, `toc_*_heading_level`, `sidebar_position`, `sidebar_class_name`, `sidebar_custom_props`, `sidebar_key`, `custom_edit_url`, `last_update`, `parse_number_prefixes`, `tags` → drop. `description` is meta-only and defaults to the first line of content (`mint migrate --topic conversion`, Frontmatter).
+
+MDX version: v2 sources are MDX 1 and often contain `<!-- -->` comments, unescaped `{`/`<`, string `style` attributes (`mint migrate --topic conversion`, MDX safety). v3 with `markdown.format: 'detect'` treats `.md` as CommonMark.
+
+## Assets
+
+- `static/` and every `staticDirectories` entry are served at the site root: `static/img/a.png` → `/img/a.png` (`mint migrate --topic conversion`, Images and files).
+- `@site/static/img/a.png` in imports or `require()` → `/img/a.png`.
+- Co-located images (`./assets/a.png`, `require('./a.png')`, `import img from './a.png'`) → move under a root folder and rewrite to root-relative paths.
+- `pathname:///img/a.png` → `/img/a.png`.
+- GitHub-style themed images (`#gh-light-mode-only` / `#gh-dark-mode-only`) and `@theme/ThemedImage` → two `<img>` tags with `className="block dark:hidden"` / `"hidden dark:block"`.
+- `@docusaurus/plugin-ideal-image` `<Image img={require(...)}/>` → `<img>`.
+
+## URLs and redirects
+
+- Doc URL = `baseUrl` + `routeBasePath` (default `docs`; `/` means docs-only) + version path + slug. Locale prefix `/<locale>/` comes before everything for non-default locales.
+- Slug: front matter `slug` (absolute `/x` from `routeBasePath`, relative `x` from the doc's folder); else the doc id path with number prefixes removed; `index`, `README` and `<folder>/<folder>` files resolve to the folder URL.
+- Versions: `lastVersion` serves at `/<routeBasePath>/`, `current` at `/<routeBasePath>/next/` (unless `lastVersion: 'current'`), others at `/<routeBasePath>/<version>/`; `versions.<name>.path` overrides.
+- `trailingSlash: true` → URLs end in `/`; `false` → files emitted as `/docs/page.html`, so hosts may also serve the `.html` form.
+- Emit redirects (`mint migrate --topic navigation`, Redirects) for: the `routeBasePath` prefix if you move docs to root, every slug/id-based URL that differs from the new file path, `/category/<slug>` generated-index pages, version and locale prefixes, and every existing `plugin-client-redirects` entry (`from` array → one entry each, `to` → `destination`). `createRedirects` functions and `fromExtensions`/`toExtensions`: expand to exact entries from the sitemap.
+- Tags pages (`/<routeBasePath>/tags/...`) have no target: redirect to the closest page or report.
+
+## Known gaps
+
+Report each that the site uses:
+
+- Swizzled theme components, `src/theme/*`, custom CSS (Infima classes do not exist in Mintlify).
+- React pages in `src/pages/*.tsx`, interactive components without a static equivalent, `react-live` blocks.
+- Doc tags and tag index pages, `<TOCInline>`, per-page TOC heading levels.
+- Edit URLs, last-updated author/time, breadcrumbs toggle, pagination overrides.
+- Tab `groupId` persistence and `queryString` deep links.
+- Docusaurus blog (author pages, tag/archive pages, RSS): see `mint migrate --topic changelog` if it is a changelog.
+- Algolia DocSearch config and any search plugin.
+- Docs plugin instances beyond what tabs/products can hold, `onlyIncludeVersions` subsets.

package/migrate/sources/fern.md

@@ -0,0 +1,130 @@
+# Fern
+
+## Detect
+
+- `fern/docs.yml` next to `fern/fern.config.json` (also nested, for example `docs/fern/`). `fern.config.json` without `docs.yml` is an SDK-only project; the docs live elsewhere.
+- API definitions in the same folder: `generators.yml` with `api.specs` (OpenAPI, AsyncAPI), `fern/apis/<name>/` for several APIs, or a Fern Definition (`api.yml` plus YAML service and type files).
+- A stale `docs.yml` can outlive a move off Fern. Confirm the live site: `curl -sI https://<docs-domain>/ | grep -i x-fern`.
+- Only the docs move. Do not delete or edit `generators.yml`, the definition or `fern.config.json`; SDK generation uses them.
+
+## Get the source
+
+Mintlify's guide for this platform: https://www.mintlify.com/docs/migration/fern.md
+
+### From the repo
+
+- Read `docs.yml`, then every file it references (product and version YAML, redirect files, `css`, `js`). Paths in a Fern YAML file are relative to that file.
+- Pages: `.md`/`.mdx` files referenced by a `path` or found by a `folder` entry. Unreferenced files are not published.
+- Snippets live in a `snippets/` folder; changelog entries in a `changelog/` folder (reserved name).
+
+### From an export
+
+Not covered yet. Use the repo.
+
+### From the live site
+
+Clean Markdown at `<page-url>.md`; page list at `/llms.txt`.
+
+Reference: https://buildwithfern.com/learn/docs/getting-started/project-structure
+
+## Config → docs.json
+
+| docs.yml                                                                                                                                                                                                        | docs.json                                                                                 |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `title`                                                                                                                                                                                                         | `name`                                                                                    |
+| `logo.light` / `logo.dark` / `logo.href`                                                                                                                                                                        | `logo.light` / `logo.dark` / `logo.href`                                                  |
+| `favicon`                                                                                                                                                                                                       | `favicon`                                                                                 |
+| `colors.accent-primary` (string or `{ light, dark }`)                                                                                                                                                           | `colors.primary` (+ `colors.light` / `colors.dark`)                                       |
+| `colors.background`                                                                                                                                                                                             | `background.color`                                                                        |
+| `typography.bodyFont` / `headingsFont`                                                                                                                                                                          | `fonts.body` / `fonts.heading`                                                            |
+| `navbar-links` `type: filled`                                                                                                                                                                                   | `navbar.primary`                                                                          |
+| `navbar-links` `type: github`                                                                                                                                                                                   | `navbar.links` (`type: github`)                                                           |
+| `navbar-links` `type: minimal` / `outlined` (`url` is an older name for `href`)                                                                                                                                 | `navbar.links`                                                                            |
+| `navbar-links` `type: dropdown`                                                                                                                                                                                 | flatten into `navbar.links`; report                                                       |
+| `footer-links`                                                                                                                                                                                                  | `footer.socials` (`hackernews` → `hacker-news`)                                           |
+| `announcement.message`                                                                                                                                                                                          | `banner.content`                                                                          |
+| `analytics.ga4.measurement-id`, `analytics.gtm.container-id`, `analytics.posthog.api-key`                                                                                                                       | `integrations.ga4.measurementId`, `integrations.gtm.tagId`, `integrations.posthog.apiKey` |
+| `metadata.og:*`, `metadata.twitter:*`                                                                                                                                                                           | `seo.metatags`                                                                            |
+| `settings.search-text`                                                                                                                                                                                          | `search.prompt`                                                                           |
+| `settings.http-snippets`, `default-language`                                                                                                                                                                    | `api.examples.languages`                                                                  |
+| `css`, `js`                                                                                                                                                                                                     | (`mint migrate --topic navigation`, Chrome)                                               |
+| `redirects`                                                                                                                                                                                                     | URLs below                                                                                |
+| `instances[].url`, `custom-domain`                                                                                                                                                                              | none; host and path are part of every old URL                                             |
+| `instances[].edit-this-page`, other `colors.*`, `layout.*`, `theme.*`, `settings.*`, `global-theme`, `page-actions`, `background-image`, `header` / `footer` components, `ai-search`, `ai-chat`, `landing-page` | drop and report                                                                           |
+
+Reference: https://buildwithfern.com/learn/docs/configuration/site-level-settings
+
+## Navigation
+
+`docs.yml` `navigation` is the sidebar; folders on disk do not define it. References: https://buildwithfern.com/learn/docs/configuration/navigation, `/tabs`, `/versions`, `/products` under the same path.
+
+- `tabs:` (key → `display-name`, `icon`, `slug`, `skip-slug`, `href`, `changelog`) with `navigation: - tab: <key>` + `layout:` → tabs; an `href` tab → tab `href`. Tab `variants`: keep the default; report.
+- `section` + `contents` → group; nested sections → nested groups; section `path` → `root`; `collapsed: true` → `expanded: false`; `collapsed: open-by-default` → `expanded: true`.
+- `page: Label` + `path` → page; `Label` (or frontmatter `sidebar-title`) → `sidebarTitle` when it differs from `title`.
+- `folder: ./dir` (+ `title`) → group of that folder's files: `index` → `root`; frontmatter `position` (numeric) first, then alphabetical; subfolders → nested groups.
+- `link` + `href` → `navigation.global.anchors`.
+- `api: Name` (+ `api-name`) → a group with that API's spec.
+- `changelog: ./changelog` → the changelog page at that position.
+- `hidden: true` → hidden page or group.
+- `availability` (`beta`, `pre-release`, `in-development`, `deprecated`) → `tag`, or `deprecated`.
+- `products:` (`display-name`, `path`, `icon`, `subtitle`, `href`) → `navigation.products` (`subtitle` → `description`).
+- `versions:` (`display-name`, `path`, `availability`) → `navigation.versions`; the first is the default.
+
+## Content conversion
+
+Fern and Mintlify component names overlap but props differ. Reference: https://buildwithfern.com/learn/docs/writing-content/components/overview
+
+| Fern                                                                                                                                                                                                               | Mintlify                                                                                          |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| `<Note>`, `<Tip>`, `<Info>`, `<Warning>`, `<Check>`                                                                                                                                                                | same                                                                                              |
+| `<Success>` / `<Error>` / `<Launch>` / `<Callout intent>`                                                                                                                                                          | `<Check>` / `<Danger>` / `<Info>` / the matching callout                                          |
+| `<TabGroup>`, `<Tab language>`                                                                                                                                                                                     | `<Tabs>`, `<Tab>`                                                                                 |
+| `<CodeBlocks>`                                                                                                                                                                                                     | `<CodeGroup>`                                                                                     |
+| `<CodeBlock title>` around a fence                                                                                                                                                                                 | the fence with that title                                                                         |
+| fence `filename=`, `wordWrap`, `{1,3-4}`                                                                                                                                                                           | fence title, `wrap`, `highlight={1,3-4}`                                                          |
+| `<Code src>`                                                                                                                                                                                                       | (`mint migrate --topic conversion`, Code imports)                                                 |
+| `<CardGroup>` / `<Card>`                                                                                                                                                                                           | `<Columns>` / `<Card>`                                                                            |
+| `<ParamField path="name">` (Fern's `path` is the field name)                                                                                                                                                       | `<ParamField>` with `query`, `body`, `header` or `path` by context                                |
+| `<Files>` / `<Folder>` / `<File>`                                                                                                                                                                                  | `<Tree>` / `<Tree.Folder>` / `<Tree.File>`                                                        |
+| `<Badge intent>`                                                                                                                                                                                                   | `<Badge color>`                                                                                   |
+| `<Aside>`                                                                                                                                                                                                          | `<Panel>`                                                                                         |
+| `<Indent>`                                                                                                                                                                                                         | unwrap; nested fields → `<Expandable>`                                                            |
+| `<Button href>`, `<Download src>`                                                                                                                                                                                  | a link or `<Card>`, a link to the file                                                            |
+| `<Versions>` / `<Version title>`                                                                                                                                                                                   | `<Tabs>` / `<Tab>`                                                                                |
+| `<If products versions roles>`                                                                                                                                                                                     | the content for this page's product or version; report role-gated text                            |
+| `<EndpointRequestSnippet>`, `<EndpointResponseSnippet>`, `<EndpointSchemaSnippet>`, `<WebhookPayloadSnippet>`, `<Schema>`, `<RunnableEndpoint>`                                                                    | link to the endpoint page, or `<RequestExample>` / `<ResponseExample>` with static fences; report |
+| `<Markdown src="/snippets/x.mdx" k="v" />`; `{{k}}` inside the snippet                                                                                                                                             | (`mint migrate --topic conversion`, Reusable content); `{{k}}` → `{k}`                            |
+| custom React components                                                                                                                                                                                            | (`mint migrate --topic conversion`, Reusable content)                                             |
+| `## Title [#slug]`                                                                                                                                                                                                 | (`mint migrate --topic conversion`, Heading IDs)                                                  |
+| changelog files named `YYYY-MM-DD`, `MM-DD-YYYY` or `MM-DD-YY`; `overview.mdx`; frontmatter `tags`; `<ChangelogTags>`                                                                                              | see `mint migrate --topic changelog`; the file name is the date; drop `<ChangelogTags>`           |
+| frontmatter `sidebar-title`, `subtitle`                                                                                                                                                                            | `sidebarTitle`, `description` (if none)                                                           |
+| frontmatter `layout: reference` / `page` / `custom`                                                                                                                                                                | `mode: "wide"` / `"center"` / `"custom"`                                                          |
+| frontmatter `hide-nav-links` / `last-updated` / `availability: deprecated`                                                                                                                                         | `hideFooterPagination` / `lastUpdatedDate` / `deprecated`                                         |
+| frontmatter `slug`, `canonical-url`                                                                                                                                                                                | URLs below                                                                                        |
+| frontmatter `hide-toc`, `max-toc-depth`, `hide-feedback`, `hide-page-actions`, `edit-this-page-url`, `image`, `logo`, `headline`, `nofollow`, `jsonld*`, `search-metadata`, `position`, `layout: guide`/`overview` | drop                                                                                              |
+
+## Assets
+
+- Copy asset folders referenced from pages and `docs.yml` (logo, favicon, fonts, icons) at their relative paths.
+- OpenAPI/AsyncAPI specs from `generators.yml` `api.specs`: use them in place; download remote ones.
+- Fern Definition: export with `fern export [--api <name>] <file>.json`; report that it must be re-exported when the definition changes.
+- Fern `overlays` are OpenAPI Overlays. Fern `overrides` are Fern's own deep-merge format; `fern api enrich` merges their `x-fern-examples` into the spec; SDK-only `x-fern-*` keys can be ignored (`mint migrate --topic api`).
+
+Reference: https://buildwithfern.com/learn/api-definitions/overview/project-structure
+
+## URLs and redirects
+
+- URLs come from `docs.yml`, not file paths (https://buildwithfern.com/learn/docs/seo/configuring-slugs). Each level contributes its `slug` or its kebab-cased display name: product, version, tab, section, folder, page. `skip-slug: true` drops a level. A frontmatter `slug` replaces everything below the product/version prefix. The first version has no prefix.
+- Compute each old URL with these rules and check it against `sitemap.xml`.
+- Changelog entries were served at `<changelog-path>/<YYYY>/<M>/<D>` (no zero padding).
+- Endpoint pages sat under the `api` entry's slug; to keep them, see `mint migrate --topic api`.
+- `docs.yml` `redirects` (`source`, `destination`, `permanent`), including regex segments (`:slug(.*)`) and sources with more than one wildcard: (`mint migrate --topic navigation`, Redirects).
+
+## Known gaps
+
+- Fern Definition content missing from the OpenAPI export; WebSocket, gRPC and OpenRPC references.
+- SDK snippets from `generators.yml`, API Explorer behavior, audiences.
+- Role, feature-flag and `viewers` gating; authentication.
+- Tab variants, `landing-page`, custom header and footer components, global themes, Ask Fern.
+- Same-day changelog entries Fern merged into one URL; changelog RSS URLs.
+- Multiple `instances` (one Mintlify site per domain).

package/migrate/sources/fumadocs.md

@@ -0,0 +1,141 @@
+# Fumadocs
+
+Docs built with Fumadocs (`fumadocs-core`, `fumadocs-ui`, `fumadocs-mdx`) on Next.js, React Router, TanStack Start, Waku or Astro. Reference: https://fumadocs.dev/docs/page-conventions and https://fumadocs.dev/docs/markdown.
+
+## Detect
+
+- `package.json` has `fumadocs-core`, `fumadocs-ui` or `fumadocs-mdx`.
+- `source.config.ts`, or `defineDocs` from `fumadocs-mdx/macro` in `lib/source.ts`, plus a `loader({ baseUrl, source })` call.
+- `meta.json` files inside the content folder (default `content/docs/`).
+- Live site: Tailwind classes prefixed `fd-` (`text-fd-primary`, `fd-steps`) and Next.js `/_next/` assets when hosted on Next.
+
+The dependency wins. `meta.json` alone is not proof.
+
+## Get the source
+
+### From the repo
+
+Content folder = `dir` in `defineDocs(...)`. Read alongside it:
+
+- `lib/source.ts`: `baseUrl`, the `icon()` handler, `i18n`, loader `plugins` (they can rewrite slugs or the tree).
+- `lib/layout.shared.tsx` (older: `app/layout.config.tsx`): `nav.title`, `links`, `githubUrl`.
+- `components/mdx.tsx` (older: `mdx-components.tsx`): components usable in MDX without an import. List them before converting.
+- `source.config.ts` `mdxOptions`: remark/rehype plugins that change syntax (`remarkSteps`, `remarkMdxFiles`, `remarkDirectiveAdmonition`, math).
+
+If content comes from a CMS integration (Notion, Sanity) the repo has no MDX; use the live site.
+
+### From an export
+
+None; the site is built from the repo.
+
+### From the live site
+
+If the site enabled the LLM integration (https://fumadocs.dev/docs/integrations/llms), fetch `/llms.txt` for the page list and `<page-url>.md` per page; components appear as JSX. Otherwise mirror the rendered `<article>`.
+
+## Config → docs.json
+
+| Fumadocs                                          | docs.json                                                       |
+| ------------------------------------------------- | --------------------------------------------------------------- |
+| `nav.title` (text or JSX)                         | `name`; image inside it → `logo`                                |
+| `githubUrl`                                       | `navbar.links` entry with `type: "github"`                      |
+| `links` (`text`, `url`, `icon`)                   | `navbar.links`, or `navigation.tabs` with `href` if in main row |
+| `<Banner>` in a layout                            | `banner`                                                        |
+| Root folders (`root: true`)                       | `navigation.tabs`                                               |
+| Root folders sharing a type (`root: "version"`)   | `navigation.versions` if versions are migrated, else report     |
+| `i18n` (`defineI18n`)                             | `navigation.languages` if languages are migrated, else report   |
+| `icon()` handler built on `lucide-react`          | `icons.library: "lucide"`                                       |
+| `loader({ baseUrl })`                             | none; affects URLs, see below                                   |
+| Search provider (Orama, Algolia, Mixedbread, ...) | drop and report                                                 |
+| Feedback, Open Graph image routes, page actions   | drop and report                                                 |
+| Theme CSS / presets                               | `colors.primary` from the rendered CSS; rest drop and report    |
+
+## Navigation
+
+Each folder's `meta.json` is the nav source. Resolve every folder, then emit groups in that order:
+
+| `meta.json`                               | Mintlify                                                                    |
+| ----------------------------------------- | --------------------------------------------------------------------------- |
+| folder `title`                            | `group` label (fallback: the folder name as Fumadocs renders it)            |
+| `pages` list                              | `pages` in that order; with no `...`, unlisted items are not in the sidebar |
+| no `pages`                                | items sorted alphabetically                                                 |
+| `"..."` / `"z...a"`                       | expand to the remaining items, alphabetical / reversed                      |
+| `"!item"`                                 | remove `item` from the expanded rest                                        |
+| `"...folder"`                             | inline that folder's items here, no nested group                            |
+| `"---Label---"`, `"---[Icon]Label---"`    | close the current group; following items form a new group `Label`           |
+| `"[Text](url)"`, `"external:[Text](url)"` | a page with frontmatter `title` + `url: <href>`, listed at that position    |
+| `index.mdx` or `pagesIndex`               | group `root`                                                                |
+| `defaultOpen: true`                       | `expanded: true` on the nested group                                        |
+| `collapsible: false`                      | report                                                                      |
+| `icon`                                    | `icon`, converted (below)                                                   |
+| `root: true` + `title`, `description`     | tab label; `description` only if you use `navigation.products`              |
+| `meta.<lang>.json`                        | that language's labels                                                      |
+
+Folders in parentheses, `(name)/`, group files without adding a URL segment. Move their files up one level and keep the nav their `meta.json` defines.
+
+Icons are names resolved by the repo's own `icon()` handler, usually PascalCase `lucide-react` exports. Convert each to its lucide.dev kebab-case name (`BookOpen` → `book-open`; strip a trailing `Icon`) and confirm it exists on lucide.dev. Drop icons you cannot confirm.
+
+## Content conversion
+
+| Fumadocs                                                           | Mintlify                                                             |
+| ------------------------------------------------------------------ | -------------------------------------------------------------------- |
+| `<Callout>` / `type="info"`                                        | `<Info>`                                                             |
+| `type="warn"` / `"warning"`                                        | `<Warning>`                                                          |
+| `type="error"`                                                     | `<Danger>`                                                           |
+| `type="success"`                                                   | `<Check>`                                                            |
+| `type="idea"`                                                      | `<Tip>`                                                              |
+| Callout `title`                                                    | (`mint migrate --topic conversion`, Components)                      |
+| `:::tip[Title]` etc. (remarkDirectiveAdmonition enabled)           | (`mint migrate --topic conversion`, Admonitions)                     |
+| `<Cards>` / `<Card icon={<X />} title href>`                       | `<Columns cols={2}>` / `<Card icon="x" title href>`                  |
+| `<Tabs items={[...]}>` + `<Tab value="A">`                         | `<Tabs>` + `<Tab title="A">`; no `value` → label from `items[i]`     |
+| `<Tabs defaultIndex>`; `groupId`, `persist`, `updateAnchor`        | `defaultTabIndex`; drop the rest                                     |
+| `<Accordions>` / `<Accordion title id>`                            | `<AccordionGroup>` / `<Accordion title id>`                          |
+| `<Steps><Step>### Title ...</Step></Steps>`                        | `<Steps><Step title="Title">...</Step></Steps>`, heading removed     |
+| `### Title [step]`, `### 1. Title` (remark-steps), `fd-steps` divs | `<Steps>` / `<Step title>`                                           |
+| `<Files>` / `<Folder name defaultOpen>` / `<File name>`            | `<Tree>` / `<Tree.Folder name defaultOpen>` / `<Tree.File name>`     |
+| ` ```files ` fence (remark-mdx-files)                              | `<Tree>`                                                             |
+| `<TypeTable type={{ key: { type, default, description } }}>`       | one `<ResponseField name type default>` per key, description as body |
+| `<include>./x.mdx</include>`                                       | (`mint migrate --topic conversion`, Reusable content)                |
+| `<include>./code.ts#region</include>`                              | (`mint migrate --topic conversion`, Code imports)                    |
+| `<Mermaid chart="...">` (user component)                           | ` ```mermaid ` fence                                                 |
+| `## Heading [#custom-id]`                                          | (`mint migrate --topic conversion`, Heading IDs)                     |
+| `## Heading [!toc]` / `[toc]`                                      | strip the marker; report                                             |
+
+Code fences:
+
+| Fumadocs meta                                     | Mintlify                                                  |
+| ------------------------------------------------- | --------------------------------------------------------- |
+| `title="x"`                                       | `title="x"`                                               |
+| `lineNumbers`                                     | `lines`                                                   |
+| `lineNumbers=N`                                   | `lines`; report the start offset                          |
+| adjacent fences with `tab="A"`                    | one `<CodeGroup>`, each block titled `A`                  |
+| `tab-group="..."`                                 | drop                                                      |
+| `// [!code highlight]` / `[!code focus]` comments | remove; `highlight={n}` / `focus={n}`                     |
+| `// [!code ++]` / `[!code --]`                    | keep                                                      |
+| `// [!code word:x]`                               | remove; report                                            |
+| `twoslash`                                        | keep                                                      |
+| ` ```npm ` fence                                  | (`mint migrate --topic conversion`, Package-manager tabs) |
+
+Imports: remove `fumadocs-ui/*`, `fumadocs-core/*` and `lucide-react` imports after converting their usages (`mint migrate --topic conversion`, Components).
+
+Frontmatter: keep `title`, `description` (Fumadocs UI renders it under the title), `icon` (converted). `full: true` → `mode: "wide"`, report. Pages with `_openapi` frontmatter that render `<OpenAPIPage>`/`<APIPage>` are generated; delete them and follow `mint migrate --topic api`.
+
+## Assets
+
+`public/` is served from the site root: `public/img/a.png` → `/img/a.png` (`mint migrate --topic conversion`, Images and files). Images imported into MDX (`import img from './a.png'`) or referenced relatively: move the file and use its root path.
+
+## URLs and redirects
+
+URL = `baseUrl` + file path slugs: `dir/page.mdx` → `<baseUrl>/dir/page`, `dir/index.mdx` → `<baseUrl>/dir`, `(group)` segments dropped. With i18n, locales prefix the path unless `hideLocale` hides it (`default-locale`: default locale unprefixed; `always`: no prefix). Loader plugins may change slugs; trust the live sitemap over the file tree.
+
+If the Mintlify site drops the `baseUrl` prefix, add a base path redirect (`mint migrate --topic navigation`, Redirects).
+
+## Known gaps
+
+Report these:
+
+- `[!toc]` / `[toc]` heading markers, `<InlineTOC>` and page-tree-driven card lists (render the list statically).
+- `<auto-type-table>`, `<auto-files>`: generated at build time; render their output statically.
+- `<DynamicCodeBlock>`, `<GithubInfo>`, `<ImageZoom>`, `<GraphView>`.
+- Custom Shiki transformers, `[!code word:]`, line number offsets, persisted tab groups.
+- `collapsible: false` folders and nested `[Text](url)` sidebar links.
+- GraphQL and AsyncAPI pages generated by Fumadocs integrations.