# Configure links and redirects for your site

> Learn how to configure redirects and external links in Fern Docs. Set up exact path redirects, regex patterns, and navigation links for your documentation 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`](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 path you want to redirect from.
</ParamField>

<ParamField path="destination" type="string" required={true}>
  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`.
</ParamField>

<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/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:

    ```yaml title="docs.yml"
    redirects:
      - source: /docs/event-notifications
        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.
  </Accordion>
</AccordionGroup>

## Links

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

```yaml title="docs.yml"
navigation: 
  - section: Home
    contents:
      - page: Introduction
        path: ./intro.mdx
      - link: Our YouTube Channel
        href: https://www.youtube.com/
```

<Frame>
  <img src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/b43c1214e4ce8206db3e263383ae7ac7561ead361a4798021da237574b01ec9e/products/docs/pages/seo/external-link.png" alt="An external link within navigation" />
</Frame>