> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. # Bring your custom domain > Learn how to set up your Fern-generated documentation site to use a custom subdomain or subpath. You can configure any of the following custom domain types: * **Subdomain**: `docs.mydomain.com` * **Subpath**: `mydomain.com/docs` * **Root domain**: `mydomain.com` Fern recommends [using the Fern Dashboard to set up custom domains](/learn/dashboard/configuration/custom-domains). The Dashboard automatically provides the correct DNS records based on your domain type. If you prefer to configure your domain manually, follow the instructions on this page. ## Manual setup Expand the section below that matches your domain type: #### Subdomain To host your documentation on a subdomain like `docs.mydomain.com`, you need to create a CNAME record in your DNS settings. #### Update the domain in \`docs.yml\` Add your `custom-domain` and merge your changes into `main`. [Here's an example](https://github.com/octoml/fern-config/blob/389b67679953856ba0716537981a6d749635556f/fern/docs.yml#L1-L3). **`docs.yml`** ```yaml docs.yml instances: - url: example.docs.buildwithfern.com custom-domain: docs.mydomain.com ``` #### Contact Fern Contact Fern via your dedicated Slack channel or [email](mailto:support@buildwithfern.com) to receive: * A unique CNAME value for your site * A TXT record to verify your domain #### Create DNS records Log in to your domain registrar's dashboard and navigate to the DNS settings for your domain. Add the following records: #### CNAME Record (Subdomain) ``` Type Name Value CNAME docs b7278b3c9357963d.vercel-dns-013.com ``` #### TXT Record (Domain Verification) ``` Type Name Value TXT @ [TXT record value provided by Fern] ``` Replace `docs` with any subdomain you want to use. #### Cloudflare users If you are using Cloudflare, you should ensure the record isn't proxied. #### Verify the setup Once Fern has completed your setup, you'll be able to access your documentation at `docs.mydomain.com`. SSL will be 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. #### Subpath To host your documentation on a subpath like `mydomain.com/docs`, you need to edit your `docs.yml` configuration and set up a reverse proxy on your infrastructure. #### Configure the \`url\` in \`docs.yml\` Append that subpath to the end of the `url`. This example use `docs` for the subpath, but you can use any word you like, such as `reference` or `developer`. #### docs.yml ```yaml instances: - url: example.docs.buildwithfern.com/docs ``` #### Configure the \`custom-domain\` Below the `url`, add a `custom-domain` key: #### docs.yml ```yaml instances: - url: example.docs.buildwithfern.com/docs custom-domain: mydomain.com/docs ``` [Here's an example.](https://github.com/fern-api/fern/blob/7d8631c6119787a8aaccb4ba49837e73c985db28/fern/docs.yml#L1-L3) The `url` and `custom-domain` must share the same basepath (here, `/docs`). Navigation links and redirects are generated relative to the `url` basepath, so a mismatched `custom-domain` basepath breaks those links after DNS cutover. `fern check` and publishing fail when the basepaths differ. #### Set up a reverse proxy A subpath can't be routed with DNS alone — your infrastructure has to forward requests from `mydomain.com/docs` 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). #### Contact Fern Contact Fern via your dedicated Slack channel or [email](mailto:support@buildwithfern.com) to set up your custom subpath. #### Verify the setup Once Fern has completed your setup, you'll be able to access your documentation at `mydomain.com/docs`. It may take a few minutes for DNS changes to propagate globally. Try accessing your new docs site from a mobile device or incognito browser to confirm everything is working. #### HTTP/2 transfer errors with nginx If you see partial page loads or HTTP/2 transfer errors, nginx's lack of native [Brotli](https://github.com/google/brotli) support may be the cause. Fern's CDN serves Brotli-compressed responses by default, which nginx can't decode when proxying upstream. Add this directive to your nginx config to request only supported encodings: ```nginx proxy_set_header Accept-Encoding "gzip,deflate"; ``` #### Root domain To host your documentation on a root domain like `mydomain.com`, you need to edit your `docs.yml` configuration and configure DNS records. #### Configure the \`url\` in \`docs.yml\` #### docs.yml ```yaml instances: - url: example.docs.buildwithfern.com custom-domain: www.mydomain.com ``` [Here's an example.](https://github.com/dannysheridan/katiedanny/blob/2fcf5769e2994af29e31d00904e04788b188a18b/fern/docs.yml#L3-L5) #### Contact Fern Contact Fern via your dedicated Slack channel or [email](mailto:support@buildwithfern.com) to receive: * A unique CNAME value for your site * A TXT record to verify your domain #### Configure your DNS settings You'll need the following DNS records configured for your root domain. #### CNAME Record (WWW Subdomain) ``` Type Name Value CNAME www b7278b3c9357963d.vercel-dns-013.com ``` #### A Record (Apex Domain) ``` Type Name Value A @ 76.76.21.21 ``` #### TXT Record (Domain Verification) ``` Type Name Value TXT @ [TXT record value provided by Fern] ``` This redirects `mydomain.com` to `www.mydomain.com`. After you add these records, Fern will provision a SSL certificate. #### Verify the setup Once Fern has completed your setup, you'll be able to access your documentation at `mydomain.com`. SSL will be 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. ### Common errors Errors below are surfaced by `fern check` and `fern generate --docs` when validating the `instances[].url` values in `docs.yml`. #### Invalid URL format: "X". Expected format: \.docs.buildwithfern.com The `url` is missing a subdomain or uses an unexpected shape. Use `.docs.buildwithfern.com` (for example, `plantstore.docs.buildwithfern.com`). Don't include `https://`. #### Invalid domain in URL "X". The URL must end with one of: docs.buildwithfern.com, docs.dev.buildwithfern.com The `url` doesn't end with a supported Fern domain. Update the `url` to end with `docs.buildwithfern.com`. Configure your vanity domain with [`custom-domain`](#multiple-custom-domains). #### Invalid URL "X". A subdomain is required before docs.buildwithfern.com The `url` is set to the bare domain. Add a subdomain prefix such as `.docs.buildwithfern.com`. ### Multiple custom domains To serve your documentation from additional domains or aliases (e.g., for partner or white-label deployments), list them as an array in your `docs.yml`: **`docs.yml`** ```yaml docs.yml instances: - url: example.docs.buildwithfern.com custom-domain: - www.mydomain.com - partner.otherdomain.com ``` Listing extra domains in `docs.yml` doesn't activate them on its own. Contact Fern via your dedicated Slack channel or [email](mailto:support@buildwithfern.com) to register and verify each additional domain. You'll receive DNS configuration details for each. > Learn how to set up your Fern-generated documentation site to use a custom subdomain or subpath.