Migrating from Mintlify

Why Migrate to HolyDocs?

HolyDocs was built as a direct replacement for Mintlify, with full compatibility for existing Mintlify projects and a set of capabilities that go beyond what Mintlify offers.

Pricing Comparison

Feature Comparison

Performance

HolyDocs renders every page on Cloudflare's edge network. There is no origin server round-trip. Pages are pre-rendered to KV and served from the PoP nearest to the reader, resulting in sub-50ms TTFB worldwide compared to Mintlify's typical 200-400ms.

Automatic Migration

The fastest path is the CLI migration command. It converts your mint.json configuration, remaps components, and preserves your content structure.

bash
# Install HolyDocs CLInpm install -g holydocs# Run from your existing Mintlify project directoryholydocs migrate --from mintlify

The command performs the following:

1. Reads your mint.json and converts it to docs.json
2. Scans all MDX files for Mintlify-specific components and converts them
3. Copies images and static assets with preserved paths
4. Validates the converted project

Run holydocs migrate --from mintlify --dry-run first to preview all changes without modifying any files. The dry run shows exactly which files will be created, modified, or copied.

Dry Run Output

text
  Migration Preview (Mintlify -> HolyDocs)  Configuration:    mint.json -> docs.json    - 4 tabs, 12 groups, 56 pages  Components converted:    <Note> -> <Callout type="note">  (23 occurrences)    <Warning> -> <Callout type="warning">  (8 occurrences)    <Tip> -> <Callout type="tip">  (12 occurrences)  Files:    56 MDX pages (3 modified)    42 images copied    1 configuration file created  Run without --dry-run to apply changes.

Manual Migration

If you prefer to migrate manually or need fine-grained control, follow these steps.

Configuration Mapping: mint.json to docs.json

Every field in mint.json has a direct equivalent in docs.json. The table below covers the complete mapping.

Top-Level Fields

Navigation

In Mintlify, navigation is a flat array of groups. In HolyDocs, groups are nested under navigation.tabs. If your Mintlify project does not use tabs, the migration wraps all groups under a single default "Documentation" tab.

API Configuration

Theme Configuration

Full Example

json
{  "name": "Acme API",  "logo": {    "light": "/logo/light.svg",    "dark": "/logo/dark.svg"  },  "favicon": "/favicon.svg",  "colors": {    "primary": "#6366F1",    "light": "#F5F5F4",    "dark": "#0A0A0A",    "anchors": "#6366F1"  },  "modeToggle": {    "default": "dark",    "isHidden": false  },  "topbarLinks": [    { "name": "Dashboard", "url": "https://app.acme.com" }  ],  "topbarCtaButton": {    "name": "Sign Up",    "url": "https://app.acme.com/signup"  },  "tabs": [    { "name": "API Reference", "url": "api-reference" }  ],  "navigation": [    {      "group": "Getting Started",      "pages": ["introduction", "quickstart", "authentication"]    },    {      "group": "Guides",      "pages": ["guides/webhooks", "guides/pagination"]    }  ],  "api": {    "baseUrl": "https://api.acme.com",    "auth": {      "method": "bearer"    }  },  "openapi": "/openapi.json",  "footerSocials": {    "github": "https://github.com/acme",    "twitter": "https://twitter.com/acme"  }}

json
{  "name": "Acme API",  "logo": {    "light": "/logo/light.svg",    "dark": "/logo/dark.svg"  },  "favicon": "/favicon.svg",  "colors": {    "primary": "#6366F1",    "background": {      "light": "#F5F5F4",      "dark": "#0A0A0A"    },    "accent": "#6366F1"  },  "appearance": {    "default": "dark",    "strict": false  },  "theme": "mint",  "navbar": {    "links": [      { "label": "Dashboard", "href": "https://app.acme.com" }    ],    "primary": {      "type": "button",      "label": "Sign Up",      "href": "https://app.acme.com/signup"    }  },  "navigation": {    "tabs": [      {        "tab": "Documentation",        "groups": [          {            "group": "Getting Started",            "pages": ["introduction", "quickstart", "authentication"]          },          {            "group": "Guides",            "pages": ["guides/webhooks", "guides/pagination"]          }        ]      },      {        "tab": "API Reference",        "groups": [          {            "group": "Endpoints",            "pages": ["api-reference/overview"]          }        ]      }    ]  },  "api": {    "baseUrl": "https://api.acme.com",    "auth": {      "type": "bearer"    }  },  "openapi": "/openapi.json",  "footer": {    "socials": {      "github": "https://github.com/acme",      "twitter": "https://twitter.com/acme"    }  }}

Component Mapping

Callout Components

Mintlify uses named components for callouts. HolyDocs uses a single Callout component with a type prop.

mdx
<Note>  This is a note in Mintlify.</Note><Warning>  This is a warning in Mintlify.</Warning><Tip>  A helpful tip in Mintlify.</Tip><Info>  Additional information in Mintlify.</Info><Check>  Task completed successfully in Mintlify.</Check>

mdx
<Callout type="note">  This is a note in HolyDocs.</Callout><Callout type="warning">  This is a warning in HolyDocs.</Callout><Callout type="tip">  A helpful tip in HolyDocs.</Callout><Callout type="info">  Additional information in HolyDocs.</Callout><Callout type="check">  Task completed successfully in HolyDocs.</Callout>

Compatible Components

The following components are identical in both Mintlify and HolyDocs. No changes are needed.

If your Mintlify project only uses compatible components (no <Note>, <Warning>, <Tip>, <Info>, or <Check>), your MDX files require zero modifications.

OpenAPI Migration

HolyDocs supports the same OpenAPI integration pattern as Mintlify. Your existing OpenAPI spec files work without modification.

json
{  "openapi": "/openapi.json"}

json
{  "group": "API Reference",  "pages": [    "api-reference/overview",    "api-reference/GET /users",    "api-reference/POST /users",    "api-reference/GET /users/{id}"  ]}

HolyDocs supports OpenAPI 3.0 and 3.1 specifications. Swagger 2.0 specs are automatically converted during the build.

Custom Domain Transfer

If you have a custom domain configured with Mintlify, you need to update your DNS records to point to HolyDocs.

DNS propagation can take up to 48 hours depending on your provider and TTL settings. During this window, some visitors may still be routed to Mintlify. Consider lowering your TTL to 300 seconds before starting the migration.

Verifying the Migration

After migration, run through this checklist to confirm everything works.

bash
holydocs check

bash
holydocs dev

bash
holydocs deploy

Common Issues and Fixes

json
{  "customCss": "/custom.css"}

json
{  "redirects": [    { "source": "/old-path", "destination": "/new-path" }  ]}