# Connect a custom domain

A docs site has exactly one public address: a subdomain you own, such as `docs.example.com`. EvoHub does not give sites an address of its own, so until a domain is connected and active, the site is visible only through **Preview** in the console. This page shows how to connect one.

You need permission to manage the site (`docs:site:write`) and access to your domain's DNS.

## Before you start

- Use a **subdomain** with at least three labels, like `docs.example.com`. Apex domains (`example.com`) are not supported.
- One hostname serves one site across EvoHub. A hostname already used by another site or a status page is refused.
- The site's pages show only once the site and the pages are published. You can connect the domain first and publish later.

## Connect the domain

:::steps
### Enter the hostname
Open the site's **Settings**, **Domain**. Under **Your domain**, type the hostname (for example `docs.example.com`) and choose **Connect domain**.

### Add the DNS records
EvoHub shows two records with **Type**, **Name** and **Value**, each with a **Copy** button:

| Type | Name | Value |
| --- | --- | --- |
| CNAME | `_acme-challenge.docs.example.com` | The value shown in the console |
| CNAME | `docs.example.com` | `cname.evohub-dns.com` |

Add the `_acme-challenge` record first and wait for the status to turn green, then add the routing CNAME. That way the domain never goes live without a certificate.

### Wait for validation
Choose **Re-check** to refresh the status. When it shows **Verified · SSL active**, the site is live at `https://docs.example.com`.
:::

> [!TIP]
> If your DNS is proxied through Cloudflare, set SSL to **Full** (not Flexible).

## Domain status

| Status | Meaning |
| --- | --- |
| **Not connected** | No domain yet. |
| **Pending DNS** | The records are not found yet. |
| **Validating** | The records are found and the certificate is being issued. |
| **Verified · SSL active** | The site is live on the domain with a certificate. |
| **Action needed** | The domain stopped being served — usually a record was removed or the certificate expired. |

For **Action needed**, check that both records are still in your DNS exactly as shown, then **Re-check**. If it stays red, remove the domain and connect it again.

Keep both records in place for as long as the site uses the domain. Removing them takes the site off the address.

## What the domain is used for

Everything a reader reaches is on this domain: the pages, search, `llms.txt`, the `.md` copies of pages, the MCP server, sign-in for private sites and change request preview links. Links EvoHub builds for you — a preview link, a test sign-in link — need the domain to be active.

## Change or remove the domain

- To move to a different hostname, connect the new one. It replaces the old one, which stops serving the site.
- **Remove domain** disconnects the hostname. The site stays in the console and keeps its pages.

## Related

- [Docs overview](https://docs-dev.evohub.io/docs-overview.md)
- [Private docs](https://docs-dev.evohub.io/private-docs.md)
- [Custom domain for a status page](https://docs-dev.evohub.io/status-page-custom-domain.md)