Configure links and redirects for your site

Set up the navigation for your documentation site built with Fern Docs using the docs.yml file

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
1redirects:
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.

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

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