> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-mintlify-0dbda2de.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom domain

> Host your site at your own domain, subdomain, or subpath with DNS records, automatic TLS certificates, and Mintlify-managed or proxy traffic routing.

Host your documentation at your own domain, like `docs.example.com`, or at a subpath on your domain, like `example.com/docs`.

To host your documentation on a custom domain:

1. Add your domain in your dashboard.
2. Configure DNS settings on your domain provider.
3. Allow time for DNS to propagate and TLS certificates to be automatically provisioned.

## Choose where to host your documentation

You can host your documentation at the root of a domain, a subdomain, or a subpath.

**Domain or subdomain**: Host your documentation at a domain like `example.com` or a subdomain like `docs.example.com`. Mintlify serves all traffic for the domain or subdomain. Hosting at a domain with no subdomain requires a DNS provider that supports CNAME flattening or `ALIAS` records. See [Apex domains](#apex-domains).

**Subpath**: Host your documentation at a path on your domain, like `example.com/docs`. Enable the **Host at** toggle when you add your domain and enter your base path. How traffic reaches Mintlify depends on your DNS:

* If your domain's DNS points to Mintlify, Mintlify serves your documentation at your subpath. Only point your domain at Mintlify if it hosts no other content and Mintlify can receive all paths on the domain.
* If another site runs on your domain, your app or CDN keeps receiving traffic for the domain and proxies only your subpath to Mintlify.

<Note>
  Subpath hosting is not supported for documentation with [authentication](/deploy/authentication-setup) enabled.
</Note>

## Add your custom domain

1. Navigate to the [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) page in your dashboard.
2. To host at a subpath, enable the **Host at** toggle and enter your base path, like `/docs`.
3. Enter your domain name. For example, `docs.example.com` or `example.com`.
4. Click **Add domain**.

If your domain traffic routes to Mintlify, the dashboard displays the DNS records to add at your domain provider.

If you proxy only your subpath to Mintlify, the dashboard displays reverse proxy setup guides instead. Follow the guide for your provider and see [Host docs at a subpath](/deploy/docs-subpath) for more information.

### Base path requirements

Your base path can be any path that meets these requirements:

* Starts with `/` and contains no spaces, query strings, or hashes.
* Is at most 128 characters.
* Is not a path that Mintlify reserves: `/_next`, `/_mintlify`, `/_sites`, `/_live-preview`, `/api`, `/login`, `/logout`, `/mcp`, `/feedback`, `/openapi-specs.download`, `/llms.txt`, `/llms-full.txt`, `/sitemap.xml`, `/robots.txt`, `/skill.md`, and `/.well-known`.

### Change your base path

When you change your base path or subpath, Mintlify rebuilds and redeploys your site. Your site stays live at the current path until the deployment finishes, then traffic switches to the new path. If the deployment fails, your site continues serving from the current path and you can retry the change from your dashboard.

## Configure your DNS

<Tip>
  Each domain provider has different ways to add DNS records. Refer to your domain provider's documentation for specific instructions.
</Tip>

1. On your domain provider's website, navigate to your domain's DNS settings.
2. Create the DNS records shown in your dashboard.

The dashboard displays verification `TXT` records and a `CNAME` record:

```text theme={null}
TXT | _acme-challenge.<your-domain> | <value shown in your dashboard>
TXT | _cf-custom-hostname.<your-domain> | <value shown in your dashboard>
CNAME | <your-domain> | cname.mintlify.builders
```

The `_acme-challenge` record authorizes Let's Encrypt to issue a TLS certificate for your domain, and the `_cf-custom-hostname` record verifies that you control the domain.

<Warning>
  Add your `TXT` records first. Do not add or change your `CNAME` until both verification `TXT` records show as verified in your dashboard. Each appears with a green check when DNS is correct. The dashboard verifies `TXT` records before certificate provisioning can complete. Switching `CNAME` too early commonly breaks HTTPS until provisioning finishes.

  If you migrate an existing domain and want zero downtime, publish the verification `TXT` records first and wait until they show verified and TLS has pre-provisioned before pointing `CNAME` at Mintlify.

  This pre-validation flow does not work for domains proxied through Cloudflare. See [Cloudflare-proxied domains](#cloudflare-proxied-domains).
</Warning>

The dashboard polls DNS in the background and marks each record with a green check once it verifies the expected value. After saving records at your DNS provider, allow a short time for propagation before status updates appear.

### Apex domains

If you host your documentation at an apex domain like `example.com` with no subdomain, your DNS provider must support CNAME flattening or a virtual record type like `ALIAS` or `ANAME`. Standard DNS does not allow a `CNAME` record at the apex of a domain, so providers without this support cannot create the record shown in your dashboard.

Providers that support apex `CNAME` records include Cloudflare (CNAME flattening), Amazon Route 53 (alias records), DNSimple (`ALIAS` records), and Porkbun (`ALIAS` records). If your provider does not support any of these, host your documentation at a subdomain like `docs.example.com` instead.

### DNS propagation

DNS changes typically take 1-24 hours to propagate globally, though it can take up to 48 hours in some cases. Use a tool like [DNSChecker](https://dnschecker.org) to verify your DNS configuration is correct.

Once your DNS records are active, your documentation is first accessible via HTTP. HTTPS is available after Mintlify provisions your TLS certificate.

### Automatic TLS provisioning

After you add your `TXT` records and your DNS records resolve correctly, Mintlify generates a free SSL/TLS certificate for your site using Let's Encrypt.

This typically completes within a few hours of DNS propagation, though it can take up to 24 hours in rare cases. Certificates are automatically renewed before expiration.

### CAA records

If your domain uses CAA (Certification Authority Authorization) records, you must authorize Let's Encrypt to issue certificates for your domain. Add the following CAA record to your DNS settings:

```text theme={null}
0 issue "letsencrypt.org"
```

### Reserved paths

Mintlify reserves the `/.well-known/acme-challenge` path for certificate validation. You cannot redirect or rewrite this path. If you have configured redirects or rewrites for this path, certificate provisioning fails.

### Cloudflare-proxied domains

If your domain is already proxied through Cloudflare (the proxy status shows an orange cloud), the verification `TXT` records cannot show as verified before you update your `CNAME`. This happens even when the records resolve correctly with tools like `dig` or DNSChecker. Cloudflare's proxy prevents the verification from completing until traffic for the hostname routes to Mintlify.

For Cloudflare-proxied domains, follow these steps:

1. Add the verification `TXT` records at your DNS provider.
2. Update your `CNAME` record to point to `cname.mintlify.builders` without waiting for the `TXT` records to show as verified.
3. Wait for verification and TLS provisioning to complete. Your site may briefly serve an invalid certificate during provisioning.

If you need zero downtime during migration, set the `CNAME` record's proxy status to **DNS only** (gray cloud) instead. This allows the standard pre-validation flow to complete before you switch traffic.

### Provider-specific settings

<Accordion title="Cloudflare encryption mode">
  If Cloudflare is your DNS provider, you must enable the "Full (strict)" mode for the SSL/TLS encryption setting. Additionally, disable "Always Use HTTPS" in your Edge Certificates settings. Cloudflare's HTTPS redirect blocks Let's Encrypt from validating your domain during certificate provisioning.
</Accordion>

### Retry validation

`TXT` records typically validate within five minutes. If your domain is still pending validation after adding the verification `TXT` records, manually retry validation from your dashboard.

1. Navigate to the [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) page in your dashboard.
2. Find your pending custom domain.
3. Click **Retry validation**.

Only retry validation after you confirm that your DNS records are correct. Repeated retries with incorrect records do not speed up validation.

## Remove a custom domain

To remove a custom domain, click the <Icon name="trash-2" /> remove icon next to your domain on the [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) page and confirm the removal. Existing links to the domain may break, and re-adding the domain may require reconfiguring your DNS records.

## Set a canonical URL

After configuring your DNS, set a canonical URL to ensure search engines index your preferred domain. A canonical URL tells search engines which version of your documentation is the primary one. This improves SEO when your documentation is accessible from multiple URLs and prevents issues with duplicate content.

Add the `canonical` meta tag to your `docs.json`:

```json theme={null}
"seo": {
    "metatags": {
        "canonical": "https://www.your-custom-domain-here.com"
    }
}
```

Replace `https://www.your-custom-domain-here.com` with your actual custom domain. For example, if your custom domain is `docs.mintlify.com`, you would use:

```json theme={null}
"seo": {
    "metatags": {
        "canonical": "https://docs.mintlify.com"
    }
}
```