Add migration guides

components/banner.mdx

@@ -27,7 +27,7 @@ To add a banner, use the `banner` property in your `docs.json`:
 
   ```json Critical notices wrap
   "banner": {
-    "content": "**Action required:** Rotate your API keys before January 1. [Migration guide](/migration)",
+    "content": "**Action required:** Rotate your API keys before January 1. [Migration guide](/migration/index)",
     "type": "critical",
     "dismissible": true
   }
@@ -129,4 +129,4 @@ Configure different banner content for each language in your documentation. Defi
 Banners follow a priority order when determining which content to display:
 
 1. **Language-specific banner**: If the current language has a `banner` configuration, it takes priority.
-2. **Global banner**: If no language-specific banner exists, display the global `banner`.
+2. **Global banner**: If no language-specific banner exists, display the global `banner`.

docs.json

@@ -41,7 +41,19 @@
                       "cli/commands"
                     ]
                   },
-                  "migration"
+                  {
+                    "group": "Migrate to Mintlify",
+                    "root": "migration/index",
+                    "pages": [
+                      "migration/docusaurus",
+                      "migration/readme",
+                      "migration/gitbook",
+                      "migration/fern",
+                      "migration/document360",
+                      "migration/manual",
+                      "migration/go-live"
+                    ]
+                  }
                 ]
               },
               {

es/components/banner.mdx

@@ -27,7 +27,7 @@ Para añadir un banner, usa la propiedad `banner` en tu `docs.json`:
 
   ```json Critical notices wrap
   "banner": {
-    "content": "**Acción requerida:** rota tus claves de API antes del 1 de enero. [Guía de migración](/migration)",
+    "content": "**Acción requerida:** rota tus claves de API antes del 1 de enero. [Guía de migración](/migration/index)",
     "type": "critical",
     "dismissible": true
   }

fr/components/banner.mdx

@@ -27,7 +27,7 @@ Pour ajouter une bannière, utilisez la propriété `banner` dans votre `docs.js
 
   ```json Critical notices wrap
   "banner": {
-    "content": "**Action requise :** effectuez la rotation de vos clés d'API avant le 1er janvier. [Guide de migration](/migration)",
+    "content": "**Action requise :** effectuez la rotation de vos clés d'API avant le 1er janvier. [Guide de migration](/migration/index)",
     "type": "critical",
     "dismissible": true
   }

migration/document360.mdx

@@ -0,0 +1,141 @@
+---
+title: "Migrate from Document360"
+description: "Migrate Document360 workspaces, languages, articles, categories, media, reusable content, and API references to Mintlify."
+keywords: ["Document360 migration", "Document360 to Mintlify", "knowledge base export", "project ZIP"]
+---
+
+Export a Document360 project as a ZIP, then convert its workspaces, languages, categories, and articles into a Mintlify project. Use the Document360 API and published site to audit content that the export may not represent completely.
+
+<Note>
+  The Mintlify scraper does not currently support Document360.
+</Note>
+
+## Create a migration snapshot
+
+Before exporting, create a named manual backup in Document360. Navigate to **Settings > Knowledge base portal > Backup & Restore**. Download a project export for the migration itself.
+
+In Document 360, navigate to **Content tools > Import and export > Import and export project**.
+
+<Note>
+  Export each workspace and language deliberately. A single-language export can contain Markdown for articles created in the Markdown editor and HTML for WYSIWYG articles. A multi-language export uses JSON regardless of editor type.
+</Note>
+
+1. Click **Export project**.
+2. Include articles from **All** dates.
+3. Select every maintained workspace, language, category, and subcategory.
+4. Include media files.
+5. Download the ZIP as soon as it is ready. A later export replaces the previous file shown in the portal.
+6. Export the **All articles** list as CSV. This list of metadata is useful for reconciling titles, publication status, dates, categories, and URLs.
+
+<Tip>
+  Keep the exported ZIP and CSV unchanged as source snapshots. Make copies for any conversion work you do while migrating.
+</Tip>
+
+## Inventory content outside the export
+
+Record project features that require separate migration work.
+
+- Homepage Builder content and navigation
+- Custom pages linked from the header, footer, or sidebar
+- Snippets, variables, glossary terms, and templates
+- Custom CSS, JavaScript, and integrations
+- Reader groups, roles, SSO, and private-content rules
+- Redirect rules and custom domains
+- Analytics, feedback, forms, and search configuration
+- API reference source specifications
+- Drive files, decision trees, and embedded content
+
+Use the published sitemap and the Document360 Customer API to compare the export with public and private content. The API is particularly useful when you need to traverse category metadata or recover fields that are difficult to derive from exported files.
+
+## Recreate navigation
+
+Map the Document360 hierarchy to `docs.json`.
+
+| Document360 | Mintlify |
+| --- | --- |
+| Workspace | [Version](/organize/navigation#versions), [product](/organize/navigation#products), [tab](/organize/navigation#tabs), or separate navigation tree |
+| Language | [Language navigation element](/organize/navigation#languages) |
+| Folder category | Navigation group |
+| Index or page category | Group with a `root` page |
+| Article or sub-article | Page or nested group |
+| Custom page | Standard MDX page or custom layout |
+| Header and footer navigation | Navbar links, anchors, menus, or footer links |
+
+Choose the mapping for workspaces based on how your readers use them. A workspace named `v1` is usually a version, while separate product knowledge bases may map better to products or tabs. See [Navigation](/organize/navigation) for more information on Mintlify navigation elements.
+
+Document360 category API responses include only direct children. If you use the API to build an inventory, request each child category recursively and retrieve content separately for index and page categories.
+
+## Convert article content
+
+Copy Markdown articles into `.mdx` files and convert exported HTML or JSON to MDX. Add frontmatter with at least a `title`, and retain descriptions, keywords, publication metadata, and canonical routes where useful.
+
+Review each editor's platform-specific output:
+
+| Document360 content | Mintlify treatment |
+| --- | --- |
+| Info, warning, and error callouts | Convert to [Mintlify callouts](/components/callouts). |
+| Tabs and accordions | Convert to [`Tabs`](/components/tabs) or [`AccordionGroup`](/components/accordions). |
+| Step-by-step guides | Convert to [`Steps`](/components/steps). |
+| Code tabs | Convert to a [`CodeGroup`](/components/code-groups). |
+| Private notes | Remove them or move internal guidance outside the public docs. |
+| Article templates | Convert repeated structure into starter files or reusable snippets. |
+| Embedded forms, videos, and widgets | Replace with supported embeds, links, or custom components. |
+| Decision trees | Rebuild as guides, branching links, or an appropriate interactive experience. |
+
+Both Document360 and Mintlify render the `title` frontmatter as the page H1, so page bodies begin at H2. Do not add a duplicate H1 during conversion.
+
+## Convert reusable content
+
+Inventory variables, snippets, glossary terms, and every usage before replacing them.
+
+- Convert reusable content blocks to [Mintlify snippets](/create/reusable-snippets).
+- Replace variables with explicit text, generated content, or another maintainable source of truth.
+- Replace glossary tooltips with links or supported tooltip components.
+- Preserve language-specific variations rather than consolidating text that only appears identical in one locale.
+
+Check the rendered source site as well as the export to determine whether each reusable item appears as expanded content or as a platform-specific reference.
+
+## Migrate API references
+
+Download the original OpenAPI file from each Document360 API reference category or retrieve it from the system that syncs the specification.
+
+1. Add the original specification to the Mintlify repository.
+2. Configure [OpenAPI-generated pages](/api-playground/openapi-setup).
+3. Preserve custom endpoint descriptions or examples that editors added after import.
+4. Compare tag hierarchy, endpoint order, servers, authentication, examples, and code samples.
+5. Replace any Document360 resync automation with the Mintlify deployment workflow.
+
+Do not convert generated endpoint articles when the source specification is available.
+
+## Migrate media and files
+
+Include media in the project export and copy owned files into your Mintlify project repository. Check Document360 Drive links, thumbnails, SVGs, downloadable files, CSS background images, and content embedded from external services.
+
+Update asset paths after reorganizing pages. Do not leave required production assets on Document360 domains unless you intend to keep that hosting active.
+
+## Preserve URLs and access rules
+
+Document360 routes can include workspace and language slugs plus category and article slugs. Build a URL map from the published sitemap and the exported article CSV, then add [redirects](/create/redirects) for every changed route.
+
+Recreate private documentation with [authentication and access control](/deploy/authentication-setup). Create reader groups and role-based restrictions that mirror your previous access control setup. Test as each group before you publish your site.
+
+## Review your migration
+
+- Check that the exported ZIP, CSV, API inventory, and published sitemap align.
+- Compare every workspace, language, category, subcategory, article, and custom page.
+- Search for unconverted HTML, snippets, variables, private notes, and widget embeds.
+- Verify that API reference content comes from your maintained source specification.
+- Test media, downloads, language switching, private access, and redirects.
+- Complete the [go-live checklist](/migration/go-live).
+
+## Document360 references
+
+- [Export a project ZIP](https://docs.document360.com/help/docs/exporting-your-document360-project-as-a-zip-file-json)
+- [Export all articles](https://docs.document360.com/help/docs/export-bulk-operations)
+- [Backup and restore](https://docs.document360.com/help/docs/backup-restore)
+- [Workspaces and languages](https://docs.document360.com/docs/workspaces-languages)
+- [Markdown editor](https://docs.document360.com/docs/markdown-editor)
+- [Snippets](https://docs.document360.com/help/docs/snippets)
+- [Manage API references](https://docs.document360.com/docs/manage-api-references)
+- [Category API](https://apidocs.document360.com/v2-api/apidocs/get-category)
+- [Custom pages](https://docs.document360.com/docs/custom-pages)

migration/docusaurus.mdx

@@ -0,0 +1,158 @@
+---
+title: "Migrate from Docusaurus"
+description: "Migrate Docusaurus documentation to Mintlify, including MDX pages, sidebars, versions, localized content, assets, and custom components."
+keywords: ["Docusaurus migration", "Docusaurus to Mintlify", "sidebars.js", "versioned_docs"]
+---
+
+Migrate a public Docusaurus 2 or 3 site with the Mintlify scraper. If you need more precise control over versions, localized content, or custom React components, migrate from your source repository.
+
+## Choose a method
+
+| Method | Use it when |
+| --- | --- |
+| Scraper | Your complete documentation site is public and most content uses standard Docusaurus components. |
+| Source migration | Your site is private or uses versioning, localization, custom plugins, custom React components, or unpublished pages. |
+
+For complex sites, combine both methods. Scrape your public site to create an initial `docs.json` and convert components, then compare the result with the source repository for missing content.
+
+## Migrate a public site
+
+<Warning>
+  The scraper can overwrite existing files.
+
+  Run the scraper in an empty directory so it does not replace any existing files.
+</Warning>
+
+```bash
+mkdir mintlify-migration
+cd mintlify-migration
+npx @mintlify/scraping@latest section https://docs.example.com
+```
+
+If your Docusaurus documentation uses a route base path, filter to scrape that path:
+
+```bash
+npx @mintlify/scraping@latest section https://example.com --filter=/docs
+```
+
+The scraper detects Docusaurus, expands its sidebar, downloads reachable images, converts common rendered components to Mintlify components, and creates a `docs.json` from the published navigation.
+
+After the scraper finishes, compare the generated Mintlify navigation with your `sidebars.js`, `sidebars.ts`, or other Docusaurus navigation structure. Check for collapsed categories, external links, generated category index pages, and pages excluded from the published sidebar.
+
+## Migrate from source
+
+Copy the following source content into a separate migration branch or working directory.
+
+- Your configured docs content directory, which is `docs/` by default in Docusaurus
+- `sidebars.js`, `sidebars.ts`, or other sidebar configuration files
+- `docusaurus.config.js` or `docusaurus.config.ts`
+- `_category_.json`, `_category_.yml`, or `_category_.yaml` files
+- The `static/` directory and assets stored beside documentation pages
+- `versioned_docs/`, `versioned_sidebars/`, and `versions.json`
+- Localized docs below `i18n/<locale>/docusaurus-plugin-content-docs/<versionName>/`, such as `current/`
+- React components imported by MDX pages
+
+<Note>
+  Docusaurus can change its docs directory, route base path, sidebar generator, and included files in the docs plugin configuration. Depending on your configuration, your content may be in a different directory than `docs/`.
+</Note>
+
+Copy Markdown and MDX pages into your Mintlify project. Every page needs frontmatter with at least a `title`.
+
+```mdx Example frontmatter
+---
+title: "Get started"
+description: "Install the SDK and make your first request."
+---
+```
+
+## Recreate navigation
+
+Docusaurus sidebars are executable JavaScript or TypeScript, while Mintlify navigation is data in `docs.json`. Convert the resolved sidebar, not only its source text, if the sidebar uses functions or custom generators.
+
+| Docusaurus | Mintlify |
+| --- | --- |
+| `doc` item or doc ID | Page path in a `pages` array |
+| `category` | Nested group with `group` and `pages` |
+| Category linked to a doc | Group with a `root` page |
+| Generated category index | Create an overview page and use it as the group `root` |
+| `link` item | An anchor, tab, menu item, or page that links to the external destination |
+| Multiple sidebars | Separate tabs, anchors, products, or groups |
+| Autogenerated sidebar | Mirror the file hierarchy or list the generated order explicitly |
+
+Docusaurus uses the file hierarchy for autogenerated sidebars. Mintlify lets you organize navigation independently from file locations, so you do not need to rename pages solely to match the sidebar.
+
+## Convert Docusaurus MDX
+
+Standard Markdown usually works without changes. Review Docusaurus-specific syntax and imports.
+
+| Docusaurus source | Mintlify replacement |
+| --- | --- |
+| `import Tabs from '@theme/Tabs'` and `TabItem` | Remove the imports and use [`Tabs` and `Tab`](/components/tabs). |
+| `:::note`, `:::tip`, `:::info`, `:::warning`, `:::danger` | Use [`Note`, `Tip`, `Info`, `Warning`, or `Danger`](/components/callouts). |
+| `<details>` and `<summary>` | Use an [`Accordion`](/components/accordions). |
+| Tabbed code examples | Use a [`CodeGroup`](/components/code-groups) when every tab contains code. |
+| `@site/...` imports and theme components | Replace them with Mintlify components, snippets, or standard MDX. |
+| Custom Markdown plugin syntax | Convert the generated syntax or recreate the behavior in supported MDX. |
+| Swizzled theme components | Recreate the user-facing behavior with Mintlify settings or components. |
+
+Custom React components do not migrate automatically from your source repository. Determine whether each component is content, presentation, or application behavior.
+
+- Replace content patterns with a [Mintlify component](/components).
+- Convert repeated content to a [reusable snippet](/create/reusable-snippets).
+- Add a [React component](/customize/react-components) when you need an interaction that no built-in component provides.
+- Move full application pages outside the documentation site or rebuild them as [custom page layouts](/guides/custom-layouts).
+
+## Preserve routes and links
+
+Docusaurus combines the docs plugin `routeBasePath`, page frontmatter `slug`, version, and locale to create a URL. Create an inventory from the published sitemap rather than inferring every URL from filenames.
+
+When you rename or reorganize a page, add its old published path to [redirects](/create/redirects). Test links with and without the former route base path, for example `/docs/getting-started` and `/getting-started`.
+
+Review explicit Docusaurus heading IDs such as:
+
+```mdx
+## Configure the client {/* #configure-client */}
+```
+
+Convert them to Mintlify's custom heading ID syntax when you must preserve inbound anchor links:
+
+```mdx
+## Configure the client {#configure-client}
+```
+
+## Migrate assets
+
+Docusaurus supports global assets in `static/` and assets stored beside versioned pages. Copy both kinds into the Mintlify repository.
+
+- A Docusaurus file at `static/img/logo.png` is normally published as `/img/logo.png`. Preserve that public path or update every reference.
+- Resolve `@site/static/...` imports before removing Docusaurus imports.
+- Keep collocated versioned assets with the correct version or move them to version-specific asset directories.
+- Check CSS background images and React component imports, which a Markdown-only inventory can miss.
+
+## Migrate versions and languages
+
+Docusaurus stores frozen versions under `versioned_docs/version-<name>` and their navigation under `versioned_sidebars/`. Map each maintained version to a Mintlify [version](/organize/navigation#versions). Decide whether `current`, the latest released version, or another version should be the default.
+
+Map Docusaurus locale directories to Mintlify [language navigation](/organize/navigation#languages). Preserve the locale prefix in redirects when the old site used paths such as `/fr/docs/...`.
+
+## Migrate API documentation
+
+Locate OpenAPI or AsyncAPI files referenced by plugins, custom pages, or build scripts. Add the original specification to the Mintlify repository and configure [OpenAPI-generated pages](/api-playground/openapi-setup). Do not migrate rendered endpoint HTML when the source specification is available.
+
+## Review your migration
+
+- Compare every sidebar and sitemap URL with the generated Mintlify navigation.
+- Search for remaining `@theme`, `@site`, `:::`, `DocCardList`, `useDocusaurusContext`, and custom plugin imports.
+- Preview every maintained version and language.
+- Verify relative links and both global and collocated assets.
+- Test redirects for explicit slugs and the previous route base path.
+- Complete the [go-live checklist](/migration/go-live).
+
+## Docusaurus references
+
+- [Docs plugin configuration](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs)
+- [Sidebars](https://docusaurus.io/docs/sidebar)
+- [Versioning](https://docusaurus.io/docs/versioning)
+- [Internationalization](https://docusaurus.io/docs/i18n/introduction)
+- [Static assets](https://docusaurus.io/docs/static-assets)
+- [Heading IDs](https://docusaurus.io/docs/markdown-features/toc#heading-ids)