Skip to navigation
Configuration

Set up a custom domain

View as Markdown

Admins can use the Fern Dashboard 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, contact Fern to register and verify each one.

Alternatively, you can set up your custom domain by manually configuring DNS records.

Setup

1

Open the Dashboard

Navigate to the Fern Dashboard and select your documentation site.

2

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.

3

Update the domain in docs.yml

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

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.

4

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).

5

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 for your provider (Cloudflare Workers, AWS CloudFront, Netlify, Vercel, Nginx, Akamai, or Caddy). Skip this step for subdomain or root domain hosting.

6

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.

Migrate a domain that points to Vercel

Fern Docs has moved to new hosting. Custom domains set up before the move may still point to Vercel: a CNAME record to vercel-dns.com (for example, b7278b3c9357963d.vercel-dns-013.com) or, for a root domain, an A record to a Vercel IP address such as 76.76.21.21. These domains must point to cname.ferndocs.com instead.

fern generate --docs (including --preview) checks each custom-domain in the docs instance being published. When a domain still points to Vercel, the CLI prints a warning that starts with “Action required by December 1, 2026: your custom domain still points to Vercel.” Starting December 1, 2026, the warning becomes an error and publishing fails until the domain is migrated. Domains served through a reverse proxy or your own CDN, and subpath domains, aren’t affected.

Your docs stay live on the current setup until you change the DNS record.

1

Start the switch

Navigate to the Fern Dashboard, select your documentation site, and select Make the switch.

2

Verify domain ownership

Add the TXT records the Dashboard shows to your DNS provider: one for domain ownership and one for the SSL certificate. The certificate record appears after ownership is verified. Then select Verify TXT records in the Dashboard.

3

Update your CNAME record

Change your domain’s CNAME record to cname.ferndocs.com. For a root domain, use an ALIAS record or a flattened CNAME pointing to cname.ferndocs.com. Return to the Dashboard to confirm the DNS change.

Multi-source settings

For multi-source sites — 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 for the full setup walkthrough.