Redirects

redirects

When a page moves, keep its old address working: list it in redirects, with where visitors should go instead.

{
  "redirects": [
    { "source": "/old-page", "destination": "/docs/getting-started/" },
    { "source": "/v1/setup", "destination": "/docs/setup/" },
    { "source": "/community", "destination": "https://forum.example.com" }
  ]
}

The visitor lands on the destination straight away, and the address keeps its ?query and #anchor.

A source matches one exact address. Patterns like /old/:slug or /old/* aren’t supported, and writedocs validate reports them - list each address instead.

A redirect is permanent (301): browsers and search engines remember it, and search results move to the new address over time.

On Cloudflare Pages and Netlify

The site includes a _redirects file with every redirect. Cloudflare Pages and Netlify read it and redirect before any page loads, with a real HTTP 301. On other hosts, the old address serves a small page that sends the visitor on before anything shows - it works with JavaScript turned off too.

A redirect works with and without a trailing slash: /old-page and /old-page/ both go to the destination.

API pages that moved

An endpoint with no tag in its spec used to be served under untagged: /api/untagged/get-customers/. It’s now at /api/get-customers/, and the old address redirects there by itself - there’s nothing to add to redirects.

The site’s address

/ shows the home page - index.mdx at the project root, or the page whose frontmatter has slug: /. A site without one sends / to the first page in the navigation.

That redirect is temporary (302), so it isn’t remembered: once you add a home page, visitors see it.

Folder addresses

A page’s address has folders in it: /docs/payments/refunds/ is in /docs/payments/. When there’s no page at a folder’s own address, opening it sends the visitor to the first page inside it - the first one in your navigation’s order. There’s nothing to set up.

• A real page at the folder’s address - a group’s page, say - is always shown instead, and so is a redirect of your own.
• It works with and without the trailing slash, keeps the address’s ?query and #anchor, and works in writedocs dev too.
• It’s temporary (302), so a page you add at that address later is shown to everyone. Folder addresses aren’t in sitemap.xml.
• A folder with pages from both public and hidden sections sends visitors to a public page.
• writedocs broken-links counts a link to a folder address as working, since it leads somewhere.

A page that points elsewhere

To send a page’s own address to another site - and make its sidebar entry a link there - set url in its frontmatter. See Frontmatter.