Configure links and redirects for your site

Redirects

The redirects object allows you to redirect traffic from one path to another. You can redirect exact paths or use dynamic patterns with regex 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.

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     permanent: true
8   - source: "/old-folder/path"
9     destination: "https://www.example.com/fern" # External destination
10     
11   # Regex-based redirects
12   - source: "/old-folder/:slug" # Matches single segments: /old-folder/foo
13     destination: "/new-folder/:slug"   
14   - source: "/old-folder/:slug*" # Matches multiple segments: /old-folder/foo/bar/baz 
15     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.

source

stringRequired

The internal path that you want to redirect from.

destination

stringRequired

The path or URL that you want to redirect 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

boolean

Toggle between permanent and temporary redirects (default false). When true, the status code is 308. When false, the status code is 307.

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/getting-started/v2). 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/event-notifications/v2 # 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.

Links

You can add a link to an external page within your sidebar navigation with the following configuration:

docs.yml

1 navigation: 
2   - section: Home
3     contents:
4       - page: Introduction
5         path: ./intro.mdx
6       - link: Our YouTube Channel
7         href: https://www.youtube.com/