Skip to main content
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.
Looking to set up a subpath like example.com/docs? See /docs subpath.

​
Add your custom domain

  1. Navigate to the Custom domain setup page in your dashboard.
  2. Enter your domain name. For example, docs.example.com or www.example.com.
  3. Click Add domain.
The Custom domain setup page showing the field to enter your custom domain URL.

​
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:
CNAME | docs | cname.mintlify.builders
Each domain provider has different ways to add DNS records. Refer to your domain provider’s documentation for specific instructions.
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.

​
Verification TXT records

After you add a custom domain, the dashboard displays two TXT records that you must add at your DNS provider: 
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 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: 
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

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.

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

​
Limitations and lifecycle

Custom domains have a few lifecycle constraints that are not obvious during setup. Review these before you migrate a production site.

​
The default .mintlify.site subdomain is permanent

The <subdomain>.mintlify.site URL is assigned when the deployment is first created and cannot be changed later. Renaming your project or organization only updates the display name in the dashboard; it does not rename the URL. If you push to a deployment whose display name no longer matches the original subdomain, requests to preview URLs can return a Disallowed origin host error until the site rebuilds against the original subdomain. To change the .mintlify.site subdomain, you must:
  1. Back up any content and settings you want to keep. Deleting a deployment removes everything associated with it.
  2. Delete the deployment from the Danger zone. See Delete a deployment.
  3. Create a new deployment and enter the desired name during setup.

​
The default subdomain stays live after adding a custom domain

Once a custom domain is verified, your documentation is served from both the custom domain and the original <subdomain>.mintlify.site URL. The default subdomain cannot currently be disabled, and there is no automatic redirect from it to your custom domain. To consolidate on the custom domain in search results, set a canonical URL so search engines index the custom domain as the primary version.

​
One primary custom domain per project

Mintlify serves each documentation project from a single primary custom domain. Pointing multiple hostnames (for example, developers.example.com and docs.example.com) at the same project through the dashboard is not supported. If you need multiple hostnames or multiple projects under one domain, choose the option that fits your setup:
  • Multiple hostnames for one project: Configure a self-managed reverse proxy (for example, Cloudflare Workers) in front of Mintlify so each hostname rewrites to the primary custom domain. See Reverse proxy.
  • Multiple projects under one domain as subpaths: Use a multi-repository deployment to combine several repositories into one site with dedicated URL paths. Multi-repository deployments are available on Enterprise plans.
  • Docs under a subpath of an existing site: See Host docs at a /docs subpath.

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