Custom domain

Host your site at your own domain, subdomain, or subpath with DNS records, automatic TLS certificates, and Mintlify-managed or proxy traffic routing.

Host your documentation at your own domain, like docs.example.com, or at a subpath on your domain, like example.com/docs.

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.

You can host your documentation at the root of a domain, a subdomain, or a subpath.

Domain or subdomain: Host your documentation at a domain like example.com or a subdomain like docs.example.com. Mintlify serves all traffic for the domain or subdomain. Hosting at a domain with no subdomain requires a DNS provider that supports CNAME flattening or ALIAS records. See Apex domains.

Subpath: Host your documentation at a path on your domain, like example.com/docs. Enable the Host at toggle when you add your domain and enter your base path. How traffic reaches Mintlify depends on your DNS:

• If your domain's DNS points to Mintlify, Mintlify serves your documentation at your subpath. Only point your domain at Mintlify if it hosts no other content and Mintlify can receive all paths on the domain.
• If another site runs on your domain, your app or CDN keeps receiving traffic for the domain and proxies only your subpath to Mintlify.

1. Navigate to the Custom domain setup page in your dashboard.
2. To host at a subpath, enable the Host at toggle and enter your base path, like /docs.
3. Enter your domain name. For example, docs.example.com or example.com.
4. Click Add domain.

If your domain traffic routes to Mintlify, the dashboard displays the DNS records to add at your domain provider.

If you proxy only your subpath to Mintlify, the dashboard displays reverse proxy setup guides instead. Follow the guide for your provider and see Host docs at a subpath for more information.

Your base path can be any path that meets these requirements:

• Starts with / and contains no spaces, query strings, or hashes.
• Is at most 128 characters.
• Is not a path that Mintlify reserves: /_next, /_mintlify, /_sites, /_live-preview, /api, /login, /logout, /mcp, /feedback, /openapi-specs.download, /llms.txt, /llms-full.txt, /sitemap.xml, /robots.txt, /skill.md, and /.well-known.

When you change your base path or subpath, Mintlify rebuilds and redeploys your site. Your site stays live at the current path until the deployment finishes, then traffic switches to the new path. If the deployment fails, your site continues serving from the current path and you can retry the change from your dashboard.

1. On your domain provider's website, navigate to your domain's DNS settings.
2. Create the DNS records shown in your dashboard.

The dashboard displays verification TXT records and a CNAME record:

TXT | _acme-challenge.<your-domain> | <value shown in your dashboard>
TXT | _cf-custom-hostname.<your-domain> | <value shown in your dashboard>
CNAME | <your-domain> | cname.mintlify.builders

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.

If you host your documentation at an apex domain like example.com with no subdomain, your DNS provider must support CNAME flattening or a virtual record type like ALIAS or ANAME. Standard DNS does not allow a CNAME record at the apex of a domain. Providers without this support cannot create the record shown in your dashboard.

Providers that support apex CNAME records include Cloudflare (CNAME flattening), Amazon Route 53 (alias records), DNSimple (ALIAS records), and Porkbun (ALIAS records). If your provider does not support any of these, host your documentation at a subdomain like docs.example.com instead.

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.

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.

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"

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.

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.

TXT records typically validate within five minutes. If your domain is still pending validation after adding the verification TXT records, manually retry validation 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.

To remove a custom domain, click the remove icon next to your domain on the Custom domain setup page and confirm the removal. Existing links to the domain may break, and re-adding the domain may require reconfiguring your DNS records.

Removing a domain also releases it so another Mintlify project or organization can claim it. If you cannot add a domain because another project holds it, see Add domain fails with "Domain is already claimed by another organization".

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

• Glossary
• Deploy at a subpath with Cloudflare Workers
• Deploy at a subpath with Vercel