diff --git a/docs.json b/docs.json index 652ac7d90c..0b6719ed0e 100644 --- a/docs.json +++ b/docs.json @@ -41,7 +41,18 @@ "cli/commands" ] }, - "migration" + { + "group": "Migrate to Mintlify", + "root": "migration/index", + "pages": [ + "migration/docusaurus", + "migration/readme", + "migration/gitbook", + "migration/fern", + "migration/document360", + "migration/manual" + ] + } ] }, { diff --git a/migration.mdx b/migration.mdx deleted file mode 100644 index 3f98bef049..0000000000 --- a/migration.mdx +++ /dev/null @@ -1,204 +0,0 @@ ---- -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"] ---- - -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. - -## 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 -``` - -### Scrape pages and sections - -The migration tool automatically detects your documentation platform and converts your content. It saves prepared files locally in the `./docs` folder by default. - -For large documentation sites, migrate smaller sections one at a time rather than the entire site at once. - -**Migrate entire sections:** -```bash -mintlify-scrape section https://your-docs-site.com/docs -``` - -**Migrate single pages:** -```bash -mintlify-scrape page https://your-docs-site.com/docs/getting-started -``` - -**Filter specific paths:** - -Use the `--filter` (or `-f`) option to scrape only URLs matching a specific path prefix. - -```bash -mintlify-scrape section https://your-docs-site.com --filter=/docs -``` - -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:** - -```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 -``` - -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: - -```bash -npx @mintlify/scraping@latest openapi-file -o -``` - - - 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) - ``` - - - - -## Post-migration checklist - -After completing your migration (automated or manual), check the following: - -- 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 diff --git a/migration/document360.mdx b/migration/document360.mdx new file mode 100644 index 0000000000..9108138913 --- /dev/null +++ b/migration/document360.mdx @@ -0,0 +1,144 @@ +--- +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"] +--- + +import MigrationLaunchChecklist from "/snippets/migration-launch-checklist.mdx"; + +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. + + + The Mintlify scraper does not currently support Document360. + + +## 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 Document360, navigate to **Content tools > Import and export > Import and export project**. + + + 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. + + +1. Click **Export project**. +2. Select the export format. Choose **JSON** for a complete project export. +3. In **Include new or modified articles in**, select **All** so the export is not limited to recently modified articles. +4. Select every maintained workspace, language, category, and subcategory. +5. Select **Include media files**. +6. Click **Export**. The export runs in the background and notifies you when it is ready. +7. Download the ZIP from **Recent files** as soon as it is ready. Each new export overwrites the previous ZIP. +8. Export the **All articles** list as CSV. This list of metadata is useful for reconciling titles, publication status, dates, categories, and URLs. + + + Keep the exported ZIP and CSV unchanged as source snapshots. Make copies for any conversion work you do while migrating. + + +## 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 your exported ZIP, article CSV, API inventory, and published sitemap align, then test language switching and every workspace selector. + +Search your converted files for unconverted Document360 content: raw HTML, snippet and variable references, private notes, and widget embeds. + + + +## 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) diff --git a/migration/docusaurus.mdx b/migration/docusaurus.mdx new file mode 100644 index 0000000000..266760defb --- /dev/null +++ b/migration/docusaurus.mdx @@ -0,0 +1,162 @@ +--- +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"] +--- + +import MigrationLaunchChecklist from "/snippets/migration-launch-checklist.mdx"; + +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 + + + The scraper can overwrite existing files. + + Run the scraper in an empty directory so it does not replace any existing files. + + +```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//docusaurus-plugin-content-docs//`, such as `current/` +- 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. Depending on your configuration, your content may be in a different directory than `docs/`. + + +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). | +| `
` 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 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. +- Do not leave required production assets on your former deployment unless you plan to keep that hosting after your migration. + +## 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/...`. + +If your source repository contained unpublished or restricted pages, configure [authentication](/deploy/authentication-setup) and page visibility, then test your site as a signed-out user and as a member of each group. + +## 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 your migrated pages against your sidebar entries and published sitemap, then preview every maintained version and language. + +Search your converted files for leftover Docusaurus syntax, which renders as literal text or fails the build: `@theme`, `@site`, `:::`, `DocCardList`, `useDocusaurusContext`, and custom plugin imports. + + + +## 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) diff --git a/migration/fern.mdx b/migration/fern.mdx new file mode 100644 index 0000000000..4a29044dae --- /dev/null +++ b/migration/fern.mdx @@ -0,0 +1,138 @@ +--- +title: "Migrate from Fern" +description: "Migrate Fern MDX content, docs.yml navigation, products, versions, assets, API references, and components to Mintlify." +keywords: ["Fern migration", "Fern to Mintlify", "docs.yml", "Fern Docs"] +--- + +import MigrationLaunchChecklist from "/snippets/migration-launch-checklist.mdx"; + +Migrate a Fern site from its Git repository. Fern stores documentation as Markdown or MDX alongside `docs.yml`, assets, and API specifications, so the source repository is more complete and reliable than the published HTML. + + + The Mintlify scraper does not currently support Fern. + + +## Collect your source content + +Create a migration branch or copy of your documentation repository. + +Locate all of the following items: + +- `fern/docs.yml`, which defines site settings and navigation +- MDX pages, commonly in `fern/docs/pages/` +- Image, video, favicon, and logo assets, commonly in `fern/docs/assets/` +- Reusable MDX snippets, commonly in `fern/docs/snippets/` +- Changelog entries in `fern/docs/changelog/` +- `fern/styles.css` and any other custom CSS or JavaScript +- `fern/fern.config.json` and the pinned Fern CLI version +- OpenAPI, AsyncAPI, and Fern definition files +- `generators.yml` and scripts that retrieve or generate API specifications +- Product, version, and tab configuration files referenced by `docs.yml` +- Custom MDX components +- Any environment variables, remote specifications, generated files, or private packages required when you run `fern check` or `fern docs dev` + + + Fern reserves the `fern` and `changelog` folder names. Every other folder name is configurable, so confirm your directory names against `docs.yml` before you move files. + + +## Recreate navigation + +Fern defines navigation in `docs.yml` or in separate files for products and versions. Mintlify defines navigation in `docs.json`. + +| Fern | Mintlify | +| --- | --- | +| `page` with `path` | Page path in a `pages` array | +| `section` | Navigation group | +| Section with `path` | Group with a `root` page | +| `folder` | Navigation group with its pages listed explicitly | +| `link` | Navigation link, anchor, menu item, or card | +| `tabs` | Tabs in `docs.json` | +| `products` | Products in `docs.json` | +| Site-wide versions | Versions in `docs.json` | +| `hidden: true` | `hidden: true` in page frontmatter or a hidden navigation entry | + +Fern constructs routes from the slugs of sections, folders, tabs, versions, products, and pages. Do not infer the old URL from the source filename alone. Export the published sitemap and resolve `slug`, `skip-slug`, and page-level path overrides before creating redirects. + +When a Fern folder uses `index.mdx` as its overview, use that page as the Mintlify group's `root`. Preserve deliberate navigation order rather than relying on Fern's alphabetical folder discovery. + +## Convert pages and frontmatter + +Most standard Markdown and MDX can move directly. Every Mintlify page needs a `title`. Retain descriptions, keywords, and other useful SEO metadata. + +Review Fern-specific frontmatter such as: + +- `slug` and path overrides +- `availability` badges +- Page layout and table-of-contents settings +- Visibility and indexing controls +- API reference associations + +Recreate behavior with Mintlify frontmatter, navigation, or content. Add a callout for availability states that do not have an equivalent presentation. + +## Convert components + +Fern and Mintlify both use MDX components, but component names and properties are not interchangeable. Search every page for JSX tags and imports instead of assuming they render unchanged. + +| Fern content | Mintlify treatment | +| --- | --- | +| Callouts | Convert to [`Note`, `Tip`, `Info`, `Warning`, or `Danger`](/components/callouts). | +| `Tabs` and `Tab` | Convert properties and labels to [`Tabs` and `Tab`](/components/tabs). | +| Steps | Convert to [`Steps` and `Step`](/components/steps). | +| Accordions | Convert to [`AccordionGroup` and `Accordion`](/components/accordions). | +| Cards and buttons | Map to [Mintlify cards](/components/cards) and supported links. | +| `Versions` blocks | Use tabs or separate versioned pages, depending on whether the selection should affect one block or the site. | +| `If` blocks | Split content by product or version, or use a supported custom component when conditional rendering is essential. | +| API schema and endpoint snippet components | Generate the reference from the original API specification and move supplemental prose into guides or operation descriptions. | +| Reusable MDX snippets from `fern/docs/snippets/` | Convert to [Mintlify snippets](/create/reusable-snippets) and update each import path. | +| Custom MDX components | Rebuild with a [React component](/customize/react-components) or replace with a built-in component. | + +Remove Fern-only imports after conversion. Preview pages that use nested components because valid syntax and supported properties can differ even when both platforms use the same component name. + +## Migrate API references + +Use your API specification to create your new API reference pages. + +1. Trace each `api` navigation entry to its OpenAPI, AsyncAPI, or Fern definition source. +2. Download specifications that the build retrieves from a URL or another repository. +3. Preserve overlays, generated examples, authentication configuration, and custom endpoint prose. +4. Add the source specification to the Mintlify repository and configure [API reference pages](/api-playground/openapi-setup). +5. Compare endpoint grouping, servers, security schemes, examples, and SDK snippets with the Fern site. + +Fern definitions can contain information that is not represented directly in an OpenAPI document. Review the generated OpenAPI output and move any missing descriptions or examples before retiring your Fern build. + +## Migrate products and versions + +Fern can place navigation in product-specific or version-specific YAML files. Inventory every referenced file and map each maintained product and version to the corresponding Mintlify [navigation structure](/organize/navigation). + +Check for: + +- A landing page outside the product navigation +- Products or versions with different page trees +- Slugs added by product, version, or tab levels +- Version-specific API specifications +- Hidden, deprecated, or pre-release sections +- External products that link to another site + +## Migrate assets and site settings + +Copy files from the configured asset directories and update relative paths after moving pages. Do not leave required production assets on your former deployment unless you plan to keep that hosting after your migration. Review `docs.yml` for logos, favicons, social images, fonts, colors, navbar links, announcement banners, redirects, analytics, custom CSS, and custom JavaScript. + +Recreate supported settings in `docs.json`. Treat CSS and JavaScript as requirements to evaluate, not files to copy blindly, because their selectors and runtime assumptions are platform-specific. + +## Review your migration + +Compare every `docs.yml` navigation entry and discovered folder page against `docs.json`, then validate every product, version, and tab. + +Search your converted files for leftover Fern syntax: component imports, unsupported JSX properties, and `Versions` or `If` blocks. + + + +## Fern references + +- [Project structure](https://buildwithfern.com/learn/docs/getting-started/project-structure) +- [Navigation](https://buildwithfern.com/learn/docs/configuration/navigation) +- [Products](https://buildwithfern.com/learn/docs/configuration/products) +- [Versions](https://buildwithfern.com/learn/docs/configuration/versions) +- [Components](https://buildwithfern.com/learn/docs/writing-content/components/overview) +- [Custom CSS and JavaScript](https://buildwithfern.com/learn/docs/customization/custom-css-js) +- [CLI commands](https://buildwithfern.com/learn/cli-api-reference/cli-reference/commands) diff --git a/migration/gitbook.mdx b/migration/gitbook.mdx new file mode 100644 index 0000000000..471c31a4f2 --- /dev/null +++ b/migration/gitbook.mdx @@ -0,0 +1,174 @@ +--- +title: "Migrate from GitBook" +description: "Migrate GitBook sections, Markdown, navigation, reusable content, variants, assets, and OpenAPI documentation to Mintlify." +keywords: ["GitBook migration", "GitBook to Mintlify", "Git Sync", "SUMMARY.md", "GitBook sections"] +--- + +import MigrationLaunchChecklist from "/snippets/migration-launch-checklist.mdx"; + +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 are an admin of your GitBook site or need source Markdown, reusable content, private pages, or a stable migration snapshot. | +| Automated scraper | Your GitBook 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 is made up of sections, and a section can have multiple variants, while Git Sync operates at the section level. Export every section that appears on the published site. + + + GitBook now calls the content containers inside a site sections. Older GitBook documentation and community scripts call them spaces. + + +## Export a section with Git Sync + +GitBook does not provide direct Markdown downloads for individual pages. To export a section as Markdown: + +1. Create an empty GitHub or GitLab repository or an empty branch in a migration repository. +2. In the section you want to export, click **Set up** next to **Git Sync** in the section header. +3. From the provider list, click **GitHub Sync** or **GitLab Sync**, then authenticate if you have not connected the provider yet. +4. Select the empty repository and the branch for the export. +5. For the initial sync direction, choose **GitBook → GitHub** or **GitBook → GitLab**. +6. Start the initial sync. When it finishes, clone or download the repository. +7. Repeat for every section, language, or version that you need to migrate. + + + The initial sync direction matters. Choosing **GitHub → GitBook** or **GitLab → GitBook** replaces your section's content with the selected branch instead of exporting the section. Confirm that the direction starts at GitBook and targets your empty repository. If you choose the wrong direction, roll back to the revision before the Git Sync operation in the section's version history. + + +Keep the synchronized repository unchanged as a migration snapshot. Create a branch or copy for your Mintlify conversion. + +## Migrate a public site + + + The scraper overwrites existing files in a directory. + + 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 sections, unpublished changes, permissions, comments, or revision history. + +Compare the generated project with your 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 the following files and directories: + +{/* vale Vale.Terms = NO */} + +- `README.md`: Section home page +- `SUMMARY.md`: Table of contents +- `.gitbook.yaml`: Content root, structure, and section redirects +- `.gitbook/assets/`: Uploaded images and files +- `.gitbook/includes/`: Reusable content + +{/* vale Vale.Terms = YES */} + +The paths can differ when the GitBook configuration defines another content root, home page, or summary file. Confirm your specific 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` | Section 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. + +Every Mintlify page also needs frontmatter with at least a `title`. Add or convert frontmatter as you migrate each page. + + + Community scripts can automate the recursive `SUMMARY.md` mapping. 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 + +GitBook represents many 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 to verify it functions 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 sections. GitBook assigns a parent section that owns the content and is the only place it can be edited, so separate section exports can contain duplicate or cross-section references that need to become a single shared snippet. + +## Migrate sections, variants, and translations + +A GitBook site publishes one or more sections, organizes related sections into groups, and uses variants for versions or languages. Choose the closest Mintlify navigation model: + +- Map product or audience sections to [products](/organize/navigation#products), tabs, or anchors. +- Map release variants to [versions](/organize/navigation#versions). +- Map translated sections 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 your Mintlify repository and update relative image and download paths. Review inline images that use HTML for sizing or alignment. Do not leave required production assets on GitBook unless you plan to keep that hosting after your migration. + +GitBook redirects can exist in your configuration file and in site-level settings. Collect both sources and convert them to Mintlify [redirects](/create/redirects). GitBook scopes a redirect in its configuration file to one section, while a Mintlify redirect applies to the published site, so include the former section or variant prefix when necessary. + +## Migrate OpenAPI documentation + +GitBook can store OpenAPI specifications at the organization level and place generated OpenAPI blocks in sections. The Markdown section export might not be the source of truth for these specifications. + +1. Inventory every OpenAPI specification in your GitBook organization. +2. Retrieve the original file, hosted source URL, or specification through the GitBook API. +3. Add the JSON or YAML file to your 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 your Mintlify API pages. + +## Review your migration + +Compare every exported section and `SUMMARY.md` entry against `docs.json`, then verify every section, group, variant, and language. + +Search your converted files for leftover GitBook syntax: `{%`, `{% end`, `.gitbook/includes`, and the raw HTML blocks that GitBook exports in place of Markdown. + + + +## GitBook references + +- [Git Sync](https://gitbook.com/docs/getting-started/git-sync) +- [Enable GitHub Sync](https://gitbook.com/docs/getting-started/git-sync/enabling-github-sync) +- [Content configuration](https://gitbook.com/docs/getting-started/git-sync/content-configuration) +- [Content structure](https://gitbook.com/docs/creating-content/content-structure) +- [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) +- [Add an OpenAPI specification](https://gitbook.com/docs/api-references/openapi/add-an-openapi-specification) diff --git a/migration/index.mdx b/migration/index.mdx new file mode 100644 index 0000000000..3ec2383b69 --- /dev/null +++ b/migration/index.mdx @@ -0,0 +1,49 @@ +--- +title: "Migration overview" +sidebarTitle: "Overview" +description: "Choose a migration path for moving existing documentation from Docusaurus, ReadMe, GitBook, Fern, Document360, or another platform to Mintlify." +keywords: ["migration", "Docusaurus", "ReadMe", "GitBook", "Fern", "Document360", "import"] +--- + +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. + + + Scrape a public site, or migrate from source to preserve private pages, versioned docs, localized content, and custom React components. + + + Export project files to preserve private content and OpenAPI files, or scrape a public site for a faster starting point. + + + Export each section with Git Sync for the most complete migration, or scrape a public site. + + + Migrate MDX, assets, API specifications, and `docs.yml` configuration from the source repository. + + + Export every workspace and language as a project ZIP, including articles, categories, and media files. + + + Follow the manual workflow for another platform or a project with mixed content sources. + + +## Scrape individual pages + +The Docusaurus, ReadMe, and GitBook guides use the scraper's `section` command, which converts every page it can reach from the URL you give it. To convert a single page instead, use the `page` command from your migration directory. + +```bash +npx @mintlify/scraping@latest page https://docs.example.com/getting-started +``` + +Use `page` to check how the scraper converts your content before a full run, or to fill in individual pages that a `section` run missed. For a large site, narrow a `section` run with `--filter` rather than scraping everything at once. + +## Generate a site from a repository + +Mintlify can generate a complete documentation site for any GitHub repository, whether it already contains documentation or just code. + +Replace `github` with `mintlify` in your repository URL. + +```text +https://github.com/org/repo -> https://mintlify.com/org/repo +``` + +Browse [generated documentation sites](https://www.mintlify.com/wiki) to see more examples. diff --git a/migration/manual.mdx b/migration/manual.mdx new file mode 100644 index 0000000000..10fe2828b0 --- /dev/null +++ b/migration/manual.mdx @@ -0,0 +1,133 @@ +--- +title: "Migrate from another platform" +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"] +--- + +import MigrationLaunchChecklist from "/snippets/migration-launch-checklist.mdx"; + +Use a manual migration when your current platform is not included in the listed platforms, your site is private, or you need complete control over the resulting structure. + +## Collect your source content + +Export or copy all content before converting it. + +1. Markdown or MDX files from your source repository +2. A native Markdown or HTML export from your current platform +3. Content retrieved through your current platform's API +4. Rendered HTML from your published site +5. Manual copy and conversion + +Keep your original export unchanged. Perform conversion work in a copy so you can compare or restart your 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 your Mintlify project + +A typical Mintlify project includes: + +- A `docs.json` file for site settings and navigation +- Markdown or MDX files for pages that are not generated from an API specification +- Images and downloadable files that you want to host from your repository +- Optional OpenAPI or AsyncAPI specifications or GraphQL schemas for generated API documentation + +See [Pages](/organize/pages) for supported frontmatter and file behavior. + +## Design your navigation + +You can faithfully reproduce your existing navigation structure or use the migration as an opportunity to improve how users find content. + +Use an appropriate [navigation structure](/organize/navigation). The following table shows common navigation patterns for sites hosted on Mintlify. + +| Content model | Mintlify navigation elements | +| --- | --- | +| 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 [hidden page](/organize/hidden-pages) remains reachable by URL, but it is excluded from site search, sitemaps, search engine indexing, and AI context by default. + +## Convert your 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 your 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 or GraphQL schema when one exists. Add the source file to your 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 your 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 your former site. + +You can generate initial OpenAPI endpoint pages with the Mintlify scraper package: + +```bash +npx @mintlify/scraping@latest openapi-file ./openapi.yaml -o api-reference +``` + +## Migrate your assets + +Copy images, videos, fonts, and downloadable files that you own into your repository. Preserve existing public paths where practical to reduce link changes. + +Review the following patterns to identify assets that need to be migrated. + +- Markdown image and link destinations +- HTML `` and `