redirects

Configure redirects to resources within your project. Use redirects to change which resource a URL points to, maintaining working links when you move, rename, or restructure content.

Redocly supports two ways of configuring redirects:

• In the redocly.yaml config file - Useful for maintaining lists of redirects after site or section migrations
• In a separate YAML file - Place redirects in a separate file (for example, redirects.yaml) to make long lists more manageable

When redirects are configured in both locations, the redocly.yaml configuration takes priority.

Configure redirects in redocly.yaml by adding a redirects section:

redirects:
  '/some-old-url/':
    to: '/new-url/'
  '/some-other-old-url':
    to: '/new-url/'
    type: 307
  '/external-redirect/':
    to: 'https://redocly.com'
  '/url-with-wildcard-redirect/*':
    to: '/new-url/*'

Use paths to redirect individual pages, perhaps after restructuring site content:

redirects:
  '/concepts/static-assets/':
    to: '/content/static-assets/'
  '/howto/add-openapi-docs/':
    to: '/content/api-docs/add-openapi-docs/'

Adding redirects means that anyone with the old URLs still reaches the expected content.

If you want to redirect to or from an index page, omit index/ from paths:

Previous location: /config/openapi/index.md

New location: /config/api/index.md

redirects:
  '/config/openapi/':
    to: '/config/api/'

When a page has moved to a separate site or domain, use a redirect to point to its new location:

redirects:
  '/roadmap':
    to: 'https://example.com/awesome-roadmap'

Redirects support use of wildcards to match the last parts of a path. For example, if you restructured content from many pages in a directory into a single page:

redirects:
  '/pages/*':
    to: '/book-on-one-page/'

Use this approach when you consolidate content, or want to redirect many URLs to the same resource.

If you move a whole directory of content from one place to another, describe the first part of the path for the source and destination, and end both with a wildcard:

redirects:
  '/guides/*':
    to: '/tutorials/*'

All pages, including nested pages, will be redirected. For example /guides/add-linting/ redirects to /tutorials/add-linting/ and /guides/cli/previews/ redirects to /tutorials/cli/previews/.

If there's a specific redirect for a page that also matches a wildcard, then the specific redirect wins.

Versioned content files create a specific path structure:

• Links to non-default versions contain the version subfolder (without the @): docs/installation/v2/install.
• Links to the default version omit the segment that contains the name of the version sub-folder: docs/installation/install.

After you change the default version of your content and publish the project, the links update automatically:

• The links to the new default version inherit the links from the previous default version.
• The links from the previous default version now include the segment with the version subfolder.

You do not need to create redirects to the default version of your content, as the same links now point to new content. To learn more about how Realm manages URLs to your content pages, see File-based routing.

However, there are cases where you may need to create redirects to versioned content.

To redirect a non-versioned page to a default version of a page:

redirects:
  '/guides/install/':
    to: '/versioned-installation/guide/'

To redirect a page to a non-default version of a page:

redirects:
  '/guides/install/':
    to: '/versioned-installation/v1/guide/'

If you have many redirects, maintain them in a separate file using the $ref syntax. Create a redirects.yaml file:

'/products/original-product/':
  to: '/products/new-shiny'
'/products/slightly-improved-product/':
  to: '/products/new-shiny'

Then reference it in your main redocly.yaml configuration:

redirects:
  $ref: './redirects.yaml'

• Manage links - Manage and configure links on project pages for optimal navigation and redirect handling