Custom domain

Host your documentation on a custom domain with DNS configuration, automatic TLS certificates, and subdomain or subpath routing options.

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.

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

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.

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.

Manage an existing custom domain

After your custom domain is live, you may need to change hosts, re-verify DNS, serve documentation across multiple domains, or decommission the domain.

Change or replace a custom domain

To move your documentation to a different custom domain, for example from www.example.com to docs.example.com:

1. Navigate to the Custom domain setup page in your dashboard.
2. Remove the existing custom domain.
3. Add the new domain and follow the DNS configuration steps for it.
4. After the new domain is verified and serving traffic, remove the old CNAME and verification TXT records at your DNS provider.

If you want zero downtime during the switch, keep the previous domain configured until the new domain shows as verified and TLS provisioning is complete. Then add a redirect at your DNS or hosting provider from the old hostname to the new one.

Only one primary custom domain is supported per project. To serve documentation on additional hostnames, see Serve documentation across multiple domains.

Re-verify when TXT values change

The dashboard regenerates the _acme-challenge and _cf-custom-hostname TXT values under some conditions, including when you remove and re-add the domain, when you click Retry validation after a long delay, or when the underlying certificate order expires.

If verification is failing, always copy the values that are currently displayed in the dashboard rather than reusing values you saved earlier. Stale TXT values do not verify.

1. Open the Custom domain setup page and copy the TXT values that are currently shown.
2. At your DNS provider, replace any earlier _acme-challenge.<your-domain> and _cf-custom-hostname.<your-domain> records with the current values.
3. Wait for DNS propagation, then click Retry validation.

If you have removed and re-added the same domain and validation is still failing, delete both TXT records at your DNS provider, wait for propagation, and re-add the values that the dashboard shows after the re-add.

Serve documentation across multiple domains

A single Mintlify project serves content from one primary custom domain. To make your documentation reachable from more than one hostname, choose one of the following patterns.

• Redirect additional domains to your primary domain. Configure a permanent redirect (HTTP 301) at your DNS or hosting provider from each additional hostname to your primary custom domain. This is the recommended pattern when you only need alternate URLs to resolve, and it preserves SEO through your canonical URL.
• Serve different content per domain with multi-repository deployments. Multi-repository deployments let you combine multiple content sources under one project, with a dedicated URL path per source. Multi-repository deployments require an Enterprise plan.
• Route with an external reverse proxy. Use a Cloudflare Worker, Vercel rewrites, or a custom reverse proxy to serve documentation at subpaths of different domains, for example example.com/docs and example.io/docs. The proxy is responsible for routing each hostname to mintlify.site.

Release a custom domain

To stop serving documentation from a custom domain and revert to your <subdomain>.mintlify.app URL:

1. Navigate to the Custom domain setup page in your dashboard.
2. Remove the custom domain.
3. At your DNS provider, delete the CNAME record and the _acme-challenge and _cf-custom-hostname TXT records for the hostname.

After the domain is removed from your dashboard, Mintlify stops serving traffic for it and does not renew the TLS certificate. If you plan to reuse the same hostname on another platform, wait for DNS to propagate before pointing it elsewhere.

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"
    }
}