diff --git a/customize/custom-domain.mdx b/customize/custom-domain.mdx index d54a84037..eb5c05a2d 100644 --- a/customize/custom-domain.mdx +++ b/customize/custom-domain.mdx @@ -49,6 +49,8 @@ CNAME | docs | cname.mintlify.builders 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). ### Verification TXT records @@ -88,6 +90,18 @@ If your domain uses CAA (Certification Authority Authorization) records, you mus 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