@mintlify/cli 4.0.1763 → 4.0.1765

package/migrate/sources/nextra.md

@@ -0,0 +1,144 @@
+# Nextra
+
+Docs built with Nextra (`nextra`, `nextra-theme-docs`) on Next.js. Reference: https://nextra.site/docs/file-conventions/meta-file and https://nextra.site/docs/guide/syntax-highlighting.
+
+## Detect
+
+- `package.json` has `nextra` and `nextra-theme-docs` (or `nextra-theme-blog`, which is a blog, not docs).
+- `next.config.*` wraps the config with `nextra({...})`.
+- `_meta.{js,jsx,ts,tsx}` files (`_meta.json` in old sites, `_meta.global.*` for a single-file tree).
+- Live site: `/_next/` assets and `nextra-` CSS classes.
+
+Then pick the generation. Config and content live in different places:
+
+| Signal                                                                   | Generation   |
+| ------------------------------------------------------------------------ | ------------ |
+| `theme.config.{js,jsx,ts,tsx}` + content in `pages/`                     | Pages Router |
+| `<Layout>` from `nextra-theme-docs` in `app/layout.*`, no `theme.config` | App Router   |
+
+## Get the source
+
+### From the repo
+
+- Pages Router: every `.md`/`.mdx` under `pages/` (or `src/pages/`) is a page.
+- App Router: `content/` (or `src/content/`) served through `app/[[...mdxPath]]/page.jsx`, and/or `app/**/page.mdx`. Both can coexist; collect both.
+- Read `next.config.*` (`basePath`, `contentDirBasePath`, `i18n`, `latex`, `redirects()`), the theme config (`theme.config.*` or the `app/layout.*` props), and `mdx-components.*` for components used without imports.
+- i18n: read `i18n.locales` in `next.config`, then find how files are split per locale (locale-suffixed files such as `index.en.mdx`, or one folder per locale). Each locale has its own `_meta` files.
+
+### From an export
+
+None; the site is built from the repo.
+
+### From the live site
+
+No raw-markdown endpoint. Mirror the rendered `<article>` per page and read the sidebar from the HTML.
+
+## Config → docs.json
+
+Pages Router keys are in `theme.config.*`; App Router keys are props on `<Layout>`, `<Navbar>`, `<Footer>`, `<Banner>` in `app/layout.*`.
+
+| Nextra                                              | docs.json                                                                 |
+| --------------------------------------------------- | ------------------------------------------------------------------------- |
+| `logo` / `<Navbar logo>` (JSX)                      | `name` from the text, `logo` from the image                               |
+| `project.link` / `<Navbar projectLink>`             | `navbar.links` entry with `type: "github"` (if GitHub)                    |
+| `chat.link` / `<Navbar chatLink>`                   | `navbar.links` entry (`type: "discord"` if Discord)                       |
+| `banner.content`, `banner.dismissible` / `<Banner>` | `banner.content`, `banner.dismissible`                                    |
+| `footer` / `<Footer>` children                      | `footer.links` / `footer.socials` if it holds links; else drop and report |
+| `head` / `<Head>`                                   | `seo.metatags` for static tags; dynamic logic drop and report             |
+| `darkMode`, `nextThemes.defaultTheme`               | `appearance`                                                              |
+| `primaryHue`, `primarySaturation`                   | `colors.primary` (take the hex from the rendered CSS)                     |
+| `lastUpdated`                                       | `metadata.timestamp`                                                      |
+| `i18n` (theme) + `i18n` (`next.config`)             | `navigation.languages` if languages are migrated, else report             |
+| `latex: true` (`next.config`)                       | none; math renders natively                                               |
+| `docsRepositoryBase`, `editLink`, `feedback`        | drop and report                                                           |
+| `search`, `sidebar.*`, `toc.*`, `navigation`        | drop and report                                                           |
+| `basePath`, `contentDirBasePath`, `trailingSlash`   | none; affect URLs, see below                                              |
+
+## Navigation
+
+Each folder's `_meta` sets order and labels for its own children. A folder's label lives in the parent `_meta`, under the folder's key.
+
+| `_meta` entry                                             | Mintlify                                                                        |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| key order                                                 | `pages` order; unlisted files follow alphabetically (`index` first if unlisted) |
+| `key: 'Label'` or `{ title }` on a page                   | `sidebarTitle` when it differs from the page H1                                 |
+| `key: 'Label'` on a folder                                | `group` label for that folder                                                   |
+| JSX title                                                 | its text                                                                        |
+| root `type: 'page'` (folder)                              | `navigation.tabs` entry `{ tab: title, groups }`                                |
+| root `type: 'page'` with `href`                           | tab with `href`                                                                 |
+| `type: 'menu'` + `items` with `href`                      | tab with `menu: [{ item, href }]`                                               |
+| `type: 'separator'` with `title`                          | close the current group; following items form group `title`                     |
+| `type: 'separator'` without `title`                       | drop                                                                            |
+| `display: 'hidden'`                                       | leave out of navigation (still served)                                          |
+| `display: 'children'`                                     | reproduce the rendered sidebar; report                                          |
+| `{ title, href }` sidebar link                            | top level: `navigation.global.anchors`; nested: drop and report                 |
+| `theme: { layout: 'full' }`                               | page frontmatter `mode: "wide"`; report                                         |
+| other `theme` keys (`sidebar`, `toc`, `typesetting`, ...) | drop and report                                                                 |
+| `'*': {...}`                                              | apply to every sibling, then drop                                               |
+| `_meta.global.*`                                          | same rules; folder entries carry children in `items`                            |
+| folder `index.mdx`, or a page with `asIndexPage: true`    | group `root`                                                                    |
+
+With the default `sidebar.defaultMenuCollapseLevel` (2), top-level folders start open; if they become nested groups, set `expanded: true`.
+
+Root `type: 'page'` entries that point at a single page (`index`, `about`) become tabs with that page, or `navbar.links` if the source shows them as utility links.
+
+## Content conversion
+
+| Nextra                                                                       | Mintlify                                                                       |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `<Callout>` / `type="default"`                                               | `<Tip>`                                                                        |
+| `type="info"`                                                                | `<Note>`                                                                       |
+| `type="warning"`                                                             | `<Warning>`                                                                    |
+| `type="error"`                                                               | `<Danger>`                                                                     |
+| `type="important"`                                                           | `<Info>`                                                                       |
+| `type={null}`                                                                | plain paragraph                                                                |
+| Callout `emoji`                                                              | drop, or `<Callout icon>` if the emoji carries meaning                         |
+| `> [!NOTE]` etc. (rendered as callouts)                                      | (`mint migrate --topic conversion`, GitHub alerts)                             |
+| `<Tabs items={[...]}>` + `<Tabs.Tab>` / `<Tab>`                              | `<Tabs>` + `<Tab title={items[i]}>`                                            |
+| `<Tabs defaultIndex>`; `storageKey`                                          | `defaultTabIndex`; drop                                                        |
+| `<Cards num={n}>` + `<Cards.Card>` / `<Card icon title href arrow>`          | `<Columns cols={n}>` + `<Card title href arrow>`; JSX icon → icon name or drop |
+| `<Steps>` wrapping `##`-`######` headings                                    | `<Steps>`; each heading and its content → `<Step title="...">`                 |
+| `<FileTree>` / `<FileTree.Folder name defaultOpen>` / `<FileTree.File name>` | `<Tree>` / `<Tree.Folder>` / `<Tree.File>` (not Mintlify's `<FileTree>`)       |
+| `<Table>`                                                                    | markdown table                                                                 |
+| `## Heading [#custom-id]`                                                    | `## Heading {#custom-id}`                                                      |
+| ` ```mermaid `                                                               | keep                                                                           |
+| ` ```math ` fence                                                            | `$$ ... $$` block                                                              |
+| inline code with `{:lang}` suffix (`` `let x{:js}` ``)                       | strip the suffix                                                               |
+
+Code fence meta:
+
+| Nextra                | Mintlify                                                  |
+| --------------------- | --------------------------------------------------------- |
+| `filename="x.js"`     | `title="x.js"`                                            |
+| `{1,4-5}`             | `highlight={1,4-5}`                                       |
+| `showLineNumbers`     | `lines`                                                   |
+| `copy`                | drop                                                      |
+| `copy=false`          | `nocopy`                                                  |
+| `/word/`, `/word/1-3` | drop; report                                              |
+| `npm2yarn`            | (`mint migrate --topic conversion`, Package-manager tabs) |
+
+Imports: remove `nextra/components`, `nextra-theme-docs`, `nextra/icons`, `next/link` and `next/image` after converting usages (`mint migrate --topic conversion`, Components).
+
+Frontmatter: keep `title`, `sidebarTitle`; drop `asIndexPage` after using it for navigation. Pages often have no frontmatter: the title is the body H1.
+
+## Assets
+
+`public/` is served from the site root: `public/demo.png` → `/demo.png` (`mint migrate --topic conversion`, Images and files). Rewrite relative static images such as `![](../public/demo.png)` and imported images to that root path. `<Image src>` from `nextra/components` and `<ImageZoom src>` become a markdown image with the same `src` and `alt`.
+
+## URLs and redirects
+
+- Pages Router: `pages/a/b.mdx` → `/a/b`; `index` → its folder.
+- App Router content dir: `content/a/b.mdx` → `<contentDirBasePath>/a/b`. App files: `app/a/b/page.mdx` → `/a/b`; `(group)` folders add no segment.
+- `basePath` in `next.config` prefixes every URL. Locales prefix the path (`/<locale>/...`). `trailingSlash: true` adds a slash.
+
+Port `async redirects()` from `next.config` and add a base path redirect if the Mintlify site drops `basePath` or `contentDirBasePath` (`mint migrate --topic navigation`, Redirects). Expand entries using `has`/`missing` or `basePath: false` to exact paths, or report them.
+
+## Known gaps
+
+Report these:
+
+- `<Bleed>`, `<Playground>`, `<Banner>` outside the layout, and `nextra-theme-blog` pages.
+- Per-page `theme` switches, `display: 'children'`, nested sidebar links, untitled separators.
+- `/word/` substring highlighting and inline `{:lang}` highlighting.
+- MathJax renderer and custom `latex` macros.
+- Edit link, feedback link, dynamic `head` logic, and custom 404 pages.

package/migrate/sources/notion.md

@@ -0,0 +1,99 @@
+# Notion
+
+Notion workspaces and pages, private or published to the web (`*.notion.site` or a custom domain). The customer exports the pages and you work on the export locally. The old pages stay on Notion, so you produce a route table instead of redirects.
+
+## Detect
+
+- Page URLs: `https://www.notion.so/<workspace>/<Title>-<32-hex id>` or `https://<domain>.notion.site/<Title>-<32-hex id>`; published sites can use a custom slug instead.
+- A Markdown & CSV export ZIP holds `.md` pages and `.csv` databases whose file and folder names end in a 32-hex page id, with a folder per page that has subpages.
+- Markdown pages contain callouts as raw HTML (`<aside>`), because Markdown has no equivalent.
+
+## Get the source
+
+### From the repo
+
+None; use an export.
+
+### From an export
+
+Formats, options and limits: https://www.notion.com/help/export-your-content
+
+- **Format.** Ask for Markdown & CSV with "Include subpages" and "Create folders for subpages" on, and files and images included. HTML is the fallback. Do not use PDF.
+- **Scope.** A page export (`•••` → Export) covers that page and, with subpages, its tree. A whole-workspace export is under Settings → General (https://www.notion.com/help/workspace-settings). Either covers only pages the exporting user can access; guests need full access. On Enterprise, owners can disable export.
+- **Delivery.** Large exports arrive as an emailed download link that expires. Ask for every part if the export is split.
+- **Databases.** A full-page database exports as a CSV of the chosen view plus one `.md` per row. Form views do not export.
+
+Inspect the layout before writing the transformer (`mint migrate --topic discovery`, From an export). Build an id → file index from the id suffix of every file and folder name.
+
+**API alternative.** If the customer prefers, they can run Notion's markdown endpoint (`GET /v1/pages/<id>/markdown`) on their machine with their own integration, shared with the pages in scope. Never ask for the token. Its syntax differs from the export (`<callout>`, `<columns>`, `<synced_block>`, `<page>`, `<unknown>` for embeds and unshared content) and long pages come back `truncated`. Reference: https://developers.notion.com/guides/data-apis/working-with-markdown-content
+
+### From the live site
+
+Public pages render client-side and serve no raw endpoint, so scraping is unreliable. Use an export. Use the published site only to confirm which pages are public and in what order they appear.
+
+## Config → docs.json
+
+Notion has almost no site chrome to carry over.
+
+| Notion                                    | docs.json                                                 |
+| ----------------------------------------- | --------------------------------------------------------- |
+| Workspace or root page name               | `name`                                                    |
+| Root page icon                            | `favicon` (ask for a logo; page icons are usually emoji)  |
+| Site header links (Notion Sites)          | `navbar.links`                                            |
+| Several teamspaces or root pages migrated | `navigation.tabs` or `navigation.products`, only as shown |
+| Page cover images, fonts, full-width      | drop and report                                           |
+| Sharing, permissions, guests              | drop and report                                           |
+| Comments, page history, analytics         | drop and report                                           |
+
+## Navigation
+
+The page hierarchy is the navigation. Build it from the export's folder nesting: a page with subpages becomes a nested group whose first page is the parent page itself (`mint migrate --topic navigation`).
+
+- The export does not record sibling order. Take it from the order of child-page links in the parent page body, then the workspace sidebar or published site as the customer sees it; ask if neither is available.
+- Map teamspaces or separate root pages to tabs only if the source presented them as separate sections.
+- Keep page titles verbatim as labels. Database row pages go under their database's group only if they were navigable pages on the source.
+
+## Content conversion
+
+Count every distinct HTML tag and block pattern in the export before mapping (`mint migrate --topic conversion`).
+
+| Notion export                                         | Mintlify                                                                                      |
+| ----------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| Page H1                                               | `title`; remove it from the body                                                              |
+| Property lines under the title (database rows)        | drop and report, unless the customer wants them as a table                                    |
+| Callout (`<aside>` with an emoji)                     | `<Note>`, `<Info>`, `<Tip>`, `<Warning>`, `<Danger>` by meaning; ask for the emoji → type map |
+| Toggle (`<details>` or a nested list item; inspect)   | `<Accordion title="...">`                                                                     |
+| Toggle heading                                        | heading followed by its content, or `<Accordion>` if the customer prefers it collapsed        |
+| Columns                                               | `<Columns>`, one child per column; unwrap if the content does not fit                         |
+| Code block with language                              | fence with the language; caption → title                                                      |
+| Equation (`$$...$$`, inline `$...$`)                  | LaTeX, unchanged                                                                              |
+| To-do (`- [ ]`, `- [x]`)                              | list; prefix each item with its status                                                        |
+| Table, simple table                                   | markdown table; HTML table made MDX-safe if cells hold blocks                                 |
+| Synced block (duplicated wherever it appears)         | snippet (`mint migrate --topic conversion`, Reusable content)                                 |
+| Link to a page (`Title%20<id>.md`)                    | root-absolute path via the id → path index (`mint migrate --topic conversion`, Links)         |
+| Page mention or link to a page outside the export     | absolute Notion URL; report                                                                   |
+| Inline or linked database view                        | markdown table of the CSV, or a list of links to its row pages; report                        |
+| Bookmark                                              | link with its title                                                                           |
+| Embed (YouTube, Figma, Loom, Google Drive, and so on) | video embed where supported, else a link; report                                              |
+| Table of contents block                               | drop                                                                                          |
+| Breadcrumb block                                      | drop                                                                                          |
+
+Decode URL-encoded link targets (`%20`) before matching ids. Strip the id suffix from every file name and slug; slugify titles for new paths.
+
+## Assets
+
+- Images and files sit in a folder next to each page, named after the page. Copy them to `images/<page-path>/` (images) or a downloads folder (other files) and rewrite references (`mint migrate --topic conversion`, Images and files).
+- Links to Notion-hosted files (`secure.notion-static.com`, signed `amazonaws.com` URLs) are signed and expire. Download them during conversion, never hotlink. Reference: https://developers.notion.com/reference/file-object
+- Notion icons and covers that are emoji or Notion's built-in images are not files; drop them.
+
+## URLs and redirects
+
+Old URLs stay on Notion, so `redirects` cannot catch them. Produce `route-table.csv` as in `mint migrate --from confluence` (URLs and redirects), keyed by the 32-hex page id: `page_id, old_url, new_path, title`. Take `old_url` from the published site or the page's share link; title segments in Notion URLs change on rename, the id does not. If the customer moves a custom domain from Notion Sites to Mintlify, add `redirects` for the old paths instead (`mint migrate --topic navigation`, Redirects). Site settings: https://www.notion.com/help/public-pages-and-web-publishing
+
+## Known gaps
+
+- Databases: views, filters, sorts, relations, rollups, formulas and properties beyond the title.
+- Synced blocks no longer sync with Notion; the snippet is the single source from now on.
+- Comments, page history, permissions, guests and sharing settings.
+- Notion-specific embeds and blocks (buttons, forms, AI blocks, link previews) with no equivalent.
+- Pages the exporting user could not access, and pages outside the exported tree.

package/migrate/sources/nuxt.md

@@ -0,0 +1,113 @@
+# Nuxt Content
+
+Docs built with Nuxt and the Nuxt Content module, including Docus and Nuxt UI Pro docs templates.
+
+## Detect
+
+- Rendered HTML contains `<div id="__nuxt">` and sets `window.__NUXT__`.
+- Static assets load from `/_nuxt/`.
+- `<page-url>/_payload.json` returns JSON instead of 404.
+- In a repo: `nuxt.config.ts` with `@nuxt/content` (or `@nuxt-themes/docus`) in `modules`, and pages under `content/`.
+
+## Get the source
+
+### From the repo
+
+Pages are markdown in `content/`, written in MDC syntax. Nav order comes from numeric filename prefixes (`1.getting-started/2.installation.md`) and `.navigation.yml` / `_dir.yml` files. Config lives in `nuxt.config.ts` and `app.config.ts`.
+
+### From an export
+
+None; the site is built from the repo.
+
+### From the live site
+
+Each page's `_payload.json` holds the page body as a structured AST ("minimark": `{ type, tag, props, children }` nodes, or compact arrays `[tag, props, ...children]`) plus, usually, the site navigation tree. Convert from this AST, not from rendered HTML.
+
+Mirror `<page-url>/_payload.json` for every page (`mint migrate --topic discovery`, Mirror the raw source). Spot-check one:
+
+```bash
+curl -sS https://docs.example.com/guide/setup/_payload.json | python3 -m json.tool | head -60
+```
+
+It should show element nodes (`"tag": "h1"` and so on), not HTML. If `_payload.json` 404s site-wide but the site is still Nuxt, look for `_payload.js` and extract the embedded payload with a small Node script before falling back to HTML. Some Nuxt Content sites also expose raw markdown or a query API under `/api/_content/` or `/__nuxt_content/`; prefer raw markdown if it is served.
+
+Pick one URL form during inventory. `/foo` and `/foo/` may both return 200, but usually only one serves `_payload.json`. Mixing them creates duplicate mirror files.
+
+## Config → docs.json
+
+| Nuxt                                           | docs.json                                                                    |
+| ---------------------------------------------- | ---------------------------------------------------------------------------- |
+| `app.config.ts` site name / `seo.siteName`     | `name`                                                                       |
+| `app.config.ts` header logo (light/dark)       | `logo.light`, `logo.dark`                                                    |
+| `public/favicon.*`                             | `favicon`                                                                    |
+| `app.config.ts` `ui.primary` / theme colors    | `colors.primary` (resolve the named color to its hex from the rendered CSS)  |
+| Header links (`header.links`)                  | `navbar.links`, or `navigation.tabs` with `href` if they sit in the main row |
+| Footer links / socials                         | `footer.links`, `footer.socials`                                             |
+| Top-level content folders shown as header tabs | `navigation.tabs`                                                            |
+| `seo` / `useSeoMeta` defaults                  | `seo.metatags`                                                               |
+| `content.highlight` themes                     | drop and report                                                              |
+| Search (Algolia DocSearch, built-in)           | drop and report                                                              |
+| Analytics modules, custom plugins, middleware  | drop and report                                                              |
+| i18n (`@nuxtjs/i18n`)                          | `navigation.languages` if the user migrates other languages, else report     |
+
+## Navigation
+
+Use the navigation tree from `_payload.json` (look for a `navigation` key at the top level or under `data`) or, in a repo, the ordered `content/` tree. Each node has `title`, `_path` or `path`, and `children`. Nodes with children become nested groups; their own page, if any, goes first in the group.
+
+Labels: the node `title` is the sidebar label. If it differs from the page H1, set `sidebarTitle`. Drop numeric prefixes from paths and labels. Respect `navigation: false` in page front matter (page exists but is hidden) and `navigation.title` / `navigation.icon` overrides. Nuxt icons are usually Iconify names (`mint migrate --topic conversion`, Icons).
+
+## Content conversion
+
+Walk the AST and emit markdown and Mintlify components. Count every distinct `tag` across the mirror first (`mint migrate --topic conversion`):
+
+```python
+import json, glob, collections
+tags = collections.Counter()
+def walk(n):
+    if isinstance(n, dict):
+        if 'tag' in n: tags[n['tag']] += 1
+        for v in n.values(): walk(v)
+    elif isinstance(n, list):
+        if n and isinstance(n[0], str) and len(n) > 1 and isinstance(n[1], dict): tags[n[0]] += 1
+        for v in n: walk(v)
+for f in glob.glob('mirror/*.json'):
+    walk(json.load(open(f)))
+print(tags.most_common())
+```
+
+| MDC / component                                                               | Mintlify                                                        |
+| ----------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `::callout`, `::note`, `::tip`, `::warning`, `::caution`, `::alert{type=...}` | `<Note>`, `<Tip>`, `<Warning>`, `<Danger>`, `<Info>` by meaning |
+| `::steps`, `::Steps` with `###` children                                      | `<Steps>` / `<Step title>`                                      |
+| `::tabs` / `::code-group`                                                     | `<Tabs>` / `<CodeGroup>`                                        |
+| `::card`, `::card-group`, `::card-grid`                                       | `<Card>`, `<CardGroup>`                                         |
+| `::collapsible`, `::accordion`                                                | `<Accordion>`, `<AccordionGroup>`                               |
+| `::field`, `::field-group`                                                    | `<ParamField>` / `<ResponseField>`                              |
+| `::badge`, `:badge[...]`                                                      | `<Badge>`                                                       |
+| `:icon{name=...}`                                                             | `<Icon icon="...">` (`mint migrate --topic conversion`, Icons)  |
+| `pre` with `filename`, `highlights` props                                     | fenced block with filename and `{1,3}` line highlights          |
+| `prose-*` tags (`prose-h2`, `prose-a`, ...)                                   | the plain markdown element                                      |
+| Site-specific components (custom `components/content/*.vue`)                  | (`mint migrate --topic conversion`, Components)                 |
+
+Hazards:
+
+- Inline MDC attributes (`text{.class}`, `[link]{target=_blank}`) must be stripped; they are not MDX.
+- Props in the AST (`:prop` bindings, `v-bind`) are data, not text. Do not dump them into the page.
+- Front matter blocks inside components (`---` YAML inside `::card`) are props.
+- Vue components with slots (`#title`, `#default`) map to component props and children.
+
+## Assets
+
+Images are under `public/` in the repo, or `/_nuxt/` and `/images/` on the live site (`mint migrate --topic conversion`, Images and files). Nuxt Image (`<NuxtImg>`, `/_ipx/` URLs) serves resized variants: strip the `/_ipx/<modifiers>/` prefix to get the original file.
+
+## URLs and redirects
+
+Nuxt Content paths are the `content/` paths with numeric prefixes and `index` removed (`content/1.guide/0.index.md` → `/guide`). Keep those paths. Port redirects defined in `nuxt.config.ts` `routeRules` (`mint migrate --topic navigation`, Redirects).
+
+## Known gaps
+
+- Custom Vue components and interactive playgrounds: static content only.
+- `app.config.ts` UI theming beyond primary color, logo and fonts.
+- Built-in or Algolia search configuration, analytics modules.
+- Content queries rendered on the page (`ContentList`, `ContentQuery`): migrate the rendered output as static content.
+- Iconify icons with no Font Awesome equivalent.

package/migrate/sources/pdf.md

@@ -0,0 +1,99 @@
+# PDF
+
+One or more PDF files the customer provides locally: manuals, guides, exported specs. There is no navigation data or URL space, so structure comes from the PDF outline and headings.
+
+## Detect
+
+- The customer points you at `.pdf` files, or the current directory holds them.
+- Check each file before choosing a method:
+  - `pdfinfo file.pdf` for page count and producer.
+  - `pdffonts file.pdf`: no fonts listed means scanned pages (images only).
+  - `pdftotext -f 1 -l 3 file.pdf - | head`: empty or garbled output also means scanned or broken text encoding.
+
+## Get the source
+
+### From the repo
+
+Not applicable; the customer provides the PDF files.
+
+### From an export
+
+The PDFs are the source. Copy them unchanged into `mirror/` and work from the copies.
+
+Extract in this order of preference:
+
+1. **Native PDF reading**, if your tool reads PDFs directly with layout. Still render pages to images for table and figure checks (below).
+2. **PyMuPDF** (`pip install pymupdf`, imported as `fitz`) for structure. `page.get_text("dict")` returns blocks, lines and spans with font name, size and flags (bold, italic, monospace); use these to rebuild headings and code. `page.find_tables()` locates tables.
+3. **Poppler** for plain text: `pdftotext -layout -f N -l M file.pdf out.txt` keeps columns and table alignment; `pdftohtml -xml file.pdf out` gives positioned text with font specs when PyMuPDF is unavailable.
+
+Render each page to an image for checking: `pdftoppm -png -r 110 -f N -l N file.pdf mirror/pages/p` or PyMuPDF `page.get_pixmap(dpi=110).save(...)`.
+
+**Scanned PDFs.** Run OCR into a new file and extract from that: `ocrmypdf --skip-text file.pdf mirror/file.ocr.pdf` (add `-l <lang>` for non-English). Mark every page converted from OCR in the manifest `notes` as `ocr` and list them in the report; OCR text needs a human proofread.
+
+Encrypted PDFs that refuse extraction: ask the customer for an unlocked copy. Never try to bypass the protection.
+
+### From the live site
+
+Not applicable.
+
+## Config → docs.json
+
+| PDF                                               | docs.json                                                              |
+| ------------------------------------------------- | ---------------------------------------------------------------------- |
+| Document title (title page or metadata)           | `name`, if the customer has no product name to use                     |
+| Logo on the title page                            | `logo`, only if the customer confirms it                               |
+| Several PDFs                                      | one group per PDF, or `navigation.tabs` if they are separate manuals   |
+| Title page, copyright page, revision history      | a page only if it has content readers need; else exclude with a reason |
+| Printed table of contents, index, list of figures | drop; navigation and search replace them                               |
+| Running headers, footers, page numbers            | drop                                                                   |
+
+## Navigation
+
+The outline (bookmarks) is the navigation data:
+
+```python
+import fitz
+for level, title, page in fitz.open("mirror/file.pdf").get_toc():
+    print(level, page, title)
+```
+
+Without PyMuPDF, `qpdf --json --json-key=outlines file.pdf` exposes the same outline.
+
+- Level 1 entries become groups (or pages, if they have no children); deeper levels become nested groups and pages. Keep labels verbatim.
+- Choose a page split depth (usually level 2) and apply it uniformly. Each page covers from its outline entry's page to the page before the next entry at the same or higher level.
+- An outline entry can start mid-page; split at its heading, not at the page break.
+- No outline: derive the tree from heading font sizes (largest size = level 1) and confirm the result with the customer before converting. The printed table of contents is a fallback source of titles and page numbers.
+
+## Content conversion
+
+Never paraphrase, summarize or reword. Every word on a page comes from the PDF.
+
+- **Page furniture.** Strip running headers, footers and page numbers: lines that repeat at the same position on most pages. Detect them by position and repetition, not by guessing text.
+- **Line and page breaks.** Rejoin lines inside paragraphs; rejoin paragraphs split across a page break. Remove end-of-line hyphenation only where the joined word is a real word (`config-\nuration` → `configuration`); keep hyphens in compounds (`command-\nline` stays `command-line` when that is how the document spells it elsewhere).
+- **Headings.** Map font size and weight to heading levels per document. The page's own title becomes frontmatter `title` (`mint migrate --topic conversion`, Frontmatter).
+- **Lists.** Rebuild bullets (`•`, `–`, `▪`) and numbered items, including nesting by indent. Join wrapped list lines.
+- **Tables.** The main hazard. Extracted text loses cell boundaries, merges multi-line cells and splits tables across pages. Rebuild each table, then compare it cell by cell against the rendered page image. Merge continued tables (repeated header row on the next page). Use an HTML table only where cells span rows or columns.
+- **Code.** Monospace spans become fenced blocks. Keep indentation and line breaks exactly; do not rejoin code lines. Add a language only when the document states it or it is unambiguous.
+- **Callouts.** Boxed "Note", "Caution", "Warning" or "Tip" paragraphs map to the matching callout component, only where the label is printed.
+- **Ligatures and characters.** Normalize ligatures (`fi`, `fl`), curly quotes in code, and non-breaking spaces. Unknown glyphs (`�`) mean an encoding problem: re-extract that page with another tool or OCR it.
+- **Cross-references.** "See section 4.2" and "on page 37" become links to the migrated page that holds that content; keep the original wording.
+- **Footnotes.** Move each footnote to the end of its page's section, keeping its number.
+
+## Assets
+
+- Extract embedded images per page: `pdfimages -png -f N -l N file.pdf images/<page-path>/fig` (use `-all` to keep original formats).
+- Vector diagrams are not images: crop the region from a high-DPI render (`page.get_pixmap(clip=rect, dpi=200)`).
+- Alt text comes from the figure caption, verbatim. No caption means alt text from the nearest heading plus "figure"; record it in the report. Keep the caption under the image.
+- Drop decorative images (logos repeated on every page, rules, backgrounds).
+
+## URLs and redirects
+
+PDFs have no URLs, so there are no redirects. Instead, record the page range of every migrated page in the manifest, using `source_url` for the file and page range: `"source_url": "manual.pdf#pages=12-18"`. Every page of every PDF maps to exactly one migrated page or is `excluded` with a reason (title page, printed table of contents, blank page). If the customer links to the PDF from elsewhere, tell them which new page replaces each section.
+
+## Known gaps
+
+- OCR accuracy on scanned pages.
+- Complex tables (merged cells, rotated headers, multi-page tables) need manual review against the page image.
+- Vector diagrams become raster crops.
+- Form fields, annotations, embedded attachments and hyperlinks inside the PDF may not survive extraction; check with `pdfinfo` and PyMuPDF `page.get_links()` and report what is lost.
+- Equations: rebuild as LaTeX only where the text is extractable; otherwise use an image of the equation and report it.

package/migrate/sources/readme.md

@@ -0,0 +1,118 @@
+# ReadMe
+
+Developer hubs hosted by ReadMe (`*.readme.io` or a custom domain): guides, API reference, recipes, custom pages and changelog.
+
+## Detect
+
+- Rendered HTML loads images from `files.readme.io`.
+- URLs use `/docs/<slug>`, `/reference/<slug>`, `/recipes/<slug>`, `/page/<slug>` and `/changelog/<slug>`, optionally behind a version or project segment (`/main/docs/...`, `/v2.0/docs/...`).
+- Page markdown contains emoji callouts (`> 📘`), `[block:...]` blocks, `<<variable>>` or `(doc:slug)` links.
+- In a repo: top-level `docs/`, `reference/`, `recipes/`, `custom_pages/`, `custom_blocks/`, `changelogs/` and `_order.yaml` files.
+
+## Get the source
+
+Mintlify's guide for this platform: https://www.mintlify.com/docs/migration/readme.md
+
+### From the repo
+
+A Git sync repo (bi-directional sync): one repo per project, one branch per ReadMe version. https://docs.readme.com/main/docs/bi-directional-sync. Layout: https://docs.readme.com/main/docs/documentation-structure
+
+- A page with children is a folder with `index.md`, the children, and `_order.yaml`.
+- `_order.yaml` is a flat list of child slugs (no extension, never `index`) in sidebar order.
+- `reference/` holds the OpenAPI files and endpoint pages; endpoint frontmatter `api.file` + `api.operationId` ties a page to an operation.
+
+### From an export
+
+Either of these, run by the customer per version, with the same layout as the repo:
+
+- ZIP export from the Branch menu, emailed to the customer. It includes OpenAPI files but not images. https://docs.readme.com/main/docs/exporting-data
+- `rdme docs export <folder>` (and `rdme reference export`) with their own API key. https://github.com/readmeio/rdme
+
+Export every maintained version. Hidden and unpublished pages are only in the repo or an export.
+
+### From the live site
+
+`<page-url>.md` returns markdown; `llms.txt` at the site root and per project lists pages. Quirks (`mint migrate --topic discovery`, Mirror the raw source):
+
+- Strip the generated frontmatter block (`updatedAt`, `agentTools`) at the top and the `# Sibling pages` / `# What's Next` sections at the end.
+- Reference `.md` pages embed the operation's spec under a `# OpenAPI definition` JSON block. Extract it as data; it is not page content.
+- The changelog index `.md` is a link list, not an entry.
+
+## Config → docs.json
+
+| ReadMe                                               | docs.json                                           |
+| ---------------------------------------------------- | --------------------------------------------------- |
+| Project name                                         | `name`                                              |
+| Logo (light/dark), favicon                           | `logo.light`, `logo.dark`, `favicon`                |
+| Brand / theme colors                                 | `colors.primary`                                    |
+| Top navigation sections (Guides, API Reference, ...) | `navigation.tabs`                                   |
+| Header links                                         | `navbar.links`                                      |
+| Versions                                             | `navigation.versions` if the customer migrates them |
+| Glossary                                             | drop; terms become `<Tooltip>` at use sites         |
+| Custom CSS / JS, custom HTML header/footer           | drop and report                                     |
+| Personalized docs, JWT login, API key injection      | drop and report                                     |
+| Metrics, Owlbot AI, suggested edits, discussions     | drop and report                                     |
+
+## Navigation
+
+- One tab per hub section the source shows (Guides, Recipes, API Reference, Changelog, custom pages).
+- `docs/` category folders become groups in folder order; inside each folder, `_order.yaml` sets page order.
+- A folder's `index.md` is the first page of its nested group.
+- From the live site, rebuild the tree from each section's rendered sidebar.
+- Frontmatter `hidden: true` pages stay reachable but out of navigation; (`mint migrate --topic navigation`, Structure rules).
+- Link pages (frontmatter `link.url`) become navigation links.
+
+## Content conversion
+
+| ReadMe                                                 | Mintlify                                                                                |
+| ------------------------------------------------------ | --------------------------------------------------------------------------------------- |
+| Blockquote starting `📘` or `ℹ️`                       | `<Info>`                                                                                |
+| `👍` or `✅`                                           | `<Check>`                                                                               |
+| `🚧` or `⚠️`                                           | `<Warning>`                                                                             |
+| `❗️` or `🛑`                                           | `<Danger>`                                                                              |
+| Callout title (text after the emoji on the first line) | bold first line (`mint migrate --topic conversion`, Components)                         |
+| `<Callout icon theme>`                                 | callout by `theme`, as above                                                            |
+| Consecutive fences with no blank line between them     | `<CodeGroup>`; the text after the language is the tab title                             |
+| `<Tabs>`, `<Accordion>`, `<Cards>`, `<Columns>`        | `<Tabs>`, `<Accordion>`, `<CardGroup>`, `<Columns>`                                     |
+| `[title](url "@embed")`, `<Embed>`                     | video embed if supported, else a link                                                   |
+| `[block:callout]`                                      | callout by its theme                                                                    |
+| `[block:code]`                                         | fences, or `<CodeGroup>` for several                                                    |
+| `[block:image]`                                        | image with caption                                                                      |
+| `[block:parameters]` / `[block:table]`                 | markdown table built from the `data` keys                                               |
+| `[block:api-header]`                                   | heading                                                                                 |
+| `[block:html]`                                         | the HTML, made MDX-safe                                                                 |
+| `[block:embed]`                                        | as `@embed`                                                                             |
+| `<<glossary:term>>`, `<Glossary>term</Glossary>`       | `<Tooltip tip="<definition from the glossary>">term</Tooltip>`                          |
+| `<<name>>`, `{user.name}` (user variables)             | the variable's default value if the customer wants it inline, else `` `name` ``; report |
+| `(doc:slug)`, `(ref:slug)` links                       | root-absolute path of the migrated page                                                 |
+| Reusable content / custom blocks (`custom_blocks/`)    | snippet (`mint migrate --topic conversion`, Reusable content)                           |
+| Custom MDX components                                  | static rendering; report                                                                |
+
+Legacy `[block:TYPE]` blocks wrap JSON terminated by `[/block]`; parse the JSON, do not regex the body. Other link schemes of the form `(<word>:slug)` may exist; count them (`mint migrate --topic conversion`).
+
+Frontmatter: `excerpt` is the subtitle shown under the title, so it maps to `description`. `deprecated: true` maps to `deprecated: true`. `metadata.robots` containing `noindex` maps to `noindex: true`. `next.pages` is the "What's Next" list; keep it as links at the end of the page. Drop `metadata.image` and report it.
+
+**API reference.** Endpoint pages are hand-written prose around a spec. Collect the spec files from `reference/` (or merge the per-page `# OpenAPI definition` fragments), then attach each operation to its migrated page with `openapi:` frontmatter at the page's original path. Do not also add a generated API tab for the same spec. See `mint migrate --topic api`.
+
+**Recipes.** Interactive step-through code walkthroughs. Migrate as a page with `<Steps>` around the steps and the full code in a fence; report the lost interactivity.
+
+**Changelog.** One `<Update>` page per `mint migrate --topic changelog`. Dates: in a Git export, frontmatter `date`; on the live site, `"created_at"` in the JSON embedded in each entry's HTML page. Tags: the entry `type` (Added, Fixed, Improved, Deprecated, Removed) as shown on the source.
+
+## Assets
+
+The ZIP export and Git repo reference images by `https://files.readme.io/...` URL without the files (`mint migrate --topic conversion`, Images and files). Look in page bodies, `[block:image]` JSON and custom pages; images used only in custom pages may need the rendered page to find.
+
+## URLs and redirects
+
+- Keep `/docs/<slug>`, `/reference/<slug>`, `/recipes/<slug>`, `/page/<slug>` paths. ReadMe slugs are flat, so nested navigation does not mean nested URLs; keep the flat path.
+- Guides and reference pages can share a slug; the section prefix keeps them distinct.
+- Default-version URLs omit the version segment; versioned URLs include it. Redirect the versioned form to whichever path you keep.
+- Every `/changelog/<slug>` redirects to the consolidated changelog page.
+
+## Known gaps
+
+- Try It API explorer state, personalized API keys and per-user variables.
+- Recipe step-through interactivity.
+- Custom pages written in HTML with page-level CSS.
+- Owlbot, metrics, suggested edits and discussion threads.
+- Hidden or beta versions the customer did not export.