Skip to main content
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.

​
Choose where to host your documentation

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.
Subpath hosting is not supported for documentation with authentication enabled.

​
Add your custom domain

  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.

​
Base path requirements

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.

​
Change your base path

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.

​
Configure your DNS

Each domain provider has different ways to add DNS records. Refer to your domain provider’s documentation for specific instructions.
  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.
Add your TXT records first. 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.
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.

​
Apex domains

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, so 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 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

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.

​
Remove a custom domain

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.

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