Configure redirects

Learn how to configure redirects in Fern Docs. Set up exact path redirects and regex patterns to preserve SEO equity when pages move.

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.

docs.yml

1 redirects:
2   # Exact path redirects
3   - source: "/old-path"
4     destination: "/new-path"
5   - source: "/old-folder/path"
6     destination: "/new-folder/path"
7   - source: "/old-folder/path"
8     destination: "https://www.example.com/fern" # External destination
9   - source: "/temporary-redirect"
10     destination: "/new-location"
11     permanent: false # Use 307 (temporary) instead of 308 (permanent)
12 
13   # Regex-based redirects
14   - source: "/old-folder/:slug" # Matches single segments: /old-folder/foo
15     destination: "/new-folder/:slug"
16   - source: "/old-folder/:slug*" # Matches multiple segments: /old-folder/foo/bar/baz
17     destination: "/new-folder/:slug*"

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.

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

docs.yml

1 redirects:
2   # Specific path first — matches /docs/api/billing/overview, etc.
3   - source: "/docs/api/billing/:slug*"
4     destination: "/docs/reference/billing/:slug*"
5 
6   # Broader catch-all second — matches everything else under /docs/api/
7   - source: "/docs/api/:slug*"
8     destination: "/docs/reference/:slug*"

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

Properties

source

stringRequired

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).

destination

stringRequired

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.

permanent

booleanDefaults to 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.

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.

404 handling

Don’t create redirects to send broken links to your homepage:

docs.yml

1 redirects:
2   - source: /docs/event-notifications
3     destination: / # Don't do this

Instead, enable automatic homepage redirects in your docs.yml to send broken links to your homepage rather than showing a 404 page:

docs.yml

1 settings:
2   hide-404-page: true

Versioning and redirects

If you have 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:

docs.yml

1 redirects:
2   - source: /docs/event-notifications
3     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.

Catching missing redirects

The missing-redirects rule, run by fern check, compares the navigation tree built from your local YAML against the most recently published state of your site and flags previously-published URLs that no longer resolve and aren’t covered by an entry in redirects:. This catches pages you’ve moved or removed before they start returning 404s for existing inbound links.

Tune severity with the missing-redirects rule in docs.yml.

1	redirects:
2	# Exact path redirects
3	- source: "/old-path"
4	destination: "/new-path"
5	- source: "/old-folder/path"
6	destination: "/new-folder/path"
7	- source: "/old-folder/path"
8	destination: "https://www.example.com/fern" # External destination
9	- source: "/temporary-redirect"
10	destination: "/new-location"
11	permanent: false # Use 307 (temporary) instead of 308 (permanent)
12
13	# Regex-based redirects
14	- source: "/old-folder/:slug" # Matches single segments: /old-folder/foo
15	destination: "/new-folder/:slug"
16	- source: "/old-folder/:slug*" # Matches multiple segments: /old-folder/foo/bar/baz
17	destination: "/new-folder/:slug*"

1	redirects:
2	# Specific path first — matches /docs/api/billing/overview, etc.
3	- source: "/docs/api/billing/:slug*"
4	destination: "/docs/reference/billing/:slug*"
5
6	# Broader catch-all second — matches everything else under /docs/api/
7	- source: "/docs/api/:slug*"
8	destination: "/docs/reference/:slug*"

1	redirects:
2	- source: /docs/event-notifications
3	destination: / # Don't do this

1	redirects:
2	- source: /docs/event-notifications
3	destination: /docs/v2/event-notifications # Don't do this