Skip to main content

Mintlify Migration Assessment

Assessment of the biggest challenges for migrating this Docusaurus project to Mintlify, ranked by difficulty.

1. Internationalization (i18n) — Blocker-level​

The project has 3 languages (EN, DE, ES) using Docusaurus's built-in i18n system. Mintlify has no native i18n support — maintaining parallel directory trees manually or using a workaround like separate Mintlify instances per language would be required. This is the single biggest structural mismatch.

2. Heavy Client-Side DOM Manipulation — High​

custom-code.js (~400 lines) does things Mintlify's architecture doesn't support:

  • Dynamically builds a floating index menu by scraping H1/H2 from iframes
  • Uses MutationObserver for SPA route change detection
  • Conditionally shows/hides navbar items and sidebar based on URL patterns
  • Injects CSS into iframes

Mintlify doesn't expose a client module hook. This functionality would need to be rewritten using Mintlify's config or abandoned.

3. Iframe-Embedded Axtension Reference Manuals — High​

The static/axtension/ directory contains full .htm reference manuals loaded via iframes. Mintlify doesn't natively support embedding iframes with dynamic TOC generation. These would need to be converted to native Mintlify pages or hosted externally.

4. Custom Build Plugin — Medium-High​

plugins/docs-index-plugin.js auto-generates a documentation index at build time by scanning frontmatter across all docs. The custom src/pages/index.js consumes this to render a grouped, sortable index page. Mintlify has no equivalent plugin system — a pre-build script or a static replacement would be needed.

5. Complex Sidebar Configuration — Medium​

sidebars.js uses a hybrid approach: 11 manually configured sidebars + 8 auto-generated ones across ~20 product areas. Mintlify uses mint.json for navigation, which is purely declarative. The auto-generation logic would need to be replaced with a script that outputs static config, and multi-sidebar routing would need rethinking.

6. Extensive Custom CSS — Medium​

5 CSS files with:

  • Legal document styling (specific widths, margins, print layout) in src/css/legal.css
  • Custom div-based table components in src/css/tables.css
  • Brand color system and custom fonts (Aptos, CharisSIL) in src/css/custom.css
  • Product-specific themes (Axtension green scheme)

Mintlify supports custom CSS but has its own design system, so many of these would need reworking.

7. Frontmatter Incompatibility — Medium​

The docs use Docusaurus-specific frontmatter (sidebar_position, sidebar_label, displayed_sidebar, hide_title, custom_edit_url, hide_breadcrumbs). These have no direct Mintlify equivalents and would need bulk transformation across ~764 files.

8. JSX/HTML in Markdown — Low-Medium​

The docs embed raw HTML (<div className="style-legal">, <img className="...">, <ol>, <b>) which Mintlify supports partially via MDX, but className → class mapping and custom CSS class references would all need auditing.

What Migrates Easily​

  • The markdown content itself (standard .md)
  • Images (Azure blob storage URLs stay the same)
  • Search (Mintlify has built-in search, replacing @easyops-cn/docusaurus-search-local)
  • Sitemap generation (automatic in Mintlify)
  • No complex MDX components, admonitions, or tabs to convert

Bottom Line​

The i18n requirement and custom client-side JavaScript are the two deal-breakers to evaluate first. If English-only (or a multi-instance approach) is acceptable and the dynamic Axtension iframe menus can be dropped, the rest is achievable with a migration script for frontmatter + sidebar config and manual CSS porting.