From e98791e45a09d98ffde2f5bbb6ac99607f4f5db3 Mon Sep 17 00:00:00 2001
From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com>
Date: Thu, 27 Aug 2026 19:43:08 +0000
Subject: [PATCH 1/5] Document redirects files in docs.yml
---
.../docs/pages/changelog/2026-08-27.mdx | 9 ++++
.../pages/navigation/site-level-settings.mdx | 10 +++-
fern/products/docs/pages/seo/redirects.mdx | 48 ++++++++++++++++++-
3 files changed, 64 insertions(+), 3 deletions(-)
create mode 100644 fern/products/docs/pages/changelog/2026-08-27.mdx
diff --git a/fern/products/docs/pages/changelog/2026-08-27.mdx b/fern/products/docs/pages/changelog/2026-08-27.mdx
new file mode 100644
index 0000000000..27f6ef46cc
--- /dev/null
+++ b/fern/products/docs/pages/changelog/2026-08-27.mdx
@@ -0,0 +1,9 @@
+## Redirects in their own files
+
+seo, docs.yml
+
+You can now keep redirects outside `docs.yml`. Set `redirects` to the filepath of a YAML file that holds the list under its own `redirects` key, or to a list of filepaths to split redirects across several files. Fern combines the files in the order you list them, which is also the order they're evaluated in.
+
+Requires Fern CLI version `5.107.0` or later.
+
+
diff --git a/fern/products/docs/pages/navigation/site-level-settings.mdx b/fern/products/docs/pages/navigation/site-level-settings.mdx
index 7869127e8d..a67cc93581 100644
--- a/fern/products/docs/pages/navigation/site-level-settings.mdx
+++ b/fern/products/docs/pages/navigation/site-level-settings.mdx
@@ -67,8 +67,8 @@ navbar-links:
Configure the `primaryAccent` and `background` colors. Learn more about the [`colors` configuration](/learn/docs/getting-started/global-configuration#colors-configuration).
-
- An array of paths you want to configure to permanently redirect to another path. Learn more about the
+
+ An array of paths you want to configure to permanently redirect to another path, or the filepath(s) of YAML files holding that array. Learn more about the
[`redirects` configuration](/learn/docs/getting-started/global-configuration#redirects-configuration).
@@ -268,6 +268,12 @@ redirects:
destination: /new-folder/:slug*
```
+To keep a long list out of `docs.yml`, set `redirects` to the filepath of a YAML file that holds the list under its own `redirects` key, or to a list of such filepaths:
+
+```yaml docs.yml
+redirects: ./redirects.yml
+```
+
## NavBar links configuration
diff --git a/fern/products/docs/pages/seo/redirects.mdx b/fern/products/docs/pages/seo/redirects.mdx
index dfc05e091b..71ade391d8 100644
--- a/fern/products/docs/pages/seo/redirects.mdx
+++ b/fern/products/docs/pages/seo/redirects.mdx
@@ -7,7 +7,7 @@ Redirects map old URLs to new ones so inbound links and search rankings survive
## Set up redirects
-Configure redirects in `docs.yml`, pointing at either internal paths or external URLs. Use an exact path when a single URL moves, and a [pattern](#pattern-syntax) when a path's descendants move with it: an exact `source` matches that one URL and nothing beneath it, so `/old-folder` leaves `/old-folder/page` alone.
+Configure redirects in `docs.yml` (or in [separate files](#store-redirects-in-separate-files) that `docs.yml` references), pointing at either internal paths or external URLs. Use an exact path when a single URL moves, and a [pattern](#pattern-syntax) when a path's descendants move with it: an exact `source` matches that one URL and nothing beneath it, so `/old-folder` leaves `/old-folder/page` alone.
If your docs are hosted on a subpath (like `buildwithfern.com/learn`), include the subpath in both the source and destination paths.
@@ -55,6 +55,38 @@ Repeat the regular expression in `destination`. A parameter written as `:slug(.*
The optional modifier (`?`) is unsupported. Fern strips each `source` at the first `?` to remove search parameters, so `/old-folder/:slug?` is matched as `/old-folder/:slug`.
+## Store redirects in separate files
+
+A long redirect list can live outside `docs.yml`. Point `redirects` at a YAML file, and Fern reads the list from that file:
+
+```yaml title="docs.yml"
+redirects: ./redirects.yml
+```
+
+The file nests its list under a top-level `redirects` key. Entries take the same [properties](#properties) as inline ones:
+
+```yaml title="redirects.yml"
+redirects:
+ - source: "/old-path"
+ destination: "/new-path"
+ - source: "/old-folder/:slug*"
+ destination: "/new-folder/:slug*"
+```
+
+To split redirects across files, list several filepaths:
+
+```yaml title="docs.yml"
+redirects:
+ - ./redirects/api.yml
+ - ./redirects/guides.yml
+```
+
+Filepaths resolve relative to `docs.yml`. Fern concatenates the files in the order listed, so `redirects/api.yml` is [evaluated](#evaluation-order) before `redirects/guides.yml`. A `redirects` key holds either filepaths or inline redirect entries, never a mix of the two.
+
+[`fern check`](/learn/cli-api-reference/cli-reference/general-commands#fern-check) and publishing both fail when a referenced file is missing, empty, or holds an invalid redirect, and `fern docs dev` reloads the preview when one of the files changes.
+
+Separate redirects files require Fern CLI version `5.107.0` or later. Run `fern upgrade` to update.
+
## Evaluation order
Redirects are evaluated top-to-bottom and the first match wins, so list specific paths before broader ones:
@@ -152,6 +184,20 @@ redirects:
destination: /new-path # must differ from `source`
```
+### Failed to load redirects: /path/to/redirects.yml does not exist
+
+`redirects` in `docs.yml` points at a file that isn't on disk. Filepaths resolve relative to `docs.yml`, so `redirects: ./redirects.yml` refers to a file that sits next to it.
+
+### Failed to parse /path/to/redirects.yml: the file must nest the list under a top-level `redirects` key
+
+A redirects file holds a `redirects` key, not a bare list:
+
+```yaml title="redirects.yml"
+redirects:
+ - source: /old
+ destination: /new
+```
+
### Circular redirect chain detected: /a → /b → /a
Two or more [redirects](/learn/docs/configuration/site-level-settings#redirects-configuration) form a cycle: `/a` redirects to `/b`, and `/b` redirects back to `/a` (directly or through more hops). The browser would bounce between them indefinitely. Point every `source` in the chain at the final destination directly, so no `destination` is itself another `source`.
From 2bc84c10f30038b2032434020946c0dedfac2e02 Mon Sep 17 00:00:00 2001
From: "devin.logan"
Date: Fri, 28 Aug 2026 17:33:35 +0000
Subject: [PATCH 2/5] docs: simplify redirects file guidance
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
.../docs/pages/changelog/2026-08-27.mdx | 8 +++-----
.../pages/navigation/site-level-settings.mdx | 4 ++--
fern/products/docs/pages/seo/redirects.mdx | 17 ++++++-----------
3 files changed, 11 insertions(+), 18 deletions(-)
diff --git a/fern/products/docs/pages/changelog/2026-08-27.mdx b/fern/products/docs/pages/changelog/2026-08-27.mdx
index b365928b3b..27d23fa833 100644
--- a/fern/products/docs/pages/changelog/2026-08-27.mdx
+++ b/fern/products/docs/pages/changelog/2026-08-27.mdx
@@ -17,12 +17,10 @@ You can now present a changelog as a blog, with dated entries rendered as cards
-## Redirects in their own files
+## Redirects in separate files
seo, docs.yml
-You can now keep redirects outside `docs.yml`. Set `redirects` to the filepath of a YAML file that holds the list under its own `redirects` key, or to a list of filepaths to split redirects across several files. Fern combines the files in the order you list them, which is also the order they're evaluated in.
+You can now keep redirects in a separate YAML file and reference it from `docs.yml`. You can also split redirects across multiple files.
-Requires Fern CLI version `5.107.0` or later.
-
-
+
diff --git a/fern/products/docs/pages/navigation/site-level-settings.mdx b/fern/products/docs/pages/navigation/site-level-settings.mdx
index 90cdf119a9..d58f9b40aa 100644
--- a/fern/products/docs/pages/navigation/site-level-settings.mdx
+++ b/fern/products/docs/pages/navigation/site-level-settings.mdx
@@ -68,7 +68,7 @@ navbar-links:
- An array of paths you want to configure to permanently redirect to another path, or the filepath(s) of YAML files holding that array. Learn more about the
+ A list of redirects, a YAML file path, or a list of YAML file paths. Learn more about the
[`redirects` configuration](/learn/docs/getting-started/global-configuration#redirects-configuration).
@@ -268,7 +268,7 @@ redirects:
destination: /new-folder/:slug*
```
-To keep a long list out of `docs.yml`, set `redirects` to the filepath of a YAML file that holds the list under its own `redirects` key, or to a list of such filepaths:
+To keep redirects in separate files, set `redirects` to one or more YAML file paths:
```yaml docs.yml
redirects: ./redirects.yml
diff --git a/fern/products/docs/pages/seo/redirects.mdx b/fern/products/docs/pages/seo/redirects.mdx
index 71ade391d8..3e275e5f5b 100644
--- a/fern/products/docs/pages/seo/redirects.mdx
+++ b/fern/products/docs/pages/seo/redirects.mdx
@@ -7,7 +7,7 @@ Redirects map old URLs to new ones so inbound links and search rankings survive
## Set up redirects
-Configure redirects in `docs.yml` (or in [separate files](#store-redirects-in-separate-files) that `docs.yml` references), pointing at either internal paths or external URLs. Use an exact path when a single URL moves, and a [pattern](#pattern-syntax) when a path's descendants move with it: an exact `source` matches that one URL and nothing beneath it, so `/old-folder` leaves `/old-folder/page` alone.
+Configure redirects in `docs.yml` (or in [separate files](#keep-redirects-in-separate-files) that `docs.yml` references), pointing at either internal paths or external URLs. Use an exact path when a single URL moves, and a [pattern](#pattern-syntax) when a path's descendants move with it: an exact `source` matches that one URL and nothing beneath it, so `/old-folder` leaves `/old-folder/page` alone.
If your docs are hosted on a subpath (like `buildwithfern.com/learn`), include the subpath in both the source and destination paths.
@@ -55,15 +55,15 @@ Repeat the regular expression in `destination`. A parameter written as `:slug(.*
The optional modifier (`?`) is unsupported. Fern strips each `source` at the first `?` to remove search parameters, so `/old-folder/:slug?` is matched as `/old-folder/:slug`.
-## Store redirects in separate files
+## Keep redirects in separate files
-A long redirect list can live outside `docs.yml`. Point `redirects` at a YAML file, and Fern reads the list from that file:
+Set `redirects` in `docs.yml` to a YAML file path:
```yaml title="docs.yml"
redirects: ./redirects.yml
```
-The file nests its list under a top-level `redirects` key. Entries take the same [properties](#properties) as inline ones:
+The file must contain a top-level `redirects` list:
```yaml title="redirects.yml"
redirects:
@@ -73,7 +73,7 @@ redirects:
destination: "/new-folder/:slug*"
```
-To split redirects across files, list several filepaths:
+To use multiple files, list their paths:
```yaml title="docs.yml"
redirects:
@@ -81,11 +81,7 @@ redirects:
- ./redirects/guides.yml
```
-Filepaths resolve relative to `docs.yml`. Fern concatenates the files in the order listed, so `redirects/api.yml` is [evaluated](#evaluation-order) before `redirects/guides.yml`. A `redirects` key holds either filepaths or inline redirect entries, never a mix of the two.
-
-[`fern check`](/learn/cli-api-reference/cli-reference/general-commands#fern-check) and publishing both fail when a referenced file is missing, empty, or holds an invalid redirect, and `fern docs dev` reloads the preview when one of the files changes.
-
-Separate redirects files require Fern CLI version `5.107.0` or later. Run `fern upgrade` to update.
+File paths are relative to `docs.yml`. Fern evaluates the files in the order listed. Use file paths or inline redirect entries, but not both.
## Evaluation order
@@ -210,4 +206,3 @@ redirects:
destination: /c
```
-
From f5490fa6cfe3020eaa7946098263d5754e66e76a Mon Sep 17 00:00:00 2001
From: "devin.logan"
Date: Fri, 28 Aug 2026 17:35:21 +0000
Subject: [PATCH 3/5] docs: add redirects changelog example
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
fern/products/docs/pages/changelog/2026-08-27.mdx | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/fern/products/docs/pages/changelog/2026-08-27.mdx b/fern/products/docs/pages/changelog/2026-08-27.mdx
index 27d23fa833..0395a70cb1 100644
--- a/fern/products/docs/pages/changelog/2026-08-27.mdx
+++ b/fern/products/docs/pages/changelog/2026-08-27.mdx
@@ -23,4 +23,8 @@ You can now present a changelog as a blog, with dated entries rendered as cards
You can now keep redirects in a separate YAML file and reference it from `docs.yml`. You can also split redirects across multiple files.
+```yaml docs.yml
+redirects: ./redirects.yml
+```
+
From 7f2c88da797daac345843fd66942cfb65228e5b1 Mon Sep 17 00:00:00 2001
From: "devin.logan"
Date: Fri, 28 Aug 2026 17:36:11 +0000
Subject: [PATCH 4/5] docs: clarify redirects setup wording
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
fern/products/docs/pages/seo/redirects.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/fern/products/docs/pages/seo/redirects.mdx b/fern/products/docs/pages/seo/redirects.mdx
index 3e275e5f5b..d6a300dcdf 100644
--- a/fern/products/docs/pages/seo/redirects.mdx
+++ b/fern/products/docs/pages/seo/redirects.mdx
@@ -7,7 +7,7 @@ Redirects map old URLs to new ones so inbound links and search rankings survive
## Set up redirects
-Configure redirects in `docs.yml` (or in [separate files](#keep-redirects-in-separate-files) that `docs.yml` references), pointing at either internal paths or external URLs. Use an exact path when a single URL moves, and a [pattern](#pattern-syntax) when a path's descendants move with it: an exact `source` matches that one URL and nothing beneath it, so `/old-folder` leaves `/old-folder/page` alone.
+Configure redirects to internal paths or external URLs in `docs.yml` or in [separate files](#keep-redirects-in-separate-files) that `docs.yml` references. Use an exact path when a single URL moves, and a [pattern](#pattern-syntax) when a path's descendants move with it: an exact `source` matches that one URL and nothing beneath it, so `/old-folder` leaves `/old-folder/page` alone.
If your docs are hosted on a subpath (like `buildwithfern.com/learn`), include the subpath in both the source and destination paths.
From 05de3aeda9dd438c388badb614bdfd02fa55d3ef Mon Sep 17 00:00:00 2001
From: "devin.logan"
Date: Fri, 28 Aug 2026 17:40:48 +0000
Subject: [PATCH 5/5] docs: tab redirects file examples
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
fern/products/docs/pages/seo/redirects.mdx | 24 +++++++++++++---------
1 file changed, 14 insertions(+), 10 deletions(-)
diff --git a/fern/products/docs/pages/seo/redirects.mdx b/fern/products/docs/pages/seo/redirects.mdx
index d6a300dcdf..28d12a52f9 100644
--- a/fern/products/docs/pages/seo/redirects.mdx
+++ b/fern/products/docs/pages/seo/redirects.mdx
@@ -57,13 +57,25 @@ The optional modifier (`?`) is unsupported. Fern strips each `source` at the fir
## Keep redirects in separate files
-Set `redirects` in `docs.yml` to a YAML file path:
+Set `redirects` in `docs.yml` to one or multiple YAML file paths:
+
+
```yaml title="docs.yml"
redirects: ./redirects.yml
```
+
-The file must contain a top-level `redirects` list:
+
+```yaml title="docs.yml"
+redirects:
+ - ./redirects/api.yml
+ - ./redirects/guides.yml
+```
+
+
+
+Each file must contain a top-level `redirects` list:
```yaml title="redirects.yml"
redirects:
@@ -73,14 +85,6 @@ redirects:
destination: "/new-folder/:slug*"
```
-To use multiple files, list their paths:
-
-```yaml title="docs.yml"
-redirects:
- - ./redirects/api.yml
- - ./redirects/guides.yml
-```
-
File paths are relative to `docs.yml`. Fern evaluates the files in the order listed. Use file paths or inline redirect entries, but not both.
## Evaluation order