# 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:

<AccordionGroup>
  <Accordion title="Subdomain">
    To host your documentation on a subdomain like `docs.mydomain.com`, you need to create a CNAME record in your DNS settings.

    <Steps>
      <Step title="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).

        ```yaml docs.yml
        instances:
         - url: example.docs.buildwithfern.com
           custom-domain: docs.mydomain.com
        ```
      </Step>

      <Step title="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
      </Step>

      <Step title="Create DNS records">
        Log in to your domain registrar's dashboard and navigate to the DNS settings for your domain. Add the following records:

        <CodeBlock title="CNAME Record (Subdomain)">
          ```
          Type    Name    Value
          CNAME   docs    b7278b3c9357963d.vercel-dns-013.com
          ```
        </CodeBlock>

        <CodeBlock title="TXT Record (Domain Verification)">
          ```
          Type    Name    Value
          TXT     @       [TXT record value provided by Fern]
          ```
        </CodeBlock>

        Replace `docs` with any subdomain you want to use.

        <Warning title="Cloudflare users">
          If you are using Cloudflare, you should ensure the record isn't proxied.
        </Warning>
      </Step>

      <Step title="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.

        <Tip>
          Check that you can access your new docs site from a mobile device or incognito browser.
        </Tip>
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Subpath">
    To host your documentation on a subpath like `mydomain.com/docs`, you need to edit your `docs.yml` configuration and then get provider-specific instructions for setting up the subpath. Common providers include Cloudflare, AWS Route53 and Cloudfront, Netlify, and Vercel.

    <Steps>
      <Step title="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`.

        <CodeBlock title="docs.yml">
          ```yaml
          instances:
            - url: example.docs.buildwithfern.com/docs
          ```
        </CodeBlock>
      </Step>

      <Step title="Configure the `custom-domain`">
        Below the `url`, add a `custom-domain` key:

        <CodeBlock title="docs.yml">
          ```yaml
          instances:
            - url: example.docs.buildwithfern.com/docs
              custom-domain: mydomain.com/docs
          ```
        </CodeBlock>

        [Here's an example.](https://github.com/fern-api/fern/blob/7d8631c6119787a8aaccb4ba49837e73c985db28/fern/docs.yml#L1-L3)
      </Step>

      <Step title="Contact Fern">
        Contact Fern via your dedicated Slack channel or [email](mailto:support@buildwithfern.com) to set up your custom subpath.
      </Step>

      <Step title="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.

        <Tip>
          Check that you can access your new docs site from a mobile device or incognito browser.
        </Tip>
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Root domain">
    To host your documentation on a root domain like `mydomain.com`, you need to edit your `docs.yml` configuration and then get provider-specific instructions for setting up the domain. Common providers include Cloudflare, AWS Route53 and Cloudfront, Netlify, and Vercel.

    <Steps>
      <Step title="Configure the `url` in `docs.yml`">
        <CodeBlock title="docs.yml">
          ```yaml
          instances:
            - url: example.docs.buildwithfern.com
              custom-domain: www.mydomain.com
          ```
        </CodeBlock>

        [Here's an example.](https://github.com/dannysheridan/katiedanny/blob/2fcf5769e2994af29e31d00904e04788b188a18b/fern/docs.yml#L3-L5)
      </Step>

      <Step title="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
      </Step>

      <Step title="Configure your DNS settings">
        You'll need the following DNS records configured for your root domain.

        <CodeBlock title="CNAME Record (WWW Subdomain)">
          ```
          Type    Name    Value
          CNAME   www     b7278b3c9357963d.vercel-dns-013.com
          ```
        </CodeBlock>

        <CodeBlock title="A Record (Apex Domain)">
          ```
          Type    Name    Value
          A       @       76.76.21.21
          ```
        </CodeBlock>

        <CodeBlock title="TXT Record (Domain Verification)">
          ```
          Type    Name    Value
          TXT     @       [TXT record value provided by Fern]
          ```
        </CodeBlock>

        This redirects `mydomain.com` to `www.mydomain.com`.

        After you add these records, Fern will provision a SSL certificate.
      </Step>

      <Step title="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.

        <Tip>
          Check that you can access your new docs site from a mobile device or incognito browser.
        </Tip>
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

### Multiple custom domains

To serve your documentation from multiple custom domains (e.g., for partner or white-label deployments), follow the above steps for each domain (subdomain, subpath, or root domain), then configure an array in your `docs.yml`:

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

<Info>
  After configuring multiple domains in your `docs.yml`, contact Fern via your dedicated Slack channel or [email](mailto:support@buildwithfern.com) to complete the setup. You'll receive DNS configuration details for each domain.
</Info>