> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/mintlify/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom domain

> Host your documentation on a custom domain with automatic SSL/TLS certificates.

Host your documentation on your own custom domain instead of the default Mintlify subdomain. Setting up a custom domain involves adding it to your dashboard and configuring DNS records with your domain provider.

<Info>
  Looking to set up a subpath like `example.com/docs`? See [/docs subpath](/deploy/docs-subpath).
</Info>

## Setup overview

<Steps>
  <Step title="Add your domain">
    Add your custom domain in the Mintlify dashboard.
  </Step>

  <Step title="Configure DNS">
    Update DNS settings with your domain provider to point to Mintlify.
  </Step>

  <Step title="Wait for propagation">
    Allow time for DNS propagation and automatic TLS certificate provisioning.
  </Step>
</Steps>

## Add your custom domain

<Steps>
  <Step title="Navigate to dashboard">
    Go to the [Custom domain setup](https://dashboard.mintlify.com/settings/deployment/custom-domain) page in your Mintlify dashboard.
  </Step>

  <Step title="Enter domain name">
    Enter your domain name (for example, `docs.example.com` or `www.example.com`) and click **Add domain**.
  </Step>
</Steps>

<Frame>
  <img alt="The Custom domain setup page showing the field to enter your custom domain URL." className="block dark:hidden" src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify-docs/images/domain/add-custom-domain-light.png" />

  <img alt="The Custom domain setup page showing the field to enter your custom domain URL." className="hidden dark:block" src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify-docs/images/domain/add-custom-domain-dark.png" />
</Frame>

## Configure DNS settings

<Steps>
  <Step title="Access DNS settings">
    Log in to your domain provider's website and navigate to your domain's DNS settings.
  </Step>

  <Step title="Create CNAME record">
    Create a new DNS record with the following values:

    ```text theme={null}
    CNAME | docs | cname.mintlify-dns.com.
    ```
  </Step>
</Steps>

<Tip>
  Each domain provider has different ways to add DNS records. Refer to your domain provider's documentation for specific instructions.
</Tip>

### 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](https://dnschecker.org).

Once your DNS records are active, your documentation is first accessible via HTTP. HTTPS is available after Vercel provisions your TLS certificate.

### Automatic TLS provisioning

Once your DNS records propagate and resolve correctly, Vercel 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.

<Note>
  No manual intervention is required for SSL/TLS certificates. The process is fully automated once DNS is properly configured.
</Note>

### 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:

```text theme={null}
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

<AccordionGroup>
  <Accordion title="Vercel verification">
    If Vercel is your domain provider, you must add a verification `TXT` record. This information appears on your dashboard after submitting your custom domain, and is emailed to you.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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`:

```json docs.json theme={null}
{
  "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:

```json docs.json theme={null}
{
  "seo": {
    "metatags": {
      "canonical": "https://docs.mintlify.com"
    }
  }
}
```

<Tip>
  Setting a canonical URL is especially important if your documentation is accessible from both your custom domain and the default Mintlify subdomain.
</Tip>