Skip to content

docs: document redirect pattern syntax, including regex parameters #6563

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.

Sign up for GitHub

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 1 commit into
base: main
Choose a base branch
from
Open

docs: document redirect pattern syntax, including regex parameters #6563

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 21 additions & 5 deletions fern/products/docs/pages/seo/redirects.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,18 +25,16 @@ 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*"
- source: "/old-:slug(.*)" # Matches mid-segment: /old-guides/setup
destination: "/new-:slug(.*)"
```
</CodeBlock>

<Info>
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.
</Info>

Redirects are evaluated top-to-bottom and the first match wins:

<CodeBlock title="docs.yml">
Expand All @@ -54,6 +52,24 @@ Redirects are evaluated top-to-bottom and the first match wins:

A broader pattern listed before a more specific one prevents the specific rule from ever matching.

## Pattern syntax

A parameter is a name prefixed with `:`. Each one captures part of the incoming URL and is replayed in `destination` under the same name.

| Pattern | Captures |
|---------|----------|
| `:slug` | A single path segment, starting immediately after a `/`. |
| `:slug*` | Zero or more path segments, including the separating slashes. |
| `:slug+` | One or more path segments. |
| `:slug(regex)` | Whatever the regular expression matches. Unlike the forms above, this can start mid-segment and can span `/`. |
| `(regex)` | An unnamed group, replayed in `destination` as `:0`. |

A plain `:slug` only starts after a `/` and never spans one, so reach for a regular expression when a URL changes mid-segment. `/plants-:slug` matches `/plants-monstera` but not `/plants-monstera/care`, while `/plants-:slug(.*)` matches both. The same syntax narrows a parameter instead of widening it: `/v:version(\d+)/plants/:slug*` matches `/v2/plants/monstera/care` and captures `version` as `2`.

Repeat the regular expression in `destination`. A parameter written as `:slug(.*)` in `source` must stay `:slug(.*)` in `destination`, because a bare `:slug` can't hold a value containing `/`, and the redirect then resolves to the literal text `/new-folder/: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`.

## Properties

<Markdown src="/products/docs/snippets/redirects.mdx" />
Expand Down
26 changes: 21 additions & 5 deletions fern/translations/zh/products/docs/pages/seo/redirects.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,18 +26,16 @@ subtitle: 学习如何在 Fern Docs 中配置重定向。设置精确路径重
destination: "/new-location"
permanent: false # 使用 307（临时）而不是 308（永久）

# 基于正则表达式的重定向
# 基于模式的重定向
- source: "/old-folder/:slug" # 匹配单个段：/old-folder/foo
destination: "/new-folder/:slug"
- source: "/old-folder/:slug*" # 匹配多个段：/old-folder/foo/bar/baz
destination: "/new-folder/:slug*"
- source: "/old-:slug(.*)" # 匹配段中间的内容：/old-guides/setup
destination: "/new-:slug(.*)"
```
</CodeBlock>

<Info>
带有星号 (`*`) 后缀的参数匹配零个或多个路径段，捕获 URL 中后面的所有内容。在重定向整个文件夹结构时使用此功能以保留嵌套路径。
</Info>

重定向按从上到下的顺序进行评估，第一个匹配的规则生效：

<CodeBlock title="docs.yml">
Expand All @@ -55,6 +53,24 @@ subtitle: 学习如何在 Fern Docs 中配置重定向。设置精确路径重

将更宽泛的模式放在更具体的模式之前会阻止具体规则匹配。

## 模式语法

参数是以 `:` 为前缀的名称。每个参数捕获传入 URL 的一部分，并在 `destination` 中以相同的名称回填。

| 模式 | 捕获内容 |
|------|----------|
| `:slug` | 单个路径段，紧跟在 `/` 之后开始。 |
| `:slug*` | 零个或多个路径段，包括分隔用的斜杠。 |
| `:slug+` | 一个或多个路径段。 |
| `:slug(regex)` | 正则表达式匹配到的任何内容。与上述形式不同，它可以从段中间开始，也可以跨越 `/`。 |
| `(regex)` | 未命名的分组，在 `destination` 中以 `:0` 回填。 |

普通的 `:slug` 只能在 `/` 之后开始，且不能跨越 `/`，因此当 URL 在段中间发生变化时，请使用正则表达式。`/plants-:slug` 匹配 `/plants-monstera`，但不匹配 `/plants-monstera/care`，而 `/plants-:slug(.*)` 两者都匹配。同样的语法也可以收窄参数而不是放宽它：`/v:version(\d+)/plants/:slug*` 匹配 `/v2/plants/monstera/care`，并将 `version` 捕获为 `2`。

请在 `destination` 中重复该正则表达式。在 `source` 中写成 `:slug(.*)` 的参数，在 `destination` 中也必须保持 `:slug(.*)`，因为不带正则表达式的 `:slug` 无法容纳包含 `/` 的值，此时重定向会解析为字面文本 `/new-folder/:slug`。

不支持可选修饰符 (`?`)。Fern 会在第一个 `?` 处截断每个 `source` 以去除查询参数，因此 `/old-folder/:slug?` 会按 `/old-folder/:slug` 进行匹配。

## 属性

<Markdown src="/products/docs/snippets/redirects.mdx" />
Expand Down
Loading