Redirects

Redirects

redirects.yaml maps a path a reader still has to a path you now use.

The shape

- from: /guides/getting-started
  to: /start/quickstart
  status: 301
- from: /old-api
  to: /api/content-api
  status: 301

Three fields, all required:

fromstringrequired

The old path, from the site root.

tostringrequired

Where the reader should go.

status301 | 302 | 308required

301 for a permanent move. 302 for a temporary one. 308 for a permanent move that must keep the request method.

Which status to use

Use 301 unless you have a reason not to. A permanent redirect is cached by browsers and consolidated by search engines, which is what you want when a page has moved for good.

Use 302 only while a destination is temporary. A cached 301 you regret is hard to undo in a reader’s browser.

The per-page alternative

A redirect that belongs to one page can live in that page’s frontmatter:

---
title: Quickstart
redirect_from:
  - /guides/getting-started
---

Use redirect_from when the old path is about this page. Use redirects.yaml when you are reorganising a section and the mapping is a set.

Rules

Rule	Severity	What it means
redirects-invalid	error	The YAML does not match the schema.
redirect-loop	error	A chain of redirects returns to its start.
redirect-conflict	error	A redirect and a real page claim the same path.
redirect-duplicate	warning	The same from appears twice.
redirect-chain	warning	A redirect points at another redirect.

A chain is a warning rather than an error because it works; it is just slow, and each hop is a chance for a reader to be dropped. Collapse it: point the first redirect at the final destination.

Warning

Deleting a page that other pages link to is not the dangerous case, because the linter catches it. The dangerous case is deleting a page that readers have bookmarked and search engines have indexed. Add the redirect in the same branch as the delete.