Redirects

Redirect rules send readers from an old address to a new one, so links keep working when your docs change shape. Use them when you move a section, when you rename something, or when you bring in a site from another tool.

You may not need a rule

The docs router handles most moves on its own.

You need your own rule for what Octri can't work out: a split section, or addresses from a docs site that lived somewhere else.

Three ways to add a rule

{
  "navigation": {
    "redirects": [
      { "from": "/old-guide", "to": "/guides/quickstart" },
      { "from": "/v1/*", "to": "/api/*" }
    ]
  }
}

Rules are drafts until you publish. A rename and the rule that protects it go live together, so nobody hits a gap.

How rules match

from is a path on your docs site, and to is where readers go. Case is ignored, and a trailing slash makes no difference.

A wildcard must end the path, after a slash, and to can use one only if from does.

Which rule wins

1. A live page

   If a page is published at the address, it's served. Rules only answer for paths nothing publishes at.

2. A redirected page

   The exception to the first rule: a page set to Redirect to another page sends its readers on, from every tab that lists it.

3. Your rules

   Rules are checked in order, so put a specific rule above a wildcard that would also match.

Rules can chain, and readers go straight to the end of the chain. One that loops back on itself stops before repeating, so readers can't be sent round in circles.

Limits

Some paths can't be used as from:

• /, your home page
• Paths the docs site serves itself, such as /changelog and /gate
• Anything with ? or #, because a rule matches the path only

Moving from another docs tool

Export your old site's URLs, then add a wildcard rule for each section whose shape stayed the same, and individual rules for the rest. The migration guides cover this for each tool.

Troubleshooting