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.

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:

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

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

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

The /.well-known/acme-challenge path is reserved for certificate validation and cannot be redirected or rewritten. If you have configured redirects or rewrites for this path, certificate provisioning fails.

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.

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