@mintlify/cli 4.0.1762 → 4.0.1764

package/bin/validate/files.js

@@ -20,7 +20,7 @@ var __rest = (this && this.__rest) || function (s, e) {
 };
 import { getAST, getFileCategory, parseFrontmatter, replaceVariables } from '@mintlify/common';
 import { categorizeMdxFiles, getErrorPosition, getMintIgnore, listContentFiles, } from '@mintlify/prebuild';
-import { applyEdits, collectAnchorLinks, parseContent, relocate, selectEdits, unmapEdit, } from './mdx.js';
+import { applyEdits, collectAnchorLinks, parseContent, relocate, selectEdits, toOffset, unmapEdit, } from './mdx.js';
 import { PARSE_ERROR } from './rules/parseError.js';
 const CHECKED_CATEGORIES = new Set(['page', 'snippet', 'snippet-v2']);
 export const readSiteFiles = (baseDir) => __awaiter(void 0, void 0, void 0, function* () {
@@ -44,12 +44,24 @@ const readFrontmatter = (content) => {
     }
 };
 const REASON_POSITION = /\s*\(\d+:\d+(?:-\d+:\d+)?\)$/;
-export const toParseError = (error) => {
+const TAG_NAME_RULES = new Set(['unexpected-character', 'unexpected-eof']);
+const ESCAPE_HINT = "; if this < isn't a tag, escape it as \\<";
+const isStrayLessThan = (error, content, position) => {
+    const { source, ruleId } = (error !== null && error !== void 0 ? error : {});
+    return (source === 'micromark-extension-mdx-jsx' &&
+        typeof ruleId === 'string' &&
+        TAG_NAME_RULES.has(ruleId) &&
+        (position === null || position === void 0 ? void 0 : position.line) != null &&
+        position.column != null &&
+        content[toOffset(content, position.line, position.column) - 1] === '<');
+};
+export const toParseError = (error, content = '') => {
     const reason = error === null || error === void 0 ? void 0 : error.reason;
     const fallback = error instanceof Error ? error.message : 'could not parse this file';
     const text = typeof reason === 'string' ? reason : fallback;
     const position = error && typeof error === 'object' ? getErrorPosition(error) : null;
-    return Object.assign(Object.assign(Object.assign({}, ((position === null || position === void 0 ? void 0 : position.line) != null && { line: position.line })), ((position === null || position === void 0 ? void 0 : position.column) != null && { column: position.column })), { message: text.replace(REASON_POSITION, '') });
+    const hint = isStrayLessThan(error, content, position) ? ESCAPE_HINT : '';
+    return Object.assign(Object.assign(Object.assign({}, ((position === null || position === void 0 ? void 0 : position.line) != null && { line: position.line })), ((position === null || position === void 0 ? void 0 : position.column) != null && { column: position.column })), { message: text.replace(REASON_POSITION, '') + hint });
 };
 const parseErrorDiagnostic = (file, error) => (Object.assign(Object.assign({}, error), { rule: PARSE_ERROR.id, group: PARSE_ERROR.group, severity: PARSE_ERROR.severity, file, message: `${error.message} (other checks were skipped for this file)` }));
 const tryParseContent = (content) => {
@@ -69,7 +81,7 @@ export const parseFile = (file, content, baseDir, extras = {}) => {
         return { context: Object.assign(Object.assign({}, context), { tree: getAST(content, file) }), approximate: true };
     }
     catch (error) {
-        return { error: toParseError(error) };
+        return { error: toParseError(error, content) };
     }
 };
 const EMPTY_TREE = { type: 'root', children: [] };

package/bin/validate/mdx.js

@@ -153,7 +153,7 @@ export const selectEdits = (edits) => {
     return selected;
 };
 export const applyEdits = (content, edits) => selectEdits(edits).reduce((result, edit) => result.slice(0, edit.start) + edit.text + result.slice(edit.end), content);
-const toOffset = (content, line, column = 1) => {
+export const toOffset = (content, line, column = 1) => {
     let offset = 0;
     for (let current = 1; current < line; current++) {
         const next = content.indexOf('\n', offset);

package/bin/welcome.js

@@ -44,6 +44,7 @@ const GROUPS = [
     {
         title: 'CLI',
         commands: [
+            { name: 'agent setup', description: 'Install Mintlify skills and configure Admin MCP' },
             { name: 'config', description: 'Manage CLI configuration' },
             { name: 'update', description: 'Update to the latest version' },
         ],

package/migrate/index.md

@@ -0,0 +1,56 @@
+# Migrate a docs site to Mintlify
+
+Follow these instructions to move an existing documentation site into a Mintlify project in the current directory. The goal is reading parity: every page, every section and every URL from the source arrives in Mintlify, converted to MDX and wired into `docs.json`.
+
+Read the Mintlify docs index at https://mintlify.com/docs/llms.txt before you start, and use it to look up the `docs.json` schema and components as you go.
+
+## Get the source
+
+Work out what the user is migrating from and how you can reach it: the repo, an export, or the live site, in that order of preference. If the user has not said and it is not obvious from the current directory, ask them before doing anything else. Never modify the source; write the Mintlify project to a separate directory. Details: `mint migrate --topic discovery`.
+
+If the platform has a source guide, print it with `mint migrate --from <name>` (the list is at the end of this page). Detection signals and platform specifics for each route are in its guide.
+
+## Workflow
+
+1. **Inventory.** Build a complete list of source pages before converting anything. Record each one in `migration-manifest.json` (see `mint migrate --topic discovery`).
+2. **Mirror**, live-site route only. Download the raw source for every page into `mirror/`, one file per page. A repo or export is already the source. Convert from files, never from memory.
+3. **Convert.** Turn every page into `.mdx` with source-backed frontmatter, Mintlify components and root-absolute links (`--topic conversion`). Past about 50 pages, write a transformer script and re-run it after every rule fix instead of hand-editing output.
+4. **docs.json.** Build navigation from the source's own navigation data, add redirects for every URL that moves, and carry over only the chrome the source actually shows (`--topic navigation`).
+5. **API reference**, only if the source has one (`--topic api`).
+6. **Changelog**, only if the source has one (`--topic changelog`).
+7. **Verify.** Run `mint validate` and `mint broken-links`, run the content sweeps, and reconcile the manifest (`--topic verify`).
+8. **Report** to the user (below).
+
+## Rules
+
+- **Keep every page.** Nothing in the inventory is skipped silently. Each page ends as `done`, `excluded` (with a reason, such as a sitemap entry that 404s everywhere) or `blocked` (with a reason and a next step).
+- **Never invent content.** Every word on every page comes from the source. Do not summarize, rewrite, pad or add introductions.
+- **Never invent frontmatter.** `title`, `sidebarTitle`, `description` and `icon` all render visibly. Copy them from the source or leave them out.
+- **Mirror the source navigation.** Same tabs, groups, order, labels and nesting depth. Do not reorganize unless the user asks.
+- **Preserve URLs.** Keep source paths where possible. Every URL that changes gets a redirect (`mint migrate --topic navigation`, Redirects).
+- **Use Mintlify components** where the source has a real equivalent (callouts, steps, tabs, cards, accordions, code groups, API fields). Leave ambiguous structure as plain markdown. Catalog: https://www.mintlify.com/docs/components/index.md
+- **Download assets.** Images and files live in the repo, not hotlinked from the old site.
+- **Never fix a finding by deleting content.** If a page will not parse, fix the conversion.
+- **Report what you could not carry over.** Anything dropped, approximated or blocked goes in the final report.
+
+## Done means
+
+- `mint validate` passes with no errors.
+- `mint broken-links` reports nothing.
+- Every manifest row is `done`, `excluded` or `blocked` (discovered = done + excluded + blocked), and every `blocked` row is in the report.
+- Every `.mdx` file is in `docs.json` navigation and every navigation entry has a file.
+- Every source URL resolves on the new site, directly or through a redirect.
+
+Reference: https://www.mintlify.com/docs/cli/commands.md
+
+## Report
+
+Finish with a short report to the user:
+
+- Counts of manifest rows: discovered, done, excluded, blocked.
+- Every excluded or blocked page with its reason.
+- Everything dropped or approximated: custom components with no equivalent, interactive widgets, embeds, search or analytics config, versioning, localization, theme details. A custom-designed homepage or landing page (hero, bespoke layout) is converted as content and reported, not rebuilt with custom code.
+- Redirects added.
+- Anything that needs the user's input, such as an export for gated content or a decision about versions.
+
+Delete `mirror/` and any transformer scripts only if the user asks; keep `migration-manifest.json` until they have reviewed the report.

package/migrate/sources/confluence.md

@@ -0,0 +1,120 @@
+# Confluence
+
+Confluence Cloud and Data Center spaces. Content is usually behind login, so the customer exports the space and you work on the export locally. The old site stays on Confluence, so you produce a route table instead of redirects.
+
+## Detect
+
+- Cloud URLs: `https://<site>.atlassian.net/wiki/spaces/<KEY>/pages/<pageId>/<Title>`; short links `/wiki/x/<code>`.
+- Data Center URLs: `/display/<KEY>/<Page+Title>`, `/pages/viewpage.action?pageId=<id>`, short links `/x/<code>`.
+- An XML export ZIP contains `entities.xml`; an HTML export ZIP contains `index.html` and an `attachments/` folder.
+- Page bodies contain `<ac:structured-macro ac:name="...">` (storage format) or Confluence panel classes (HTML export).
+
+## Get the source
+
+Mintlify's guide for this platform: https://www.mintlify.com/docs/help-center/migrate-from-confluence.md
+
+### From the repo
+
+None; use an export.
+
+### From an export
+
+One export per space. Formats and menus: https://support.atlassian.com/confluence-cloud/docs/export-content-to-word-pdf-html-and-xml/ (Cloud) and https://confluence.atlassian.com/doc/export-content-to-word-pdf-html-and-xml-139475.html (Data Center).
+
+| Export   | Who can run it                                                     | What you get                                                                                                                        |
+| -------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| XML      | Cloud: space admin. Data Center: Export Space permission (Back up) | `entities.xml` with every page's storage-format body, parent and position, plus attachments. Preferred.                             |
+| HTML     | Same as XML                                                        | Rendered HTML per page, `index.html` with the space tree, attachments in per-page-id folders. Flatter: macros are already rendered. |
+| PDF/Word | Any viewer                                                         | Do not use; follow `mint migrate --from pdf` only if nothing else is available.                                                     |
+
+The HTML export omits blog posts and comments; ask whether blogs are in scope. Comments are not migrated.
+
+**XML export.** Parse `entities.xml` as XML; never regex it. It is an object dump: `Page` objects (title, `parent`, `position`, `space`), `BodyContent` objects (the storage-format body, linked to its page), and `Attachment` objects (file name, owning page). It also holds historical versions, drafts and trashed pages: keep only the current version of each page (older versions are listed under the current page's `historicalVersions`). Object model notes: https://confluence.atlassian.com/confkb/use-space-site-xml-export-entities-xml-to-find-confluence-objects-1283686755.html
+
+**HTML export.** Read the space tree from `index.html` and each page's breadcrumbs. Per-page file names and wrapper markup vary by version; inspect a few files and inventory every distinct `class` before writing the transformer.
+
+Split the export into one storage-format (XML export) or HTML (HTML export) file per page, named by page id.
+
+### From the live site
+
+Not covered yet. Use an export.
+
+## Config → docs.json
+
+A space has almost no site chrome to carry over.
+
+| Confluence                                | docs.json                                                          |
+| ----------------------------------------- | ------------------------------------------------------------------ |
+| Space name                                | `name`                                                             |
+| Space logo                                | `logo` (ask the customer for a light/dark logo)                    |
+| Space key                                 | none; used only in the route table                                 |
+| Several spaces migrated together          | `navigation.tabs` or `navigation.products`, one per space          |
+| Space home page                           | first page of the first group                                      |
+| Labels                                    | drop and report (or `keywords` if the customer wants search terms) |
+| Page restrictions, space permissions      | drop and report                                                    |
+| Space theme, look and feel                | drop and report                                                    |
+| Blog posts, comments, likes, page history | drop and report                                                    |
+
+## Navigation
+
+Build the tree from page `parent` and `position` (XML) or from `index.html` (HTML). Order siblings by `position`; where it is empty, take the order from the rendered page tree.
+
+- The space home page is the root; its children become top-level groups or pages.
+- A page with children becomes a nested group whose first page is the parent page itself.
+- Keep titles verbatim as labels. Confluence trees are often deep; keep the depth and tell the customer if it exceeds what reads well, rather than flattening.
+- Pages whose only content is a `children` macro become the group's first page with that list rendered as links.
+
+## Content conversion
+
+Storage format is XHTML with `ac:` and `ri:` elements. Convert with an XML/HTML parser, not regex.
+
+| Storage format                                                | Mintlify                                                                                                           |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `info` macro                                                  | `<Info>`                                                                                                           |
+| `tip` macro                                                   | `<Tip>`                                                                                                            |
+| `note` macro (renders as a yellow caution panel)              | `<Warning>`                                                                                                        |
+| `warning` macro (renders red)                                 | `<Danger>`                                                                                                         |
+| `title` parameter on the above                                | bold first line (`mint migrate --topic conversion`, Components)                                                    |
+| `panel` macro                                                 | plain content under its `title` in bold; colors dropped                                                            |
+| `code` macro: `<ac:plain-text-body><![CDATA[...]]>`           | fence; `language`, `title` → title, `linenumbers` → `lines`, `collapse` → `expandable`                             |
+| `noformat` macro                                              | fence without a language                                                                                           |
+| `expand` macro                                                | `<Accordion title="...">`; title from the unnamed parameter, else "Click here to expand..." as shown on the source |
+| `status` macro                                                | `<Badge color="...">title</Badge>`; Grey/Red/Yellow/Green/Blue → gray/red/yellow/green/blue                        |
+| `toc` macro                                                   | drop                                                                                                               |
+| `children` macro                                              | list of links to the child pages, generated from the tree                                                          |
+| `excerpt` macro                                               | its body inline                                                                                                    |
+| `excerpt-include`, `include` macros                           | snippet of the source page's excerpt or body (`mint migrate --topic conversion`, Reusable content)                 |
+| `anchor` macro                                                | drop; repoint links that target it to the nearest heading                                                          |
+| `jira` macro                                                  | link to each issue key; JQL tables dropped and reported                                                            |
+| `drawio`, `gliffy` macros                                     | image of the diagram (see Assets); report                                                                          |
+| `<ac:link><ri:page ri:content-title="X">`                     | root-absolute link to page X, resolved by title within the space                                                   |
+| `<ac:link><ri:attachment ri:filename>`                        | link to the copied file                                                                                            |
+| `<ac:image><ri:attachment ri:filename>` / `<ri:url ri:value>` | image with alt from `ac:alt` or the file name                                                                      |
+| `<ac:task-list>`                                              | list; prefix each item with its `ac:task-status`                                                                   |
+| `<ac:emoticon ac:name>`                                       | the matching Unicode emoji or drop                                                                                 |
+| `<ac:layout>`, `<ac:layout-section>`, `<ac:layout-cell>`      | unwrap; content in reading order                                                                                   |
+| User mentions (`<ri:user>`)                                   | the user's display name if the customer approves, else drop                                                        |
+| Other macros (third-party apps, `ac:adf-extension`)           | list in the report with page ids                                                                                   |
+
+Count every distinct `ac:name` (`mint migrate --topic conversion`). Confluence tables with merged cells (`rowspan`, `colspan`) and nested tables do not fit markdown tables; keep them as HTML tables made MDX-safe.
+
+Links by title resolve through a title → path index (`mint migrate --topic conversion`, Links). Links with `ri:space-key` pointing to another space resolve only if that space is migrated too.
+
+## Assets
+
+- XML export: attachments sit in the export's attachments folder keyed by page id and attachment id; map each to its file name through the `Attachment` objects in `entities.xml`. Take the latest version only.
+- HTML export: attachments are in per-page-id folders under `attachments/`.
+- Copy to `images/<page-path>/` (images) or a downloads folder (other files) and rewrite references.
+- draw.io: the macro's `diagramName` names an attachment on the same page. Use an exported PNG or SVG of the diagram if one is attached; otherwise ask the customer to export each diagram as an image. Gliffy works the same way. Never redraw a diagram.
+
+## URLs and redirects
+
+Old URLs stay on Confluence, so `redirects` cannot catch them. Produce `route-table.csv` next to the manifest: `page_id, old_url, new_path, title`. Build `old_url` from the page id in the Cloud or Data Center pattern above. The customer can use it to update links elsewhere or archive the space with pointers. Choose new paths from slugified titles nested under the parent's path, and record them in the manifest.
+
+## Known gaps
+
+- Page restrictions and space permissions.
+- Third-party app macros, Jira query tables, live `children` listings, `contentbylabel` and similar dynamic macros: static at best.
+- Comments, inline comments, page history, likes, blog posts.
+- Short links (`/x/<code>`) are not in the route table unless the customer provides them.
+- Diagrams without an image export.

package/migrate/sources/docsify.md

@@ -0,0 +1,128 @@
+# Docsify
+
+No build step. One `index.html` sets `window.$docsify = {...}` and loads Docsify plus plugin `<script>`s; the browser fetches each page's raw Markdown and renders it. Navigation is Markdown (`_sidebar.md`, `_navbar.md`).
+
+## Detect
+
+- An `index.html` with an inline `window.$docsify = {` and a `<script src=".../docsify...">`, usually in `docs/`. That folder is the content root.
+- `_sidebar.md`, `_navbar.md`, `_coverpage.md`, `.nojekyll`, `README.md` beside it; `docsify-cli` in `package.json` or `docsify serve` in scripts.
+- Live site: URLs of the form `/#/page`, and `<site>/README.md` returns raw Markdown.
+- `index.html` with `$docsify` wins. A GitHub wiki (`_Sidebar.md`, `Home.md`, no `index.html`) is not Docsify.
+
+## Get the source
+
+### From the repo
+
+- Read all of `index.html` first. The `$docsify` object decides which files are nav (`loadSidebar`, `loadNavbar`, `coverpage` can name other files), which file is home (`homepage`, default `README.md`), and where content comes from (`basePath`, `alias`). Every `<script src>` is a plugin to map.
+- Every `.md` under the content root is a candidate page; files only reached through `:include` are partials, not pages.
+- Nested sidebars: each folder may have its own `_sidebar.md`/`_navbar.md`; Docsify falls back to the parent folder's file. Collect all of them.
+- Locales are plain subfolders (`zh-cn/README.md`, `zh-cn/guide.md`), usually linked from `_navbar.md`.
+- Remote content: a `homepage`, `basePath` or `alias` pointing at `https://raw.githubusercontent.com/...` means the page lives in another repo. Vendor a copy and report it.
+
+### From an export
+
+None; the site is served from the repo files.
+
+### From the live site
+
+Docsify serves the raw files, so fetch them directly. Route `/#/guide` → `<site><basePath>guide.md`; `/#/folder/` → `folder/README.md`; nav from `<site>/_sidebar.md` and `<site>/_navbar.md`. Respect `basePath` and `ext` from the live `index.html`.
+
+## Config → docs.json
+
+| Docsify                                                                                                                                                                                                                                        | docs.json                                                                       |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `name` (strip HTML; `true` = `<title>` of `index.html`)                                                                                                                                                                                        | `name`                                                                          |
+| `<meta name="description">` in `index.html`                                                                                                                                                                                                    | `description`                                                                   |
+| `logo`                                                                                                                                                                                                                                         | `logo`                                                                          |
+| `nameLink`                                                                                                                                                                                                                                     | `logo.href` (per-locale objects: drop and report)                               |
+| `<link rel="icon">` in `index.html`                                                                                                                                                                                                            | `favicon`                                                                       |
+| `themeColor` (deprecated) or `--theme-color` CSS variable                                                                                                                                                                                      | `colors.primary`                                                                |
+| `repo`                                                                                                                                                                                                                                         | `navbar.links` entry with `type: "github"`                                      |
+| `_navbar.md`                                                                                                                                                                                                                                   | see Navigation                                                                  |
+| `formatUpdated`, `{docsify-updated}`                                                                                                                                                                                                           | `metadata.timestamp: true` only if the user wants dates; delete the placeholder |
+| `notFoundPage`, `_404.md`                                                                                                                                                                                                                      | drop and report (`errors.404` holds only redirect/title/description)            |
+| `alias` local → local                                                                                                                                                                                                                          | `redirects`                                                                     |
+| `alias` to sidebar/navbar files (`'/.*/_sidebar.md'`)                                                                                                                                                                                          | drop                                                                            |
+| `routes` (virtual routes)                                                                                                                                                                                                                      | static string routes → pages; function routes → drop and report                 |
+| `fallbackLanguages`, `fallbackDefaultLanguage`                                                                                                                                                                                                 | drop and report                                                                 |
+| `loadSidebar`, `loadNavbar`, `coverpage`, `onlyCover`, `homepage`                                                                                                                                                                              | drop; use to locate files                                                       |
+| `routerMode`, `relativePath`, `basePath`, `ext`                                                                                                                                                                                                | drop; use to compute old URLs and resolve links                                 |
+| `subMaxLevel`, `maxLevel`, `auto2top`, `topMargin`, `mergeNavbar`, `externalLinkTarget`, `cornerExternalLinkTarget`, `collapseSidebarGroups`, `hideSidebar`, `sidebarPosition`, `keyBindings`, `requestHeaders`, `noEmoji`, `markdown` options | drop                                                                            |
+| `markdown.renderer` overrides                                                                                                                                                                                                                  | drop and report what they rendered                                              |
+| `executeScript`, `vueComponents`, `vueMounts`, `vueGlobalOptions`                                                                                                                                                                              | drop and report                                                                 |
+| Plugin `search`, `docsify-copy-code`, `zoom-image`, `docsify-pagination`                                                                                                                                                                       | drop (built into Mintlify)                                                      |
+| Plugin `gtag` with a `G-` id                                                                                                                                                                                                                   | `integrations.ga4.measurementId`                                                |
+| Plugin `ga` (`UA-` id)                                                                                                                                                                                                                         | drop and report (Universal Analytics no longer collects)                        |
+| Plugin `disqus`, `gitalk`, edit-on-github                                                                                                                                                                                                      | drop and report                                                                 |
+| Plugin `docsify-tabs`, mermaid renderer, math plugin                                                                                                                                                                                           | see Content conversion                                                          |
+| Theme CSS, custom stylesheets                                                                                                                                                                                                                  | drop and report                                                                 |
+
+## Navigation
+
+- `_sidebar.md` is a nested Markdown list. A list item with a link is a page; a list item with plain text and child items is a group header. Map: header → group, linked item → page path, nested list under a linked item → nested group with that page as `root`. Keep order and labels.
+- Label differs from the page H1 → `sidebarTitle`. Link title string (`[Guide](guide.md "Tab title")`) set only the browser tab title: drop and report.
+- Resolve link targets: strip `.md`, `README` → folder index file, `/` → home page. Links resolve from the content root unless `relativePath: true`.
+- External links in the sidebar → a page with frontmatter `title` + `url: <href>`, listed at that position.
+- A folder-level `_sidebar.md` replaces the sidebar for that folder: map that folder to its own tab with its own groups.
+- `_navbar.md`: top-level links to doc sections → `navigation.tabs`; a text item with a nested list → a tab with `menu` or, when the children are locales (`/`, `/zh-cn/`), `navigation.languages`; external links → `navbar.links`.
+- The home page (`README.md` or `homepage`) goes first. Pages not in any sidebar were reachable only by link (`mint migrate --topic navigation`, Structure rules).
+- `_sidebar.md`, `_navbar.md`, `_coverpage.md`, `_404.md` are not pages: do not convert them.
+
+## Content conversion
+
+Pages usually have no front matter (the `front-matter` plugin is optional). If content precedes the first H1, use the sidebar label as title (`mint migrate --topic conversion`, Frontmatter).
+
+| Docsify                                                                                         | Mintlify                                                                            |
+| ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `> [!NOTE]` / `[!TIP]` / `[!IMPORTANT]` / `[!WARNING]` / `[!CAUTION]`                           | `mint migrate --topic conversion`, GitHub alerts                                    |
+| `!> text` (legacy important)                                                                    | `<Info>`                                                                            |
+| `?> text` (legacy tip)                                                                          | `<Tip>`                                                                             |
+| `## Heading :id=custom-id`                                                                      | `mint migrate --topic conversion`, Heading IDs                                      |
+| `<!-- {docsify-ignore} -->`, `{docsify-ignore}`, `{docsify-ignore-all}` on headings             | delete                                                                              |
+| `[x](file.md ':include')` (Markdown)                                                            | `mint migrate --topic conversion`, Reusable content                                 |
+| `[x](file.js ':include :type=code')`, `:fragment=name`                                          | `mint migrate --topic conversion`, Code imports; fragments are `/// [name]` markers |
+| `:include` of `.html` / `:type=iframe`                                                          | `<iframe>` inside `<Frame>`                                                         |
+| `:include` of `.mp4`/`.ogg` / `.mp3`                                                            | `<video controls src>` / `<audio controls src>` with a root-relative path           |
+| `:include` of a remote URL or gist                                                              | vendor the content; report                                                          |
+| docsify-tabs `<!-- tabs:start -->`, `#### **Name**` or `<!-- tab:Name -->`, `<!-- tabs:end -->` | `<Tabs>` + `<Tab title="Name">`                                                     |
+| `<details><summary>T</summary>`                                                                 | `<Accordion title="T">`                                                             |
+| `[x](/path ':ignore')`                                                                          | plain link to that path (it pointed outside the docs)                               |
+| `[x](/path ':disabled')`                                                                        | plain text `x`                                                                      |
+| `':target=_blank'`, `':class=...'`, `':id=...'` on links                                        | drop the attribute string                                                           |
+| `![a](img.png ':size=WxH')` / `':size=N'`                                                       | `<img src="/img.png" alt="a" width="W" height="H" />`                               |
+| `![a](img.png ':no-zoom')`                                                                      | `<img ... noZoom />`                                                                |
+| `:shortcode:` emoji                                                                             | Unicode emoji, unless `noEmoji: true` (then leave literal)                          |
+| ` ```mermaid ` (custom renderer)                                                                | keep the fence                                                                      |
+| `$...$` / `$$...$$` from a math plugin                                                          | keep                                                                                |
+| Vue templates or `<script>` in pages                                                            | `mint migrate --topic conversion`, Components                                       |
+
+## Assets
+
+- Docsify serves every file in the content root at its path (`mint migrate --topic conversion`, Images and files).
+- Resolve each image path the way the live site did: open the rendered page and read the `<img src>` it produced, then map that to the new location. Do not assume `./`, `../` and `/` paths resolve from the content root.
+- `_media/` is the conventional asset folder; keep its name so paths stay stable.
+- Cover page background (`![](bg.png)` or `![color](#hex)` in `_coverpage.md`): drop and report.
+
+## URLs and redirects
+
+- Hash mode (default `routerMode: 'hash'`): every page is `/#/<path>`, folder index `/#/<folder>/`, home `/`. Heading anchors are `?id=<heading-id>` after the route (`/#/guide?id=install`).
+- Hash URLs cannot be redirected (`mint migrate --topic navigation`, Redirects). Tell the user: old links load the new site root. If they need old links to resolve, a client-side script that reads `location.hash` and rewrites `#/<path>?id=<x>` to `/<new-path>#<x>` is the only option; it lives outside `docs.json` (a custom `.js` file in the Mintlify content directory runs on every page). Do not add it without the user's approval.
+- History mode (`routerMode: 'history'`): URLs are real paths (`/guide`), so emit normal `redirects` for any path that changes. Anchors are still `?id=` and fall back to the page top (`mint migrate --topic navigation`, Redirects).
+- Pin `{#id}` on headings that old `?id=` links target, using the id Docsify rendered (read the heading `id` attributes on the live page, or the `:id=`).
+- The `homepage` file is the `/` page.
+- `alias` entries were routes too: redirect the alias path to the new page (history mode) or report it (hash mode).
+- Locales keep folder prefixes (`/zh-cn/...`).
+- `README.md` folder index files (`mint migrate --topic conversion`, Files).
+
+## Known gaps
+
+Report each that the site uses:
+
+- Hash-route URLs and `?id=` anchors (no server-side redirect).
+- Cover page layout and background, `onlyCover`.
+- Function `routes`, `alias` to remote content, `fallbackLanguages`.
+- Vue components, `executeScript` page scripts, custom `markdown` renderers.
+- Comment plugins (Disqus, Gitalk), Universal Analytics, third-party plugins without a mapping above.
+- Per-heading sidebar TOC control (`subMaxLevel`, `docsify-ignore`).
+- Link and image attributes dropped (`:target`, `:class`, `:id`).
+- Theme CSS and sidebar link title strings.

package/migrate/sources/document360.md

@@ -0,0 +1,117 @@
+# Document360
+
+Knowledge bases hosted by Document360. There is no source repo: content comes from a project export the customer runs, or from the public knowledge base site.
+
+## Detect
+
+- Rendered HTML loads images from `cdn.document360.io` and references Document360 throughout the markup.
+- Article URLs follow `/docs/<slug>`, optionally behind workspace and language segments (`/v2/docs/<slug>`, `/docs/en/<slug>`).
+- Callouts render as `<div class="infoBox">`, `warningBox`, `errorBox`, `successBox`.
+- An export ZIP contains per-article `.md`, `.html` or `.json` files and a media folder.
+
+## Get the source
+
+Mintlify's guide for this platform: https://www.mintlify.com/docs/migration/document360.md
+
+### From the repo
+
+None; content comes from a project export or the live site.
+
+### From an export
+
+The customer runs it in the portal: **Content tools > Import and export > Import and export project > Export project**. Steps: https://docs.document360.com/docs/exporting-your-document360-project-as-a-zip-file-json
+
+- Select **All** under "Include new or modified articles in"; the default date filter drops older articles.
+- Select every maintained workspace, language and category, and **Include media files** (otherwise images stay as hosted URLs).
+- Each new export overwrites the previous ZIP; download it as soon as it is ready.
+- File type depends on the editor and the export: a single-language export writes `.md` for Markdown-editor articles and `.html` for WYSIWYG and Advanced WYSIWYG articles; a multi-language export writes `.json` for every article. Handle all three.
+- Also ask for the **All articles** CSV export (title, category, status, dates, URL). Use it as the inventory and to reconcile the ZIP.
+
+The export does not include snippets, variables, glossary, custom pages, redirects, custom CSS/JS or API specs. Collect those from the live site or ask the customer for them.
+
+The Document360 API (`apihub.document360.io`, customer token) can list categories and articles if the customer prefers to script the export themselves; category responses contain only direct children, so recurse. https://apidocs.document360.com
+
+### From the live site
+
+For public knowledge bases, `/llms.txt` lists every published article and category page, and each article serves markdown at `<article-url>.md`. The sitemap URL is shown in the customer's SEO settings. Quirks (`mint migrate --topic discovery`, Mirror the raw source):
+
+- Strip the `> ## Documentation Index` blockquote after the frontmatter.
+- Its frontmatter (`title`, `slug`, `description`, `tags`, `canonical`, dates) is usable source metadata (`mint migrate --topic conversion`, Frontmatter).
+- Rendered callouts lose their type in `.md` output (only some become `> [!TIP]`-style blockquotes). Take the callout type from the rendered HTML class.
+
+Private and mixed-access content is only in the export (`mint migrate --topic discovery`, Gated content).
+
+## Config → docs.json
+
+| Document360                                      | docs.json                                              |
+| ------------------------------------------------ | ------------------------------------------------------ |
+| Project name                                     | `name`                                                 |
+| Logo (light/dark), favicon                       | `logo.light`, `logo.dark`, `favicon`                   |
+| Brand color                                      | `colors.primary`                                       |
+| Header and secondary navigation links            | `navbar.links`                                         |
+| Footer links                                     | `footer.links`                                         |
+| Workspaces used as versions                      | `navigation.versions`                                  |
+| Workspaces used as separate products             | `navigation.products` or `navigation.tabs`             |
+| Languages                                        | `navigation.languages` if the customer migrates them   |
+| Redirect rules                                   | `redirects`                                            |
+| Home page builder                                | an MDX home page with the same visible content; report |
+| Reader groups, private articles, SSO             | drop and report                                        |
+| Custom CSS / JavaScript, integrations, analytics | drop and report                                        |
+| Feedback, article ratings, search settings       | drop and report                                        |
+
+## Navigation
+
+Use the category tree from the export folder structure, the CSV `category` column, or the rendered sidebar.
+
+| Document360                        | Mintlify                                                         |
+| ---------------------------------- | ---------------------------------------------------------------- |
+| Workspace                          | version, product or tab (ask how readers use them)               |
+| Folder category (no URL)           | group                                                            |
+| Index category (URL, article list) | group whose first page is an overview with links to its articles |
+| Page category (URL, content)       | group whose first page is the category's content                 |
+| Subcategory                        | nested group                                                     |
+| Article, sub-article               | page                                                             |
+
+Take sidebar order from the rendered sidebar unless the export carries an explicit order field. Articles in draft status (CSV `status`) are not published; ask before migrating them.
+
+## Content conversion
+
+Document360 renders the article title as the H1; bodies start at H2. Do not add an H1.
+
+| Document360                                                | Mintlify                                                        |
+| ---------------------------------------------------------- | --------------------------------------------------------------- |
+| Info callout (`infoBox`)                                   | `<Info>`                                                        |
+| Warning callout (`warningBox`)                             | `<Warning>`                                                     |
+| Error callout (`errorBox`)                                 | `<Danger>`                                                      |
+| Success callout (`successBox`, `> [!TIP]` in `.md` output) | `<Check>`                                                       |
+| Callout bold first line                                    | bold first line (`mint migrate --topic conversion`, Components) |
+| `{{snippet.<code>}}`                                       | snippet (`mint migrate --topic conversion`, Reusable content)   |
+| `{{variable.<code>}}`                                      | `{{<code>}}` (`mint migrate --topic conversion`, Template tags) |
+| `{{glossary.<term>}}`                                      | `<Tooltip tip="<definition>">term</Tooltip>`                    |
+| Code block with a heading                                  | fence with `title`                                              |
+| Tabs, accordions                                           | `<Tabs>`, `<AccordionGroup>`                                    |
+| Step-by-step guide                                         | `<Steps>`                                                       |
+| Private notes                                              | remove; list them in the report                                 |
+| Embedded video, iframe                                     | supported embed, else link                                      |
+| Decision trees, forms                                      | static content or link; report                                  |
+
+Merge codes are case-sensitive. Snippet and variable content is not in the export: get each value from the customer or from a rendered page that uses it.
+
+WYSIWYG `.html` articles carry editor wrapper markup; count every distinct `class` value (`mint migrate --topic conversion`).
+
+## Assets
+
+With **Include media files**, images ship in the ZIP; rewrite each reference to its local copy under `images/`. Without it, they are `cdn.document360.io` URLs (`mint migrate --topic conversion`, Images and files). Also check Drive file links (downloadable PDFs and attachments), which may point at Document360 storage.
+
+## URLs and redirects
+
+- Build the old URL list from the CSV `URL` column plus `llms.txt` or the sitemap; include Index and Page category URLs.
+- Keep the article slug; it is the stable part of the URL. Add redirects for workspace and language prefixes you drop or rename, and for each article whose path changes.
+- Folder categories have no URL and need no redirect.
+
+## Known gaps
+
+- Home page builder layouts and custom pages.
+- Reader groups and private-content rules.
+- API documentation: specs are imported (file, URL or CLI) and not in the export. Ask for the spec file, then follow `mint migrate --topic api`; do not convert the generated endpoint articles.
+- Decision trees, article templates, related-articles widgets, feedback and ratings.