Document first-match-wins behavior for redirects

fern/products/docs/pages/navigation/site-level-settings.mdx

@@ -258,6 +258,16 @@ logo:
 
 ## Redirects configuration
 
+Redirect traffic from one path to another, either as exact paths or regex patterns. The [Configure redirects](/learn/docs/seo/redirects) guide covers examples and ordering rules in depth.
+
+```yaml docs.yml
+redirects:
+  - source: /old-path
+    destination: /new-path
+  - source: /old-folder/:slug*
+    destination: /new-folder/:slug*
+```
+
 <Markdown src="/products/docs/snippets/redirects.mdx" />
 
 ## NavBar links configuration

fern/products/docs/pages/seo/redirects.mdx

@@ -3,14 +3,102 @@ title: Configure redirects
 subtitle: Learn how to configure redirects in Fern Docs. Set up exact path redirects and regex patterns to preserve SEO equity when pages move.
 ---
 
-
-## Redirects
+Redirects map old URLs to new ones so inbound links and search rankings survive when pages move, change slugs, or are deleted. 
+
+## Set up redirects
+
+Configure redirects in `docs.yml` using exact paths or regex patterns, pointing at either internal paths 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.
+
+<CodeBlock title="docs.yml">
+  ```yml
+  redirects:
+    # Exact path redirects
+    - source: "/old-path"
+      destination: "/new-path"
+    - source: "/old-folder/path"
+      destination: "/new-folder/path"
+    - source: "/old-folder/path"
+      destination: "https://www.example.com/fern" # External destination
+    - source: "/temporary-redirect"
+      destination: "/new-location"
+      permanent: false # Use 307 (temporary) instead of 308 (permanent)
+
+    # Regex-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*"
+  ```
+</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">
+  ```yml
+  redirects:
+    # Specific path first — matches /docs/api/billing/overview, etc.
+    - source: "/docs/api/billing/:slug*"
+      destination: "/docs/reference/billing/:slug*"
+
+    # Broader catch-all second — matches everything else under /docs/api/
+    - source: "/docs/api/:slug*"
+      destination: "/docs/reference/:slug*"
+  ```
+</CodeBlock>
+
+A broader pattern listed before a more specific one prevents the specific rule from ever matching.
+
+## Properties
 
 <Markdown src="/products/docs/snippets/redirects.mdx" />
 
-<Tip>
-  To add external links to your sidebar navigation, see [Navigation](/learn/docs/configuration/navigation#links).
-</Tip>
+## Best practices
+
+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.
+
+<AccordionGroup>
+<Accordion title="404 handling">
+
+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, [enable automatic homepage redirects in your `docs.yml`](/docs/configuration/site-level-settings#settings-configuration) to send broken links to your homepage rather than showing a 404 page:
+
+```yaml title="docs.yml"
+settings:
+  hide-404-page: true
+```
+
+</Accordion>
+<Accordion title="Versioning and 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/v2/getting-started`). 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/v2/event-notifications # Don't do this
+```
+
+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.
+
+</Accordion>
+</AccordionGroup>
 
 ## Catching missing redirects
 

fern/products/docs/snippets/redirects.mdx

@@ -1,34 +1,3 @@
-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. 
-
-
-  <CodeBlock title="docs.yml">
-    ```yml
-    redirects:
-      # Exact path redirects
-      - source: "/old-path"
-        destination: "/new-path"
-      - source: "/old-folder/path"
-        destination: "/new-folder/path"
-      - source: "/old-folder/path"
-        destination: "https://www.example.com/fern" # External destination
-      - source: "/temporary-redirect"
-        destination: "/new-location"
-        permanent: false # Use 307 (temporary) instead of 308 (permanent)
-
-      # Regex-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*"  
-    ```
-  </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>
-
 <ParamField path="source" type="string" required={true}>
   The relative path you want to redirect from (e.g., `/old-path`). Must be a relative path, not an absolute URL. Must not include search parameters (e.g., `?key=value`).
 </ParamField>
@@ -40,45 +9,3 @@ If your docs are hosted on a subpath (like `buildwithfern.com/learn`), include t
 <ParamField path="permanent" type="boolean" required={false} default="true">
   By default, uses the 308 status code to instructs clients and search engines to cache the redirect forever. Set to `false` only if you need a temporary redirect using the 307 status code, which won't be cached.
 </ParamField>
-
-### Best practices
-
-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. 
-
-<AccordionGroup>
-<Accordion title="404 handling">
-
-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, [enable automatic homepage redirects in your `docs.yml`](/docs/configuration/site-level-settings#settings-configuration) to send broken links to your homepage rather than showing a 404 page:
-
-```yaml title="docs.yml"
-settings:
-  hide-404-page: true
-```
-
-</Accordion>
-<Accordion title="Versioning and 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/v2/getting-started`). 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/v2/event-notifications # Don't do this
-```
-
-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.
-
-</Accordion>
-</AccordionGroup>

fern/translations/zh/products/docs/pages/navigation/site-level-settings.mdx

@@ -250,6 +250,16 @@ logo:
 
 ## 重定向配置
 
+在路径之间重定向流量，可以是精确路径或正则表达式模式。[配置重定向](/learn/docs/seo/redirects)指南详细介绍了示例和顺序规则。
+
+```yaml docs.yml
+redirects:
+  - source: /old-path
+    destination: /new-path
+  - source: /old-folder/:slug*
+    destination: /new-folder/:slug*
+```
+
 <Markdown src="/products/docs/snippets/redirects.mdx" />
 
 ## 导航栏链接配置