> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.

# Set up a custom domain

> Use the Fern Dashboard to configure your custom domain with DNS records for subdomain, subpath, or root domain hosting.

[Admins](/learn/dashboard/configuration/permissions) can use the [Fern Dashboard](https://dashboard.buildwithfern.com/) to configure any of the following custom domain types:

* **Subdomain**: `docs.mydomain.com`
* **Subpath**: `mydomain.com/docs`
* **Root domain**: `mydomain.com`

The Dashboard automatically provides the correct DNS records based on your domain type. It verifies one custom domain per docs site; to serve [additional domains or aliases](/learn/docs/preview-publish/setting-up-your-domain#multiple-custom-domains), contact Fern to register and verify each one.

Alternatively, you can [set up your custom domain by manually configuring DNS records](/learn/docs/preview-publish/setting-up-your-domain).

## Setup

#### Open the Dashboard

Navigate to the [Fern Dashboard](https://dashboard.buildwithfern.com/) and select your documentation site.

#### Add your custom domain

In the **Domains** section of the **Overview** tab, select **Add Custom Domain** and enter your domain. The dashboard displays the DNS records you need to configure.

#### Update the domain in \`docs.yml\`

Add your `custom-domain` to your `docs.yml` configuration:

**`docs.yml`**

```yaml docs.yml
instances:
  - url: example.docs.buildwithfern.com
    custom-domain: docs.mydomain.com
```

For subpath hosting, the `url` and `custom-domain` must share the same basepath (e.g. `/docs`). `fern check` and publishing fail when the basepaths differ.

#### Configure DNS records

Log in to your domain registrar and add the DNS records shown in the Fern Dashboard. The specific records depend on your domain type (subdomain, subpath, or root domain).

#### Set up a reverse proxy (subpath only)

Subpath hosting needs more than DNS — your infrastructure has to forward requests from the subpath to Fern's origin with the `x-fern-host` header set to your bare domain. Follow the [reverse proxy setup instructions](/learn/docs/preview-publish/reverse-proxy) for your provider (Cloudflare Workers, AWS CloudFront, Netlify, Vercel, Nginx, Akamai, or Caddy). Skip this step for subdomain or root domain hosting.

#### Verify the setup

Once you've added the DNS records, return to the Fern Dashboard to verify your domain. SSL is automatically provisioned for your domain, but it may take a few minutes to propagate globally.

Check that you can access your new docs site from a mobile device or incognito browser.

## Multi-source settings

For [multi-source sites](/learn/docs/preview-publish/multi-source-docs) — where multiple repositories publish to the same custom domain on different sub-paths — the Dashboard exposes a **Multi-repo settings** card on the domain's **Settings** tab. These settings apply to the whole domain, not per sub-path.

The card configures:

* **Default path** — sets where users land at the bare root of the domain. Useful when a Fern-managed page serves as the root.
* **Search / Ask AI scope** — controls whether searches in one sub-path return results across all sub-paths (unified) or stay scoped to that sub-path (hierarchical).

See [Multi-source docs](/learn/docs/preview-publish/multi-source-docs) for the full setup walkthrough.

> Use the Fern Dashboard to configure your custom domain with DNS records for subdomain, subpath, or root domain hosting.