> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating from Mintlify

Step-by-step guide to migrate your documentation from Mintlify to HolyDocs in under 5 minutes.

## 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

| | Mintlify | HolyDocs |
|---|---|---|
| Free tier | 1 project, limited pages | 1 project, 50 pages |
| Starter | $150/mo | $29/mo |
| Pro | $400/mo | $79/mo |
| Enterprise | Custom | Custom (lower) |
| Overage charges | Per-page overage fees | No overage fees |

### Feature Comparison

| Feature | Mintlify | HolyDocs |
|---|---|---|
| Edge rendering | Vercel (single region) | Cloudflare Workers (300+ PoPs) |
| AI assistant | Basic search | Agentic RAG with tool calling |
| MCP server | Not available | Built-in per project |
| AI agent | Not available | Autonomous doc maintenance |
| llms.txt | Not available | Auto-generated every build |
| API playground | Basic | Interactive with 7-language code samples |
| i18n / translation | Manual only | AI-powered translation (24 languages) |
| Preview deploys | Pro plan | Pro plan and above |
| Audit logs | Enterprise only | Business plan and above |
| Build speed | 30-60s typical | 5-15s typical |
| Page load (TTFB) | 200-400ms | Under 50ms globally |

### 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 CLI
npm install -g holydocs

# Run from your existing Mintlify project directory
holydocs 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

```
  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.

**Create docs.json from mint.json**

Create a new `docs.json` file at the root of your docs directory. Use the field mapping table below to convert each section of your `mint.json`.
  **Convert MDX components**

Find and replace Mintlify-specific callout components in your MDX files. Most other components are fully compatible and require no changes.
  **Update OpenAPI configuration**

If you use OpenAPI specs, update the configuration key from `openapi` in `mint.json` to the `openapi` field in `docs.json`.
  **Validate and preview**

Run `holydocs check` to validate your configuration and `holydocs dev` to preview locally before deploying.

## 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

| mint.json | docs.json | Notes |
|---|---|---|
| `name` | `name` | Direct mapping |
| `logo` | `logo` | Same structure: `{ "light": "...", "dark": "..." }` |
| `favicon` | `favicon` | Direct mapping |
| `colors.primary` | `colors.primary` | Direct mapping |
| `colors.light` | `background.color.light` | Moved under `background.color` |
| `colors.dark` | `background.color.dark` | Moved under `background.color` |
| `colors.anchors` | `colors.accent` | Renamed |
| `modeToggle` | `appearance` | `default` and `isHidden` map to `appearance.default` and `appearance.strict` |
| `topbarLinks` | `navbar.links` | Migrated into the header nav |
| `topbarCtaButton` | `navbar.primary` | Migrated into the primary header CTA |
| `footerSocials` | `footer.socials` | Migrated into footer socials |
| `feedback.thumbsRating` | `feedback.enabled` | Boolean mapping |
| `feedback.suggestEdit` | `feedback.suggestEdit` | Direct mapping |
| `analytics.ga4` | `analytics.googleAnalytics` | Renamed |
| `analytics.posthog` | `analytics.posthog` | Direct mapping |
| `seo` | `seo` | Direct mapping |
| `api` | `api` | See API section below |

### Navigation

| mint.json | docs.json | Notes |
|---|---|---|
| `navigation` (array of groups) | `navigation.tabs[0].groups` | Wrapped in a default tab |
| `tabs` | `navigation.tabs` | Each tab contains its own `groups` |
| `anchors` | `navigation.tabs` | Anchors become additional tabs |
| `tabs[].name` | `navigation.tabs[].tab` | Key renamed from `name` to `tab` |
| `navigation[].group` | `groups[].group` | Direct mapping |
| `navigation[].pages` | `groups[].pages` | Direct mapping |

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

| mint.json | docs.json | Notes |
|---|---|---|
| `api.baseUrl` | `api.baseUrl` | Direct mapping |
| `api.auth.method` | `api.auth.type` | Renamed: `bearer`, `key`, `basic` |
| `api.auth.name` | `api.auth.name` | Direct mapping |
| `openapi` | `openapi` | Path to OpenAPI spec file(s) |
| `api.playground.mode` | `api.playground.enabled` | `"hide"` becomes `false` |

### Theme Configuration

| mint.json | docs.json | Notes |
|---|---|---|
| `layout` | `theme` | `"sidenav"` maps to any theme; `"topnav"` maps to `"atlas"` or `"nova"` |
| `rounded` | Theme default | HolyDocs themes have built-in border radius |
| `font.headings` | `typography.headings` | Font family configuration |
| `font.body` | `typography.body` | Font family configuration |

### Full Example

**mint.json (Before)**

```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"
      }
    }
    ```
  **docs.json (After)**

```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.

| Mintlify Component | HolyDocs Equivalent |
|---|---|
| `<Note>` | `<Callout type="note">` |
| `<Warning>` | `<Callout type="warning">` |
| `<Tip>` | `<Callout type="tip">` |
| `<Info>` | `<Callout type="info">` |
| `<Check>` | `<Callout type="check">` |

**Mintlify Syntax**

```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>
    ```
  **HolyDocs Syntax**

```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.

| Component | Props | Status |
|---|---|---|
| `<Card>` | `title`, `icon`, `href` | Fully compatible |
| `<CardGroup>` | `cols` | Fully compatible |
| `<Tabs>` | — | Fully compatible |
| `<Tab>` | `title` | Fully compatible |
| `<Steps>` | — | Fully compatible |
| `<Step>` | `title` | Fully compatible |
| `<Accordion>` | `title` | Fully compatible |
| `<AccordionGroup>` | — | Fully compatible |
| `<CodeGroup>` | — | Fully compatible |
| `<Expandable>` | `title` | Fully compatible |

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.

**Copy your OpenAPI spec**

Place your `openapi.json` or `openapi.yaml` file in your docs directory, same as in Mintlify.
  **Update docs.json**

Set the `openapi` field in `docs.json` to the path of your spec file:

    ```json
    {
      "openapi": "/openapi.json"
    }
    ```
  **Reference endpoints in navigation**

Add OpenAPI endpoint pages to your navigation groups. HolyDocs uses the same `GET /endpoint` format as Mintlify:

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

The API playground is automatically enabled for OpenAPI endpoints. Readers can make live API calls directly from the documentation.

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.

**Remove the Mintlify CNAME**

In your DNS provider, delete the existing CNAME record that points to Mintlify's servers.
  **Add the HolyDocs CNAME**

Create a new CNAME record pointing your documentation domain to `proxy.holydocs.com`:

    | Type | Name | Target |
    |---|---|---|
    | CNAME | docs | proxy.holydocs.com |
  **Add the domain in HolyDocs**

Go to **Settings > Domains** in your HolyDocs project dashboard and enter your custom domain.
  **Wait for SSL provisioning**

HolyDocs automatically provisions an SSL certificate through Cloudflare. This takes 1-5 minutes after DNS verification.

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.

**Validate configuration**

```bash
    holydocs check
    ```

    This checks your `docs.json` for errors, validates page references, and confirms all linked files exist.
  **Preview locally**

```bash
    holydocs dev
    ```

    Open `http://localhost:3333` and navigate through your documentation. Check navigation structure, component rendering, and images.
  **Test search and AI**

Deploy to HolyDocs and verify that search returns relevant results. If you have the AI assistant enabled, ask it a question that requires content from multiple pages.
  **Check OpenAPI endpoints**

If you use OpenAPI, visit an endpoint page and confirm the playground works. Test a sample request.
  **Verify custom domain**

If you transferred a custom domain, visit it in a browser and confirm HTTPS works and the correct content is served.
  **Deploy to production**

```bash
    holydocs deploy
    ```

## Common Issues and Fixes

**'Unknown component' errors in MDX files**

This happens when a Mintlify-specific component was not converted. Search your MDX files for `<Note>`, `<Warning>`, `<Tip>`, `<Info>`, and `<Check>` tags and replace them with the corresponding `<Callout type="...">` syntax. The automatic migration handles this, but manual migrations may miss some occurrences.
  **Navigation structure looks wrong**

Mintlify uses a flat `navigation` array while HolyDocs nests groups under tabs. If you migrated manually, make sure your groups are nested inside `navigation.tabs[].groups` rather than at the top level. See the configuration mapping section above.
  **Images are broken after migration**

Ensure image paths in your MDX files match the actual file locations. HolyDocs uses the same relative path resolution as Mintlify — images referenced as `/images/hero.png` should be at `images/hero.png` relative to your docs root.
  **OpenAPI pages show 'Spec not found'**

Verify the `openapi` path in `docs.json` matches the location of your spec file. The path should be relative to the docs root directory, and the file must be valid JSON or YAML.
  **Custom CSS not applying**

Mintlify's `custom.css` file is not automatically migrated. Copy your custom styles to a `custom.css` file in your docs root and reference it in `docs.json`:

    ```json
    {
      "customCss": "/custom.css"
    }
    ```
  **Redirects are missing**

Mintlify's `redirects` field in `mint.json` maps directly to `redirects` in `docs.json`. If you migrated manually, copy the redirects array to your new config:

    ```json
    {
      "redirects": [
        { "source": "/old-path", "destination": "/new-path" }
      ]
    }
    ```
  **API authentication not working in playground**

Check that `api.auth.method` was renamed to `api.auth.type` in your `docs.json`. The values (`bearer`, `key`, `basic`) remain the same.