Skip to content

docs: document custom domain TXT verification records #5678

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ethanpalm merged 3 commits into from
May 7, 2026
+19 −10
Merged

docs: document custom domain TXT verification records #5678

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
800d62f
docs: document custom domain TXT verification records
mintlify[bot] May 6, 2026
01268c9
Merge branch 'main' into mintlify/233ace88
ethanpalm May 7, 2026
d391349
copy edit
ethanpalm May 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 19 additions & 10 deletions customize/custom-domain.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,12 +46,27 @@
</Tip>

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

### Verification TXT records

Check warning on line 54 in customize/custom-domain.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/custom-domain.mdx#L54 

'Verification TXT records' should use sentence-style capitalization.

Check warning on line 54 in customize/custom-domain.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/custom-domain.mdx#L54 

Spell out 'TXT', if it's unfamiliar to the audience.

Check warning on line 54 in customize/custom-domain.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/custom-domain.mdx#L54 

Use 'txt' instead of 'TXT'.

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. You can verify your DNS is configured correctly using [DNSChecker](https://dnschecker.org).

Check warning on line 69 in customize/custom-domain.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/custom-domain.mdx#L69 

In general, use active voice instead of passive voice ('is configured').

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

Expand All @@ -75,15 +90,9 @@

### Provider-specific settings

<AccordionGroup>
<Accordion title="Vercel verification">
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 Mintlify emails it to you.
</Accordion>

Comment thread
cursor[bot] marked this conversation as resolved.
<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>
</AccordionGroup>
<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>

## Set a canonical URL

Expand Down
Loading