-
Notifications
You must be signed in to change notification settings - Fork 4
Document custom domain setup in dashboard #2968
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
devin-ai-integration
wants to merge
3
commits into
main
Choose a base branch
from
devin/1767632950-dashboard-custom-domain
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+121
−34
Open
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| ## Set up custom domains in the dashboard | ||
|
|
||
| You can now configure custom domains for your documentation site directly in the [Fern Dashboard](https://dashboard.buildwithfern.com/). The dashboard automatically displays the DNS records you need to add to your domain registrar based on your domain type. | ||
|
|
||
| [Learn more](/learn/dashboard/configuration/custom-domains) about setting up your custom domain. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,64 @@ | ||
| --- | ||
| title: Set up a custom domain | ||
| description: Use the Fern Dashboard to configure your custom domain with DNS records for subdomain, subpath, or root domain hosting. | ||
| --- | ||
|
|
||
| You 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. | ||
|
|
||
| <Note> | ||
| Alternatively, you can [set up your custom domain by manually configuring DNS records](/learn/docs/preview-publish/setting-up-your-domain). | ||
| </Note> | ||
|
|
||
| ## Setup | ||
|
|
||
| <Steps> | ||
| <Step title="Open the Dashboard"> | ||
|
|
||
| Navigate to the [Fern Dashboard](https://dashboard.buildwithfern.com/) and select your documentation site. | ||
| </Step> | ||
|
|
||
| <Step title="Add your custom domain(s)"> | ||
|
|
||
| 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. | ||
|
|
||
| For multiple custom domains (e.g., partner or white-label deployments), repeat this step to add each domain. | ||
| </Step> | ||
|
|
||
| <Step title="Update the domain in `docs.yml`"> | ||
|
|
||
| Add your `custom-domain` to your `docs.yml` configuration: | ||
|
|
||
| ```yaml docs.yml | ||
| instances: | ||
| - url: example.docs.buildwithfern.com | ||
| custom-domain: docs.mydomain.com | ||
| ``` | ||
|
|
||
| For multiple custom domains, configure an array: | ||
|
|
||
| ```yaml docs.yml | ||
| instances: | ||
| - url: example.docs.buildwithfern.com | ||
| custom-domain: | ||
| - www.mydomain.com | ||
| - partner.otherdomain.com | ||
| ``` | ||
| </Step> | ||
|
|
||
| <Step title="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). | ||
| </Step> | ||
|
|
||
| <Step title="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. | ||
|
|
||
| <Tip>Check that you can access your new docs site from a mobile device or incognito browser.</Tip> | ||
| </Step> | ||
| </Steps> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -3,23 +3,24 @@ title: Bring your custom domain | |
| description: Learn how to set up your Fern-generated documentation site to use a custom subdomain or subpath. | ||
| --- | ||
|
|
||
| Bring Fern Docs to your custom domain. You can use: | ||
| - A subdomain on your custom domain, such as `docs.mydomain.com` | ||
| - A subpath on your custom domain, such as `mydomain.com/docs` | ||
| - A root domain, such as `mydomain.com` | ||
| You can configure any of the following custom domain types: | ||
| - **Subdomain**: `docs.mydomain.com` | ||
| - **Subpath**: `mydomain.com/docs` | ||
| - **Root domain**: `mydomain.com` | ||
|
|
||
| <Info> | ||
| Once you've set up your domain, use the [Fern Dashboard](https://dashboard.buildwithfern.com/) to manage site settings. | ||
| </Info> | ||
| 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"> | ||
| <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> | ||
|
|
||
| ### Update the domain in `docs.yml` | ||
| <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 ). | ||
|
|
||
|
|
@@ -28,14 +29,16 @@ instances: | |
| - url: example.docs.buildwithfern.com | ||
| custom-domain: docs.mydomain.com | ||
| ``` | ||
| </Step> | ||
|
|
||
| ### Contact Fern | ||
| <Step title="Contact Fern"> | ||
|
|
||
| Contact Fern via your dedicated Slack channel or [email](mailto:[email protected]) to receive: | ||
| - A unique CNAME value for your site | ||
| - A TXT record to verify your domain | ||
| </Step> | ||
|
|
||
| ### Create DNS records | ||
| <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: | ||
|
|
||
|
|
@@ -58,34 +61,36 @@ 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> | ||
|
|
||
| ### Verify the setup | ||
| <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"> | ||
| <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> | ||
|
|
||
| ### Configure the `url` in `docs.yml` | ||
| <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: | ||
| instances: | ||
| - url: example.docs.buildwithfern.com/docs | ||
| ``` | ||
| </CodeBlock> | ||
| </Step> | ||
|
|
||
| ### Configure the `custom-domain` | ||
| <Step title="Configure the `custom-domain`"> | ||
|
|
||
| Below the `url`, add a `custom-domain` key: | ||
|
|
||
|
|
@@ -98,26 +103,28 @@ instances: | |
| </CodeBlock> | ||
|
|
||
| [Here's an example.](https://github.com/fern-api/fern/blob/7d8631c6119787a8aaccb4ba49837e73c985db28/fern/docs.yml#L1-L3) | ||
| </Step> | ||
|
|
||
| ### Contact Fern | ||
| <Step title="Contact Fern"> | ||
|
|
||
| Contact Fern via your dedicated Slack channel or [email](mailto:[email protected]) to set up your custom subpath. | ||
| Contact Fern via your dedicated Slack channel or [email](mailto:[email protected]) to set up your custom subpath. | ||
| </Step> | ||
|
|
||
| ### Verify the setup | ||
| <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"> | ||
| <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> | ||
|
|
||
| ### Configure the `url` in `docs.yml` | ||
| <Step title="Configure the `url` in `docs.yml`"> | ||
|
|
||
| <CodeBlock title="docs.yml"> | ||
| ```yaml | ||
|
|
@@ -128,14 +135,16 @@ instances: | |
| </CodeBlock> | ||
|
|
||
| [Here's an example.](https://github.com/dannysheridan/katiedanny/blob/2fcf5769e2994af29e31d00904e04788b188a18b/fern/docs.yml#L3-L5) | ||
| </Step> | ||
|
|
||
| ### Contact Fern | ||
| <Step title="Contact Fern"> | ||
|
|
||
| Contact Fern via your dedicated Slack channel or [email](mailto:[email protected]) to receive: | ||
| - A unique CNAME value for your site | ||
| - A TXT record to verify your domain | ||
| </Step> | ||
|
|
||
| ### Configure your DNS settings | ||
| <Step title="Configure your DNS settings"> | ||
|
|
||
| You'll need the following DNS records configured for your root domain. | ||
|
|
||
|
|
@@ -163,20 +172,22 @@ 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. | ||
| </Step> | ||
|
|
||
| ### Verify the setup | ||
| <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> | ||
| </AccordionGroup> | ||
|
|
||
| ## Multiple custom domains | ||
| ### Multiple custom domains | ||
|
|
||
| To serve your documentation from multiple custom domains (e.g., for partner or white-label deployments), configure an array of 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: | ||
|
|
@@ -186,8 +197,6 @@ instances: | |
| - partner.otherdomain.com | ||
| ``` | ||
|
|
||
| This works with any of the above domain types (subdomain, subpath, or root domain). | ||
|
|
||
| <Info> | ||
| After configuring multiple domains in your `docs.yml`, contact Fern via your dedicated Slack channel or [email](mailto:[email protected]) to complete the setup. You'll receive DNS configuration details for each domain. | ||
| </Info> | ||
| </Info> | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[FernStyles.Current] Avoid time-relative terms like 'now' that become outdated