From 7ffa3edd80f5ce5c9e50080172638f51c53b42b7 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Fri, 17 Oct 2025 03:10:35 +0000 Subject: [PATCH 1/2] Improve redirects documentation with advanced regex patterns - Add named capture group examples with regex patterns - Document Path-to-RegExp syntax including {0} delimiter - Include real-world examples (release notes, versioned APIs) - Add pattern syntax reference table - Based on user feedback about complex regex redirects Co-Authored-By: danny@buildwithfern.com --- fern/snippets/redirects.mdx | 40 ++++++++++++++++++++++++++++++++++--- 1 file changed, 37 insertions(+), 3 deletions(-) diff --git a/fern/snippets/redirects.mdx b/fern/snippets/redirects.mdx index de186cc0d..6f192ea0d 100644 --- a/fern/snippets/redirects.mdx +++ b/fern/snippets/redirects.mdx @@ -1,4 +1,4 @@ -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. +The `redirects` object allows you to redirect traffic from one path to another. You can redirect exact paths or use dynamic patterns with [Path-to-RegExp](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. @@ -17,11 +17,17 @@ If your docs are hosted on a subpath (like `buildwithfern.com/learn`), include t destination: "/new-location" permanent: false # Use 307 (temporary) instead of 308 (permanent) - # Regex-based redirects + # Pattern-based redirects - source: "/old-folder/:slug" # Matches single segments: /old-folder/foo destination: "/new-folder/:slug" - source: "/old-folder/:slug*" # Matches multiple segments: /old-folder/foo/bar/baz - destination: "/new-folder/:slug*" + destination: "/new-folder/:slug*" + + # Named capture groups with regex patterns + - source: "/release-notes/:year(\\d{4})-{0}:month(\\d{1,2})" + destination: "/docs/release-notes/:year/:month/1" + - source: "/api/v:version(\\d+)/:endpoint*" + destination: "/api-reference/:version/:endpoint*" ``` @@ -29,6 +35,34 @@ If your docs are hosted on a subpath (like `buildwithfern.com/learn`), include t Parameters suffixed with an asterisk (`*`) match zero or more path segments, capturing everything that follows in the URL. Use this when redirecting entire folder structures while preserving nested paths. +### Advanced patterns + +Fern uses [Path-to-RegExp](https://github.com/pillarjs/path-to-regexp) for pattern matching. Named capture groups can be defined with regex patterns and reused in destination URLs: + + +```yml +redirects: + # Match 4-digit years + - source: "/blog/:year(\\d{4})/:slug*" + destination: "/archive/:year/:slug*" + + # Match dates with literal separator + - source: "/posts/:year(\\d{4})-{0}:month(\\d{2})-{0}:day(\\d{2})" + destination: "/blog/:year/:month/:day" + + # Match numeric IDs only + - source: "/user/:id(\\d+)" + destination: "/users/:id/profile" +``` + + +**Pattern syntax:** +- `:name` - Captures a single path segment +- `:name*` - Captures zero or more segments +- `:name(\\d+)` - Captures digits only +- `:name(\\d{4})` - Captures exactly 4 digits +- `{0}` - Literal character delimiter between parameters + The incoming request path pattern. From 1f0b8c1cf9bdd3532e49cd1003df1101f7cddc88 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Fri, 17 Oct 2025 17:50:32 -0400 Subject: [PATCH 2/2] restructure new content --- fern/snippets/redirects.mdx | 42 +++++++++++++++++++++---------------- 1 file changed, 24 insertions(+), 18 deletions(-) diff --git a/fern/snippets/redirects.mdx b/fern/snippets/redirects.mdx index 6f192ea0d..7a3b23d20 100644 --- a/fern/snippets/redirects.mdx +++ b/fern/snippets/redirects.mdx @@ -2,8 +2,8 @@ The `redirects` object allows you to redirect traffic from one path to another. If your docs are hosted on a subpath (like `buildwithfern.com/learn`), include the subpath in both the source and destination paths. - + ```yml redirects: # Exact path redirects @@ -35,11 +35,24 @@ If your docs are hosted on a subpath (like `buildwithfern.com/learn`), include t Parameters suffixed with an asterisk (`*`) match zero or more path segments, capturing everything that follows in the URL. Use this when redirecting entire folder structures while preserving nested paths. + + The incoming request path pattern. + + + + The path you want to route to. Can be an internal path (`/new-path`) or an external URL (`https://example.com`). External URLs must include the full address, including `https`. + + + + `true` or `false` - default is `true`. If `true`, will use the 308 status code which instructs clients/search engines to cache the redirect forever. If `false`, will use the 307 status code which is temporary and is not cached. + + ### Advanced patterns -Fern uses [Path-to-RegExp](https://github.com/pillarjs/path-to-regexp) for pattern matching. Named capture groups can be defined with regex patterns and reused in destination URLs: +You can define named capture groups with regex patterns and reuse them in destination URLs: + ```yml redirects: # Match 4-digit years @@ -56,24 +69,17 @@ redirects: ``` -**Pattern syntax:** -- `:name` - Captures a single path segment -- `:name*` - Captures zero or more segments -- `:name(\\d+)` - Captures digits only -- `:name(\\d{4})` - Captures exactly 4 digits -- `{0}` - Literal character delimiter between parameters + - - The incoming request path pattern. - +| Pattern | Description | +|---------|-------------| +| `:name` | Captures a single path segment | +| `:name*` | Captures zero or more segments | +| `:name(\\d+)` | Captures digits only | +| `:name(\\d{4})` | Captures exactly 4 digits | +| `{0}` | Literal character delimiter between parameters | - - The path you want to route to. Can be an internal path (`/new-path`) or an external URL (`https://example.com`). External URLs must include the full address, including `https`. - - - - `true` or `false` - default is `true`. If `true`, will use the 308 status code which instructs clients/search engines to cache the redirect forever. If `false`, will use the 307 status code which is temporary and is not cached. - + ### Best practices