---
title: Custom domain
description: Connect a custom domain and verify DNS and certificate readiness.
---

Use a custom domain when readers should access your docs from your own domain,
such as `docs.example.com`.

Custom domains are available on the Free and Pro plans. Each docs site can have
one custom domain. Only organization owners can add or remove it.

## Supported domain patterns

| Pattern                   | Example            | How Radiant handles it                                        |
| ------------------------- | ------------------ | ------------------------------------------------------------- |
| Subdomain                 | `docs.example.com` | Radiant provides a CNAME target and manages SSL readiness     |
| Public docs URL with path | `example.com/docs` | Radiant stores the public URL for display and routing context |

Root domains such as `example.com` are not supported yet for Radiant-managed
custom domains. Use a subdomain such as `docs.example.com`.

<Callout type="info" title="Paths are different from DNS records">
  DNS records point hostnames to Radiant. A URL with a path, such as
  `example.com/docs`, usually requires your own routing or reverse proxy in
  front of Radiant.
</Callout>

## Add a managed subdomain

<Steps>
  <Step title="Open the domain settings">
    In the Radiant dashboard, open the domain settings for your docs project.
  </Step>

<Step title="Enter your docs URL">
  Enter the docs subdomain you want readers to use, such as `docs.example.com`,
  and select **Set docs URL**.
</Step>

<Step title="Add the CNAME record">
  Radiant shows the CNAME record to add at your DNS provider. Add that record
  for the subdomain.
</Step>

  <Step title="Return to Radiant">
    Go back to the dashboard and check the domain status. DNS and certificate
    readiness can take time to propagate.
  </Step>
</Steps>

## Host docs at a subpath

Use a pathname URL when your docs should appear alongside your existing site,
such as `example.com/docs`. Your hosting setup must be able to proxy requests
for that path to Radiant.

<Steps>
  <Step title="Enter the public docs URL">
    Enter the complete hostname and path, such as `example.com/docs`, and
    select **Set docs URL**. Radiant recognizes the path and starts a build
    configured for it.
  </Step>

<Step title="Copy the Radiant target">
  The dashboard displays a stable Radiant target for the docs site. Copy the
  generated target rather than the example placeholder below.
</Step>

<Step title="Configure the proxy">
  Route both the exact path and every URL below it to the corresponding URL on
  the Radiant target without redirecting visitors.
</Step>

  <Step title="Check the setup">
    Return to the dashboard after the docs build finishes and select **Check
    setup**. Radiant verifies that the public URL reaches the correct docs site.
  </Step>
</Steps>

For a public URL of `https://example.com/docs` and a generated target of
`https://SITE_ID.radiantdocs.com/docs`, the configuration looks like this:

Use the **Vercel** configuration when your website is deployed on Vercel,
regardless of its framework. Use the **Next.js** configuration when a running
Next.js server handles your website's routing. Next.js rewrites do not run in a
static export.

<CodeGroup>
```json title="Vercel"
{
  "rewrites": [
    {
      "source": "/docs",
      "destination": "https://SITE_ID.radiantdocs.com/docs"
    },
    {
      "source": "/docs/:path*",
      "destination": "https://SITE_ID.radiantdocs.com/docs/:path*"
    }
  ]
}
```

```ts title="Next.js"
export default {
  async rewrites() {
    return [
      {
        source: "/docs",
        destination: "https://SITE_ID.radiantdocs.com/docs",
      },
      {
        source: "/docs/:path*",
        destination: "https://SITE_ID.radiantdocs.com/docs/:path*",
      },
    ];
  },
};
```

```js title="Cloudflare Worker"
export default {
  async fetch(request) {
    const url = new URL(request.url);

    if (url.pathname === "/docs" || url.pathname.startsWith("/docs/")) {
      url.protocol = "https:";
      url.hostname = "SITE_ID.radiantdocs.com";
      return fetch(new Request(url, request));
    }

    return fetch(request);
  },
};
```

```nginx title="nginx"
location = /docs {
  proxy_set_header Host SITE_ID.radiantdocs.com;
  proxy_ssl_server_name on;
  proxy_ssl_name SITE_ID.radiantdocs.com;
  proxy_pass https://SITE_ID.radiantdocs.com/docs;
}

location /docs/ {
  proxy_set_header Host SITE_ID.radiantdocs.com;
  proxy_ssl_server_name on;
  proxy_ssl_name SITE_ID.radiantdocs.com;
  proxy_pass https://SITE_ID.radiantdocs.com;
}
```

</CodeGroup>

Your existing website continues to manage DNS and TLS for its hostname. Radiant
does not create a DNS record or certificate for a pathname URL.

## Managed domain status

| Status  | Meaning                                             |
| ------- | --------------------------------------------------- |
| Pending | Radiant is waiting for DNS or certificate readiness |
| Active  | The custom domain is ready for readers              |
| Failed  | Radiant could not activate the domain               |

When a managed domain becomes Active, readers can use it to access the docs
site. Pathname URLs display their build and proxy status separately in the
dashboard.

## Change or remove a domain

Organization owners can remove the current custom domain from the dashboard.
After removal, the docs site continues to be available from its Radiant-hosted
URL unless the project is otherwise unpublished or deleted.

To switch domains, remove the current domain and add the new one.

## Common questions

<AccordionGroup>
  <Accordion title="Can I use a root domain like example.com?">
    Not yet. Use a subdomain such as `docs.example.com` for a Radiant-managed
    custom domain.
  </Accordion>

<Accordion title="Why is my domain still pending?">
  Pending usually means DNS or certificate readiness has not completed yet.
  Confirm the CNAME record matches the value shown in Radiant, then check the
  status again after propagation.
</Accordion>

<Accordion title="Who can add a custom domain?">
  Organization owners can add or remove custom domains. Each docs site can have
  one custom domain.
</Accordion>

  <Accordion title="What happens if I enter a URL with a path?">
    Radiant builds the docs for that path and displays a generated Radiant
    target with proxy configuration examples. Your website must forward the
    path to Radiant before it becomes active.
  </Accordion>
</AccordionGroup>

## Next steps

<Columns columns={2}>
  <Column>

<Card
  title="Deployments"
  href="/publish-and-manage/deployments"
  icon="lucide:cloud-upload"
>
  Watch changes go live.
</Card>

  </Column>
  <Column>

<Card
  title="Billing and usage"
  href="/publish-and-manage/billing-and-usage"
  icon="lucide:credit-card"
>
  Check plan access.
</Card>

  </Column>
</Columns>