From 92cd044410f5d558c79240e31c80ee9cc52b32a6 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Wed, 12 Aug 2026 11:11:55 -0700 Subject: [PATCH 01/16] docs: add platform migration guides --- docs.json | 12 +- migration.mdx | 237 ++++++++++----------------------------- migration/docusaurus.mdx | 155 +++++++++++++++++++++++++ migration/gitbook.mdx | 159 ++++++++++++++++++++++++++ migration/go-live.mdx | 101 +++++++++++++++++ migration/manual.mdx | 153 +++++++++++++++++++++++++ migration/readme.mdx | 158 ++++++++++++++++++++++++++ 7 files changed, 798 insertions(+), 177 deletions(-) create mode 100644 migration/docusaurus.mdx create mode 100644 migration/gitbook.mdx create mode 100644 migration/go-live.mdx create mode 100644 migration/manual.mdx create mode 100644 migration/readme.mdx diff --git a/docs.json b/docs.json index 652ac7d90c..0fabb11df1 100644 --- a/docs.json +++ b/docs.json @@ -41,7 +41,17 @@ "cli/commands" ] }, - "migration" + { + "group": "Migrate to Mintlify", + "root": "migration", + "pages": [ + "migration/docusaurus", + "migration/readme", + "migration/gitbook", + "migration/manual", + "migration/go-live" + ] + } ] }, { diff --git a/migration.mdx b/migration.mdx index 3f98bef049..4e9f9f6fde 100644 --- a/migration.mdx +++ b/migration.mdx @@ -1,204 +1,89 @@ --- title: "Migrate to Mintlify" -description: "Migrate your documentation to Mintlify from Docusaurus, ReadMe, GitBook, or another platform with step-by-step instructions and CLI tooling." -keywords: ["migration", "Docusaurus", "ReadMe", "import"] +description: "Choose a migration path for moving documentation from Docusaurus, ReadMe, GitBook, or another platform to Mintlify." +keywords: ["migration", "Docusaurus", "ReadMe", "GitBook", "import"] --- -This guide helps you move your existing documentation to Mintlify. Choose automated migration for supported platforms or manual migration for complete control over the process. +Move your existing documentation to Mintlify with an automated scraper, an export from your current platform, or a manual migration. The best path depends on whether your site is public, whether you can access its source files, and which platform-specific features you use. + + + + Migrate Markdown or MDX, sidebars, versioned docs, localized content, and custom React components. + + + Migrate guides, API reference content, recipes, custom pages, versions, and reusable content. + + + Export spaces with Git Sync or scrape a public site, then convert GitBook blocks and navigation. + + + +## Choose a migration path + +| Your documentation | Recommended path | +| --- | --- | +| Public Docusaurus, ReadMe, or GitBook site | Use the scraper to convert rendered pages, common components, images, and navigation. | +| Private site with Markdown or MDX source | Copy the source into a new Mintlify project and convert platform-specific syntax. | +| ReadMe project with dashboard access | Export the project files to preserve OpenAPI files and content that might not be public. | +| GitBook space with organization access | Export to an empty GitHub or GitLab repository with Git Sync. | +| Another platform or mixed content sources | Follow the [manual migration guide](/migration/manual). | -## Choose your migration path - -* If you currently use Docusaurus or ReadMe -> **Automated migration** -* If you have a public GitHub repository -> **Auto-generated migration** -* If you are migrating from any other platform -> **Manual migration** - - - - -Migrate your documentation using the [@mintlify/scraping package](https://www.npmjs.com/package/@mintlify/scraping). The package scrapes your content and converts it to use Mintlify components. - -### Supported platforms - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -} horizontal /> - - -} horizontal /> - - -If you host your documentation on another platform, see the manual migration steps. - -### Install the scraper - -Install the `@mintlify/scraping` package to get started. - -```bash -npm install @mintlify/scraping@latest -g -``` + + Prefer source files or a native export when you need private pages, multiple versions, reusable content, or the original OpenAPI specification. A scraper can only convert content that it can reach on the published site. + -### Scrape pages and sections +## Before you migrate -The migration tool automatically detects your documentation platform and converts your content. It saves prepared files locally in the `./docs` folder by default. +Inventory the source site before changing any content. Record: -For large documentation sites, migrate smaller sections one at a time rather than the entire site at once. +- Every published and private page +- Navigation, products, versions, and languages +- Existing page URLs and redirects +- OpenAPI or AsyncAPI specifications +- Images, videos, and downloadable files +- Reusable content, variables, and custom components +- Authentication, analytics, custom scripts, and integrations -**Migrate entire sections:** -```bash -mintlify-scrape section https://your-docs-site.com/docs -``` +Choose a short content freeze or record a cutoff time. Changes made in the source platform after the export or scrape must be migrated separately. -**Migrate single pages:** -```bash -mintlify-scrape page https://your-docs-site.com/docs/getting-started -``` +## Use the automated scraper -**Filter specific paths:** +The [`@mintlify/scraping`](https://www.npmjs.com/package/@mintlify/scraping) package detects supported documentation platforms and converts their rendered content to Mintlify MDX. -Use the `--filter` (or `-f`) option to scrape only URLs matching a specific path prefix. + + Run the scraper in an empty working directory. A site scrape writes pages, downloaded assets, and a new `docs.json` into the current directory. + ```bash -mintlify-scrape section https://your-docs-site.com --filter=/docs +mkdir mintlify-migration +cd mintlify-migration +npx @mintlify/scraping@latest section https://docs.example.com ``` -The filter matches the specified path and all nested paths. For example, `--filter=/docs` matches `/docs`, `/docs/getting-started`, `/docs/api/reference`, and so on. - -**Migrate OpenAPI specifications:** +For a site that publishes documentation below a path such as `/docs`, filter the scrape to that path: ```bash -mintlify-scrape openapi-file [openApiFilename] -``` - -### Add prepared content to your Mintlify project - -After scraping your existing documentation platform, you are ready to build your docs on Mintlify. - -Confirm that you scraped all of your pages. Then add these files to the documentation repository that you created during the onboarding process. This is usually a GitHub repository. - - - -Mintlify can generate a complete documentation site for any public GitHub repository, whether it already contains documentation or just code. - -Replace `github.com` with `mintlify.com` in any public repository URL: - -```text -https://mintlify.com/github-owner/repository-name +npx @mintlify/scraping@latest section https://example.com --filter=/docs ``` -Mintlify analyzes your repository and generates a complete documentation site that you can further customize. - - - - -Migrate your documentation from any platform with full control over the process. - -### Content migration - -To migrate your content to Mintlify, you need: - -- A valid `docs.json` for your site settings and navigation. See [Global settings](/organize/settings) and [Navigation](/organize/navigation) for more information. -- A Markdown file (`.md` or `.mdx`) for each page of your documentation. MDX is the recommended format. See [Pages](/organize/pages) for more information. -- (Optional) An OpenAPI specification for your API endpoint pages. See [OpenAPI setup](/api-playground/openapi-setup) for more information. - -1. If your content is already in Markdown format, copy the content to your Mintlify project. Otherwise, convert your content to MDX format. -2. Create your `docs.json` referencing the paths to your Markdown pages. -3. If you have OpenAPI specifications, add them to your `docs.json` and configure the API playground. You can also generate MDX pages from your spec using the [`@mintlify/scraping`](https://www.npmjs.com/package/@mintlify/scraping) package: +Scrape one page while testing component conversion: ```bash -npx @mintlify/scraping@latest openapi-file -o +npx @mintlify/scraping@latest page https://docs.example.com/getting-started ``` - - If you migrate your content as `.md` files, convert them to `.mdx` to support interactive features like React components. - - -### Asset migration - -1. Copy assets to your repository's `images/` directory. -2. Update references in your Markdown files: - ```mdx - ![Alt text](/images/screenshot.png) - ``` +The scraper converts common components such as callouts, cards, accordions, tabs, code groups, and frames. Review the output for custom components, interactive embeds, authenticated pages, and content loaded only after user interaction. - - +## Complete the migration -## Post-migration checklist +After you create the Mintlify pages and navigation: -After completing your migration (automated or manual), check the following: +1. Compare the migrated page inventory with the source inventory. +2. Recreate platform features that do not have a direct content export. +3. Add redirects for every URL that changes. +4. Preview and test the site with your team. +5. Follow the [go-live checklist](/migration/go-live) before switching your domain. -- All pages render -- Navigation works as intended -- Internal links resolve properly -- Images and assets load correctly -- Code blocks display with proper syntax highlighting -- Search works -- Correct deployment branch + + Work with the Mintlify migration team on information architecture, content conversion, quality assurance, and launch. + diff --git a/migration/docusaurus.mdx b/migration/docusaurus.mdx new file mode 100644 index 0000000000..c83ae265f5 --- /dev/null +++ b/migration/docusaurus.mdx @@ -0,0 +1,155 @@ +--- +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 automated scraper, or migrate from its source repository when you need more control over versions, localized content, or custom React components. + +## Choose a method + +| Method | Use it when | +| --- | --- | +| Automated scraper | The complete documentation site is public and most content uses standard Docusaurus components. | +| Source migration | The site is private or uses versioning, localization, custom plugins, custom React components, or unpublished pages. | + +For complex sites, use both methods: scrape the public site to create an initial `docs.json` and component conversion, then compare the result with the source repository for missing content. + +## Migrate a public site + +Run the scraper in an empty directory so it does not replace files in an existing project. + +```bash +mkdir mintlify-migration +cd mintlify-migration +npx @mintlify/scraping@latest section https://docs.example.com +``` + +If the Docusaurus documentation uses a route base path, filter the scrape to 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 it finishes, compare the generated navigation with `sidebars.js`, `sidebars.ts`, or the autogenerated source directory. Check for collapsed categories, external links, generated category index pages, and pages excluded from the published sidebar. + +## Migrate from source + +Copy the following source into a separate migration branch or working directory: + +- The configured docs content directory, which is `docs/` by default +- `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//docusaurus-plugin-content-docs/` +- React components imported by MDX pages + + + Docusaurus can change its docs directory, route base path, sidebar generator, and included files in the docs plugin configuration. Read the configuration instead of assuming that all content is under `docs/`. + + +Copy Markdown and MDX pages into the Mintlify project. Every page needs frontmatter with at least a `title`. + +```mdx +--- +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). | +| `
` and `` | 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 source. Decide 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 */} +``` + +Replace them with HTML IDs when you must preserve inbound anchor links: + +```mdx +
+ +## Configure the 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-` 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. + +## Validate the result + +- 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) diff --git a/migration/gitbook.mdx b/migration/gitbook.mdx new file mode 100644 index 0000000000..3676193dc7 --- /dev/null +++ b/migration/gitbook.mdx @@ -0,0 +1,159 @@ +--- +title: "Migrate from GitBook" +description: "Migrate GitBook spaces, Markdown, navigation, reusable content, variants, assets, and OpenAPI documentation to Mintlify." +keywords: ["GitBook migration", "GitBook to Mintlify", "Git Sync", "SUMMARY.md"] +--- + +Export GitBook content to a Git repository with Git Sync for the most complete migration, or scrape a public GitBook site to create an initial Mintlify project. + +## Choose a method + +| Method | Use it when | +| --- | --- | +| Git Sync export | You can administer the GitBook space or need source Markdown, reusable content, private pages, or a stable migration snapshot. | +| Automated scraper | The site is public and you want a fast conversion of rendered pages, common blocks, assets, and navigation. | + +Use Git Sync for the primary migration when possible. A GitBook site can contain multiple spaces and variants, while Git Sync operates at the space level. Export every space that appears on the published site. + +## Export a space with Git Sync + +GitBook does not provide direct Markdown downloads for individual pages. To export a space as Markdown: + +1. Create an empty GitHub or GitLab repository or an empty branch in a migration repository. +2. In the GitBook space, select **Set up Git Sync**. +3. Connect the empty repository and choose the branch for the export. +4. For the initial synchronization direction, select **GitBook → GitHub** or **GitBook → GitLab**. +5. Wait for the sync to finish, then clone or download the repository. +6. Repeat for every space, language, or version that you need to migrate. + + + The initial sync direction matters. Selecting the repository-to-GitBook direction with an empty repository can replace or remove space content. Confirm that the direction starts at GitBook and targets the empty repository. + + +Keep the synchronized repository unchanged as a migration snapshot. Create a branch or copy for Mintlify conversion. + +## Migrate a public site + +Run the scraper in an empty directory: + +```bash +mkdir mintlify-migration +cd mintlify-migration +npx @mintlify/scraping@latest section https://docs.example.com +``` + +The scraper loads GitBook's rendered navigation, downloads reachable images, converts common blocks, and creates a `docs.json`. It cannot retrieve private spaces, unpublished changes, permissions, comments, or revision history. + +Compare the generated project with the Git Sync export when both are available. The scrape is useful for checking rendered block conversion; the export is the better inventory of source content. + +## Understand the Git Sync export + +GitBook normally creates or uses: + +```text +README.md Space home page +SUMMARY.md Table of contents +.gitbook.yaml Content root, structure, and space redirects +.gitbook/assets/ Uploaded images and files +.gitbook/includes/ Reusable content +``` + +The paths can differ when the GitBook configuration defines another content root, home page, or summary file. Read the configuration before moving any files. + +## Convert `SUMMARY.md` navigation + +`SUMMARY.md` is a nested Markdown list. Convert its headings and links to `docs.json` navigation: + +| GitBook `SUMMARY.md` | Mintlify | +| --- | --- | +| Heading | Navigation group or other division | +| Top-level linked item | Page path | +| Linked item with children | Group with a `root` and nested `pages` | +| Nested linked item | Page or nested group | +| `README.md` | Space or group overview page | +| External link | Navigation link where supported, or a normal page that points to the external resource | + +Remove `.md` extensions from navigation paths, but do not rename every file before checking links. A page such as `guides/README.md` can become `guides/index.mdx` or remain a Markdown file with a different navigation path. + + + Community scripts can automate the recursive `SUMMARY.md` mapping, but review their generated file moves and shell commands before running them. A converter must handle missing links, external URLs, duplicate pages, nested groups, and GitBook content roots without overwriting source files. + + +## Convert GitBook blocks + +Git Sync represents many GitBook blocks with `{% ... %}` directives. Convert these directives to Mintlify components. + +| GitBook source | Mintlify replacement | +| --- | --- | +| `{% hint style="info" %}` | [`Info`](/components/callouts) | +| `hint` style `success` | [`Check`](/components/callouts) or `Tip` | +| `hint` style `warning` | [`Warning`](/components/callouts) | +| `hint` style `danger` | [`Danger`](/components/callouts) | +| `{% tabs %}` and `{% tab title="..." %}` | [`Tabs` and `Tab`](/components/tabs) | +| Expandable block | [`Accordion`](/components/accordions) | +| Code tabs | [`CodeGroup`](/components/code-groups) | +| Cards and columns | [`Card`, `CardGroup`](/components/cards), or [`Columns`](/components/columns) | +| Embedded media or integration block | A supported [embed](/create/image-embeds), link, image, or custom React component | + +GitBook exports some custom blocks as HTML because they do not have a Markdown representation. Review every HTML block instead of assuming that it behaves the same in MDX. + +## Convert reusable content + +GitBook exports reusable content into `.gitbook/includes/` and references it with include directives. Convert each reusable file to a [Mintlify snippet](/create/reusable-snippets), then replace the GitBook include with an MDX import and component. + +For example: + +```mdx +import Authentication from "/snippets/authentication.mdx"; + + +``` + +Check reusable content shared across multiple spaces. GitBook assigns an owning space, so separate space exports can contain duplicate or cross-space references that need to become a single shared snippet. + +## Migrate spaces, variants, and translations + +A GitBook site can publish multiple spaces as sections and use variants for versions or languages. Choose the closest Mintlify navigation model: + +- Map product or audience spaces to [products](/organize/navigation#products), tabs, or anchors. +- Map release variants to [versions](/organize/navigation#versions). +- Map translated spaces to [languages](/organize/navigation#languages). +- Map independent content collections to separate groups when users do not need a selector. + +Record the default variant and every variant slug before changing the domain. GitBook can omit the default variant slug from its public URL, so redirects must account for both the default and explicitly named paths. + +## Migrate assets and links + +Copy `.gitbook/assets/` into the Mintlify repository and update relative image and download paths. Review inline images that use HTML for sizing or alignment. + +GitBook redirects can exist in its configuration file and in site-level settings. Export both sources and convert them to Mintlify [redirects](/create/redirects). GitBook scopes a space redirect to one space, while a Mintlify redirect applies to the published site, so include the former space or variant prefix when necessary. + +## Migrate OpenAPI documentation + +GitBook can store OpenAPI specifications at the organization level and place generated OpenAPI blocks in spaces. The Markdown space export might not be the source of truth for these specifications. + +1. Inventory every OpenAPI specification in the GitBook organization. +2. Retrieve the original file, hosted source URL, or specification through the GitBook API. +3. Add the JSON or YAML file to the Mintlify repository. +4. Configure [OpenAPI-generated pages](/api-playground/openapi-setup). +5. Recreate adjacent explanations from normal GitBook blocks. +6. Compare authentication, server URLs, examples, and GitBook-specific OpenAPI extensions with the Mintlify output. + +## Validate the result + +- Compare every exported space and `SUMMARY.md` entry with `docs.json`. +- Search for remaining `{%`, `{% end`, `.gitbook/includes`, and raw HTML blocks. +- Confirm that every reusable-content import resolves. +- Test asset paths from nested pages. +- Verify every section, variant, language, and default route. +- Test redirects from the GitBook configuration and site settings. +- Complete the [go-live checklist](/migration/go-live). + +## GitBook references + +- [Git Sync](https://gitbook.com/docs/getting-started/git-sync) +- [Content configuration](https://gitbook.com/docs/getting-started/git-sync/content-configuration) +- [Exporting content](https://gitbook.com/docs/help-center/editing-content/managing-your-content) +- [Reusable content](https://gitbook.com/docs/creating-content/reusable-content) +- [Content variants](https://gitbook.com/docs/publishing-documentation/site-structure/variants) +- [OpenAPI](https://gitbook.com/docs/api-references/openapi) diff --git a/migration/go-live.mdx b/migration/go-live.mdx new file mode 100644 index 0000000000..29af4ae39f --- /dev/null +++ b/migration/go-live.mdx @@ -0,0 +1,101 @@ +--- +title: "Migration go-live checklist" +description: "Validate content, redirects, domains, authentication, analytics, and SEO before launching migrated documentation on Mintlify." +keywords: ["migration checklist", "documentation launch", "go live", "redirect validation"] +--- + +Use this checklist after migrating content and before directing users to the Mintlify site. + +## Prepare the launch + +- Set a final content freeze or identify every source change made after the migration snapshot. +- Confirm the production branch and repository connection. +- Assign an owner for launch, DNS, content validation, and rollback decisions. +- Record the current DNS configuration and former documentation deployment settings. +- Keep the former site available until you verify the Mintlify deployment and redirects. + +## Validate content + +- Compare the migrated files with the source inventory. +- Confirm that every intended public, private, versioned, and localized page exists. +- Verify navigation hierarchy, order, titles, and group overview pages. +- Review code blocks, callouts, tabs, accordions, cards, tables, and custom components. +- Check images, videos, fonts, and downloadable files. +- Remove source-platform directives, imports, variables, and placeholders. +- Confirm that deprecated content has a clear warning and replacement path. + +## Validate links and redirects + +- Crawl internal links and repair broken page or anchor destinations. +- Test old URLs against the [redirect configuration](/create/redirects). +- Verify version, language, category, space, and API reference URL prefixes. +- Check redirects for removed and consolidated pages. +- Confirm that redirects preserve query strings when required. +- Avoid redirect chains and loops. +- Test representative inbound links from product UI, repositories, support content, and search results. + +## Validate API documentation + +- Confirm that every OpenAPI, AsyncAPI, or GraphQL source loads successfully. +- Compare endpoint count and order with the former site. +- Verify server URLs, authentication schemes, parameters, schemas, and examples. +- Test interactive requests against a safe environment. +- Confirm that supplemental endpoint descriptions were not left behind in the former platform. +- Check generated code examples in the languages your users need. + +## Validate versions, languages, and access + +- Confirm the default version and language. +- Test every selector and its corresponding URL. +- Verify version-specific and language-specific links and assets. +- Configure [authentication](/deploy/authentication-setup) and page visibility for restricted documentation. +- Test access as a signed-out user and as each relevant user group. +- Confirm that private source content did not become public during migration. + +## Configure the site + +- Connect the production repository with the appropriate [Git provider](/deploy/github). +- Invite maintainers and review [dashboard roles](/dashboard/roles). +- Configure the navbar, footer, favicon, logo, colors, and typography. +- Set page and site metadata, canonical URLs, and indexing preferences. +- Install required [analytics integrations](/integrations/analytics/overview). +- Configure the assistant, search, feedback, and other enabled product features. +- Add a [custom 404 page](/customize/custom-404-page) when necessary. + +## Test the deployment + +Preview the exact launch commit. + +- Test desktop and mobile layouts. +- Check representative pages from every navigation section. +- Verify search with product names, error messages, and common user language. +- Test redirects in the preview environment. +- Review browser console and network errors on pages with custom components or scripts. +- Ask subject-matter owners to approve their sections. + +## Switch the domain + +Follow the [custom domain guide](/customize/custom-domain) to verify the domain and provision TLS before changing production traffic. + +For a low-downtime migration: + +1. Lower the DNS record's TTL before the planned switch when your DNS provider allows it. +2. Add and verify the required DNS records in Mintlify. +3. Wait for the custom domain and TLS certificate to be ready. +4. Point production traffic to Mintlify. +5. Load the site through the custom domain and repeat the critical-path tests. + +Do not remove the former deployment immediately. Keep a rollback path until DNS has propagated and the new site is stable. + +## Monitor after launch + +During the first days after launch: + +- Monitor 404 errors, redirect failures, build failures, and search queries with no results. +- Check analytics for unexpected traffic drops on high-value pages. +- Review support reports and documentation feedback. +- Confirm that search engines can crawl intended public pages and cannot index private pages. +- Fix high-traffic broken links and missing assets first. +- Record post-launch source changes before ending the content freeze. + +When validation is complete, archive the migration inventory and URL mapping with the project so future maintainers can understand the redirects and content decisions. diff --git a/migration/manual.mdx b/migration/manual.mdx new file mode 100644 index 0000000000..ef079dc233 --- /dev/null +++ b/migration/manual.mdx @@ -0,0 +1,153 @@ +--- +title: "Migrate documentation manually" +description: "Convert documentation from any platform to Mintlify pages, navigation, components, API references, assets, and redirects." +keywords: ["manual documentation migration", "Markdown migration", "MDX migration", "docs.json"] +--- + +Use a manual migration when your current platform is not supported by the scraper, your site is private, or you need complete control over the resulting structure. + +## Collect the source content + +Export or copy all content before converting it. Prefer sources in this order: + +1. Markdown or MDX files from the source repository +2. A native Markdown or HTML export from the platform +3. Content retrieved through the platform API +4. Rendered HTML from the published site +5. Manual copy and conversion + +Keep the original export unchanged. Perform conversion work in a copy so you can compare or restart the migration. + +Create an inventory containing each page's source identifier, title, published URL, destination path, content type, version, language, and migration status. Include unpublished pages that should remain available. + +## Create the Mintlify project + +A Mintlify project needs: + +- A `docs.json` file for site settings and navigation +- One Markdown or MDX file for each documentation page +- Images and downloadable files stored in the repository +- Optional OpenAPI or AsyncAPI specifications for generated API documentation + +Start with a minimal page: + +```mdx +--- +title: "Get started" +description: "Install the SDK and make your first request." +--- + +Follow these steps to get started. +``` + +See [Pages](/organize/pages) for supported frontmatter and file behavior. + +## Design navigation + +Do not reproduce the old sidebar mechanically if the migration is also an opportunity to improve how users find content. Preserve familiar routes where possible, but organize the destination around user tasks. + +Use the appropriate [navigation structure](/organize/navigation): + +| Content model | Mintlify navigation | +| --- | --- | +| One documentation set | Groups and pages | +| Distinct products | Products | +| Major content areas | Tabs or anchors | +| Supported releases | Versions | +| Translated documentation | Languages | +| Group overview | A group with a `root` page | + +Add every page path to `docs.json` unless you intend to hide the page. A page that is not in navigation can still be reachable by URL. + +## Convert content + +Plain Markdown usually needs little conversion. Replace platform-specific syntax with Mintlify components. + +| Source pattern | Mintlify feature | +| --- | --- | +| Note, tip, warning, or danger block | [Callout](/components/callouts) | +| Collapsible section | [Accordion](/components/accordions) | +| Alternative instructions | [Tabs](/components/tabs) | +| Multiple code examples | [Code group](/components/code-groups) | +| Linked resource tiles | [Cards](/components/cards) | +| Sequential procedure | [Steps](/components/steps) | +| Reused content | [Reusable snippet](/create/reusable-snippets) | +| Interactive or application-specific UI | [React component](/customize/react-components) | + +Search the converted files for source-platform directives, imports, templating variables, raw HTML, and unresolved includes. These patterns often render as text or fail during an MDX build. + +## Migrate API documentation + +Locate the original OpenAPI or AsyncAPI specification when one exists. Add it to the Mintlify repository and follow the relevant setup guide: + +- [OpenAPI setup](/api-playground/openapi-setup) +- [AsyncAPI setup](/api-playground/asyncapi-setup) +- [GraphQL setup](/api-playground/graphql-setup) + +If the source platform stored endpoint descriptions outside the specification, merge useful content into the specification or place it in adjacent guides. Compare operation order, authentication, server URLs, examples, schemas, and code samples with the old site. + +You can generate initial OpenAPI endpoint pages with the scraper package: + +```bash +npx @mintlify/scraping@latest openapi-file ./openapi.yaml -o api-reference +``` + +## Migrate assets + +Copy images, videos, fonts, and downloadable files that you own into the repository. Preserve existing public paths where practical to reduce link changes. + +Review: + +- Markdown image and link destinations +- HTML `` and `