mintlify__docs/customize/custom-domain.mdx

---
title: "Custom domain"
description: "Host your documentation on a custom domain with DNS configuration, automatic TLS certificates, and subdomain or subpath routing options."
keywords: ["custom domain setup", "DNS configuration", "CNAME records", "TLS certificates"]
---

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.

<Info>
  Looking to set up a subpath like `example.com/docs`? See [/docs subpath](/deploy/docs-subpath).
</Info>

## Add your custom domain

1. Navigate to the [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) page in your dashboard.
2. Enter your domain name. For example, `docs.example.com` or `www.example.com`.
3. Click **Add domain**.

<Frame>
  <img
    alt="The Custom domain setup page showing the field to enter your custom domain URL."
    className="block dark:hidden"
    src="/images/domain/add-custom-domain-light.png"
  />
  <img
    alt="The Custom domain setup page showing the field to enter your custom domain URL."
    className="hidden dark:block"
    src="/images/domain/add-custom-domain-dark.png"
  />
</Frame>

## Configure your DNS

1. On your domain provider's website, navigate to your domain's DNS settings.
2. Create a new DNS record with the following values:

```text
CNAME | docs | cname.mintlify.builders
```

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

<Warning>
  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.
</Warning>

### Verification TXT records

After you add a custom domain, the dashboard displays two `TXT` records that you must add at your DNS provider:

```text
TXT | _acme-challenge.<your-domain> | <value shown in your dashboard>
TXT | _cf-custom-hostname.<your-domain> | <value shown in your dashboard>
```

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.

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.

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

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

If your domain is still pending validation after adding the verification `TXT` record, you can retry validation manually 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.

## 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
"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
"seo": {
    "metatags": {
        "canonical": "https://docs.mintlify.com"
    }
}
```