{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"redirects","__idx":0},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirects"]}]},{"$$mdtype":"Tag","name":"ConfigOptionRequirements","attributes":{"products":["Revel","Realm"],"plans":["Pro","Enterprise","Enterprise+"]},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly supports two ways of configuring redirects:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["In the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}," config file"]}," - Useful for maintaining lists of redirects after site or section migrations"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["In a separate YAML file"]}," - Place redirects in a separate file (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirects.yaml"]},") to make long lists more manageable"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When redirects are configured in both locations, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}," configuration takes priority."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"options","__idx":1},"children":["Options"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"sources-map","__idx":2},"children":["Sources map"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Option"},"children":["Option"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["/{source}"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#destination-object"},"children":["Destination object"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED"]},"."," ","Source is an absolute path that must start with a forward slash."," ","It may be an exact path; for example: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/sample/content/"]},"."," ","Alternatively it may use a wildcard at the end of the absolute path; for example: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/sample/*"]},"."," ","The wildcard symbol (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["*"]},") is only supported as the last path segment."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you are redirecting from files named ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["index.*"]},", omit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["index/"]}," from the path."]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"destination-object","__idx":3},"children":["Destination object"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Option"},"children":["Option"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["to"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED"]},"."," ","Absolute path to the destination."," ","It may be an exact path; for example: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/new-url/"]},"."," ","Alternatively, it may be a URL to an external resource; for example: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://redocly.com"]},"."," ","If the source uses a wildcard, the destination may also use a wildcard at the end of the path."," ","The destination wildcard indicates that the matched part of the path should be used; for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/new-url/*"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://redocly.com/*"]},"."," ","This option is not available for redirects defined in front matter."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you are redirecting to pages named ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["index.*"]},", omit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["index/"]}," from the path."]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["type"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HTTP status code for the redirect."," ","Default: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["301"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples","__idx":4},"children":["Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"basic-redirect-configuration","__idx":5},"children":["Basic redirect configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Configure redirects in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}," by adding a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirects"]}," section:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"redirects:\n  '/some-old-url/':\n    to: '/new-url/'\n  '/some-other-old-url':\n    to: '/new-url/'\n    type: 307\n  '/external-redirect/':\n    to: 'https://redocly.com'\n  '/url-with-wildcard-redirect/*':\n    to: '/new-url/*'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"redirect-one-page-to-another","__idx":6},"children":["Redirect one page to another"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use paths to redirect individual pages, perhaps after restructuring site content:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"redirects:\n  '/concepts/static-assets/':\n    to: '/content/static-assets/'\n  '/howto/add-openapi-docs/':\n    to: '/content/api-docs/add-openapi-docs/'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Adding redirects means that anyone with the old URLs still reaches the expected content."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you want to redirect to or from an index page, omit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["index/"]}," from paths:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Previous location: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/config/openapi/index.md"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["New location: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/config/api/index.md"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"redirects:\n  '/config/openapi/':\n    to: '/config/api/'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"redirect-to-an-external-url","__idx":7},"children":["Redirect to an external URL"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a page has moved to a separate site or domain, use a redirect to point to its new location:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"redirects:\n  '/roadmap':\n    to: 'https://example.com/awesome-roadmap'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"redirect-many-paths-to-one-page","__idx":8},"children":["Redirect many paths to one page"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"redirects:\n  '/pages/*':\n    to: '/book-on-one-page/'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this approach when you consolidate content, or want to redirect many URLs to the same resource."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"redirect-a-group-of-paths-to-the-same-structure","__idx":9},"children":["Redirect a group of paths to the same structure"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can 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:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"redirects:\n  '/guides/*':\n    to: '/tutorials/*'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All pages, including nested pages, will be redirected."," ","For example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/guides/add-linting/"]}," redirects to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/tutorials/add-linting/"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/guides/cli/previews/"]}," redirects to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/tutorials/cli/previews/"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If there's a specific redirect for a page that also matches a wildcard, then the specific redirect wins."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"add-redirects-to-versioned-content","__idx":10},"children":["Add redirects to versioned content"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Versioned content files create a specific path structure:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Links to non-default versions contain the version subfolder (without the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@"]},"): ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["docs/installation/v2/install"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Links to the default version omit the segment that contains the name of the version sub-folder: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["docs/installation/install"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After you change the default version of your content and publish the project, the links update automatically:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The links to the new default version inherit the links from the previous default version."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The links from the previous default version now include the segment with the version subfolder."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/project-structure#file-based-routing"},"children":["File-based routing"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["However, there are cases where you may need to create redirects to versioned content."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To redirect a non-versioned page to a default version of a page:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"redirects:\n  '/guides/install/':\n    to: '/versioned-installation/guide/'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To redirect a page to a non-default version of a page:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"redirects:\n  '/guides/install/':\n    to: '/versioned-installation/v1/guide/'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"use-a-separate-redirects-file","__idx":11},"children":["Use a separate redirects file"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you have many redirects, maintain them in a separate file using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," syntax."," ","Create a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirects.yaml"]}," file:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","data-title":"redirects.yaml","header":{"title":"redirects.yaml","controls":{"copy":{}}},"source":"'/products/original-product/':\n  to: '/products/new-shiny'\n'/products/slightly-improved-product/':\n  to: '/products/new-shiny'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Then reference it in your main ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}," configuration:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","data-title":"redocly.yaml","header":{"title":"redocly.yaml","controls":{"copy":{}}},"source":"redirects:\n  $ref: './redirects.yaml'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":12},"children":["Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/links"},"children":["Manage links"]}]}," - Manage and configure links on project pages for optimal navigation and redirect handling"]}]}]},"frontmatter":{"products":["Revel","Realm"],"plans":["Pro","Enterprise","Enterprise+"],"description":"Configure redirects to resources within your project."},"tagList":["configOptionRequirements","table"],"title":"redirects","lastModified":"2026-08-24T16:21:33.000Z"}