From 800d62fc18b2e5a9dc2477eeb91adfbc74853f65 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 6 May 2026 06:41:30 +0000 Subject: [PATCH 1/2] docs: document custom domain TXT verification records --- customize/custom-domain.mdx | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/customize/custom-domain.mdx b/customize/custom-domain.mdx index 1a777548d..f0512c59a 100644 --- a/customize/custom-domain.mdx +++ b/customize/custom-domain.mdx @@ -49,15 +49,28 @@ CNAME | docs | cname.mintlify.builders If you migrate an existing domain and want zero downtime, add the verification `TXT` records before updating your `CNAME`. Then wait until SSL/TLS certificates pre-provision before cutting over. Switching the `CNAME` before certificates are issued causes HTTPS requests to fail until provisioning completes. +### 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. | +TXT | _cf-custom-hostname. | +``` + +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 automatically checks these records and marks each one as configured once it detects the expected value in DNS. Refresh the page after publishing the records to update their status. + ### DNS propagation DNS changes typically take 1-24 hours to propagate globally, though it can take up to 48 hours in some cases. You can verify your DNS is configured correctly using [DNSChecker](https://dnschecker.org). -Once your DNS records are active, your documentation is first accessible via HTTP. HTTPS is available after Vercel provisions your TLS certificate. +Once your DNS records are active, your documentation is first accessible via HTTP. HTTPS is available after your TLS certificate is provisioned. ### Automatic TLS provisioning -Once your DNS records propagate and resolve correctly, Vercel automatically provisions a free SSL/TLS certificate for your domain using Let's Encrypt. +Once your DNS records propagate and the verification `TXT` records resolve correctly, Mintlify automatically provisions a free SSL/TLS certificate for your domain 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. @@ -76,10 +89,6 @@ The `/.well-known/acme-challenge` path is reserved for certificate validation an ### Provider-specific settings - - If Vercel is your domain provider, you must add a verification `TXT` record. This information appears on your dashboard after submitting your custom domain, and is emailed to you. - - 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. From d391349d1f014025d3986516c3d30e5d7fb925d6 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 7 May 2026 15:18:26 -0700 Subject: [PATCH 2/2] copy edit --- customize/custom-domain.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/customize/custom-domain.mdx b/customize/custom-domain.mdx index 26b1ff0f6..6cb14d63a 100644 --- a/customize/custom-domain.mdx +++ b/customize/custom-domain.mdx @@ -46,7 +46,9 @@ CNAME | docs | cname.mintlify.builders - If you migrate an existing domain and want zero downtime, add the verification `TXT` records before updating your `CNAME`. Then wait until SSL/TLS certificates pre-provision before cutting over. Switching the `CNAME` before Mintlify issues certificates causes HTTPS requests to fail until provisioning completes. + 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. ### Verification TXT records @@ -60,7 +62,7 @@ TXT | _cf-custom-hostname. | 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 automatically checks these records and marks each one as configured once it detects the expected value in DNS. Refresh the page after publishing the records to update their status. +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