From 72e99847fe6f3c109e358227f2908b499a08ffa6 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 8 Oct 2025 13:18:18 -0400 Subject: [PATCH 1/3] add redirects best practices and info on default version --- .../docs/pages/navigation/products.mdx | 2 + .../docs/pages/navigation/versions.mdx | 5 ++- fern/snippets/default-version.mdx | 4 ++ fern/snippets/redirects.mdx | 41 ++++++++++++++++++- 4 files changed, 50 insertions(+), 2 deletions(-) create mode 100644 fern/snippets/default-version.mdx diff --git a/fern/products/docs/pages/navigation/products.mdx b/fern/products/docs/pages/navigation/products.mdx index 8960ca8d5..15719ed01 100644 --- a/fern/products/docs/pages/navigation/products.mdx +++ b/fern/products/docs/pages/navigation/products.mdx @@ -188,6 +188,8 @@ products: ``` + + diff --git a/fern/products/docs/pages/navigation/versions.mdx b/fern/products/docs/pages/navigation/versions.mdx index ac4d3faa9..db6bd76d1 100644 --- a/fern/products/docs/pages/navigation/versions.mdx +++ b/fern/products/docs/pages/navigation/versions.mdx @@ -44,7 +44,7 @@ Version-specific `yml` files: -Define a version in the top-level `docs.yml` by adding an item to the `versions` list and specifying the `display-name` and `path`. +Define a version in the top-level `docs.yml` by adding an item to the `versions` list and specifying the `display-name` and `path`. ```yaml @@ -55,6 +55,9 @@ versions: path: ./versions/v2.yml ``` + + + diff --git a/fern/snippets/default-version.mdx b/fern/snippets/default-version.mdx new file mode 100644 index 000000000..d9d92697a --- /dev/null +++ b/fern/snippets/default-version.mdx @@ -0,0 +1,4 @@ + + + Versions appear in the version dropdown in the order listed in `versions`. The first version in your `versions` list is your default version. This version appears at unversioned paths like `/docs/getting-started`, while other versions use versioned paths like `/docs/getting-started/v2`. Fern automatically handles version routing by [redirecting](/docs/seo/redirects) broken versioned links to the default version and managing canonical URLs. + \ No newline at end of file diff --git a/fern/snippets/redirects.mdx b/fern/snippets/redirects.mdx index 9c3c6a1bb..457381103 100644 --- a/fern/snippets/redirects.mdx +++ b/fern/snippets/redirects.mdx @@ -1,6 +1,6 @@ The `redirects` object allows you to redirect traffic from one path to another. You can redirect exact paths or use dynamic patterns with [`regex`](https://www.npmjs.com/package/path-to-regexp) parameters like `:slug` to handle bulk redirects. You can redirect to internal paths within your site or external URLs. -If your docs are hosted on a subpath (like `buildwithfern.com/learn`), include the subpath in both the source and destination paths. +If your docs are hosted on a subpath (like `buildwithfern.com/learn`), include the subpath in both the source and destination paths. @@ -38,3 +38,42 @@ If your docs are hosted on a subpath (like `buildwithfern.com/learn`), include t Toggle between **permanent** and **temporary** redirects (default `false`). When true, the status code is 308. When false, the status code is 307. + +### Best practices + +Only add redirects when necessary. Having a long list of redirects can slow down your site since each request must check against all redirect rules before routing the user. + +Avoid using redirects for 404 handling or versioning behavior, as Fern provides built-in settings for these use cases. + + + + +Don't create redirects to send broken links to your homepage: + +```yaml title="docs.yml" +redirects: + - source: /docs/event-notifications + destination: / # Don't do this +``` + +Instead, reach out to Fern to enable automatic homepage redirects, an internal setting that handles broken links without needing manual redirects. + + + + +If you have [versions](/docs/configuration/versions) configured, your default version uses unversioned paths (`/docs/getting-started`), while other versions use versioned paths (`/docs/getting-started/v2`). Fern automatically handles version routing by redirecting broken versioned links to the default version and managing canonical URLs. + +Avoid redirecting from unversioned to versioned URLs: + +```yaml title="docs.yml" +redirects: + - source: /docs/event-notifications + destination: /docs/event-notifications/v2 # Don't do this +``` + +This breaks Fern's version switcher behavior, potentially creating redirect loops or preventing users from navigating between versions. + +If you frequently need to redirect from the default version to another version, consider changing which version is set as default in your versions configuration. + + + \ No newline at end of file From ad4809569932092f59146951809432965bc0167f Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 8 Oct 2025 13:22:42 -0400 Subject: [PATCH 2/3] wording fix --- fern/snippets/default-version.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/fern/snippets/default-version.mdx b/fern/snippets/default-version.mdx index d9d92697a..a59f45991 100644 --- a/fern/snippets/default-version.mdx +++ b/fern/snippets/default-version.mdx @@ -1,4 +1,6 @@ - Versions appear in the version dropdown in the order listed in `versions`. The first version in your `versions` list is your default version. This version appears at unversioned paths like `/docs/getting-started`, while other versions use versioned paths like `/docs/getting-started/v2`. Fern automatically handles version routing by [redirecting](/docs/seo/redirects) broken versioned links to the default version and managing canonical URLs. + Versions appear in the version dropdown in the order listed in `versions`. The first version in your `versions` list is your default version. This version uses unversioned paths like `/docs/getting-started`, while other versions use versioned paths like `/docs/getting-started/v2`. + + Fern automatically handles version routing by [redirecting](/docs/seo/redirects) broken versioned links to the default version and managing canonical URLs. \ No newline at end of file From fc4ba7fd66720d20a9cda925a0b86ca5528e9110 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 8 Oct 2025 13:36:23 -0400 Subject: [PATCH 3/3] wording fixes --- fern/snippets/redirects.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/fern/snippets/redirects.mdx b/fern/snippets/redirects.mdx index 457381103..127f123f2 100644 --- a/fern/snippets/redirects.mdx +++ b/fern/snippets/redirects.mdx @@ -41,9 +41,7 @@ If your docs are hosted on a subpath (like `buildwithfern.com/learn`), include t ### Best practices -Only add redirects when necessary. Having a long list of redirects can slow down your site since each request must check against all redirect rules before routing the user. - -Avoid using redirects for 404 handling or versioning behavior, as Fern provides built-in settings for these use cases. +For optimal site performance, only add redirects when necessary. Avoid using redirects for behavior that Fern already handles automatically, such as 404 handling and version routing. @@ -71,7 +69,7 @@ redirects: destination: /docs/event-notifications/v2 # Don't do this ``` -This breaks Fern's version switcher behavior, potentially creating redirect loops or preventing users from navigating between versions. +Manually overriding the default versioning behavior can lead to unexpected redirect patterns. If you frequently need to redirect from the default version to another version, consider changing which version is set as default in your versions configuration.