Redirects

Redirects

Keep an old URL working after you move, rename, or restructure a page - a static HTML stub gets written at the old path, so a search engine's stale index entry or someone's old bookmark still lands on the right page instead of 404ing. No server-side rewrite rule is involved (a static host has nowhere to run one) - the stub is just enough HTML for a browser to redirect itself and a crawler to learn the real canonical URL.

Per-page: frontmatter redirect_from

Add one or more old paths to a page's own frontmatter:

---
title: New Setup
redirect_from:
  - guides/old-setup
  - setup
---

Each entry is a pretty-URL segment - no leading/trailing slash, no .md/.html extension - the same shape the page's own URL takes. A build then writes a stub at each one (site/guides/old-setup/index.html, site/setup/index.html for the example above), both redirecting to this page's own real URL.

redirect_from is scoped to whichever tree the page itself belongs to - a version's own page redirects within that version (site/versions/2.0/old-path/), a locale's own translated page redirects within that locale (site/es/old-path/), exactly the same way the page's own real URL already is. There's nothing extra to configure per tree.

Site-wide: bxsites.yaml redirects

For an old URL that never belonged to a specific page - a restructured section, an old domain's path, anything not naturally a single page's own "old name" - list an explicit from/to pair instead:

redirects:
  - from: old-guide
    to: guides/new-guide/
  - from: moved-to-another-site
    to: https://example.com/docs

{
	"redirects": [
		{ "from": "old-guide", "to": "guides/new-guide/" },
		{ "from": "moved-to-another-site", "to": "https://example.com/docs" }
	]
}

• from - the old pretty-URL segment, same shape as redirect_from above
• to - either a root-relative path (resolved against the site's own baseURL, same convention theme.logo/ogImage already use) or a full https:// URL, for redirecting off-site entirely

redirects only ever applies to the main site tree - a bare to is a root-relative path that's only unambiguous at the site root. A version/locale tree wanting the same old-URL mapping needs its own page-level redirect_from instead.

page:rename stamps this for you

Renaming/moving a page with page:rename automatically adds its old path to the moved page's own redirect_from - on top of rewriting every relative Markdown link that pointed at it, the old URL itself keeps working too:

bxSites page:rename --from=guides/old-setup.md --to=guides/new-setup.md

Renaming a page more than once just keeps appending - a page's redirect_from list can carry as many old paths as it's had over time.

Conflicts

A build fails outright, rather than silently overwriting real content, if:

• A redirect's own from path collides with a real page already built at that path (BxSites.RedirectConflict)
• Two redirects (redirect_from entries, redirects config entries, or one of each) both target the same from path

What's out of scope (for now)

• Blog posts don't get redirect_from. The frontmatter key is only read for regular docs/ pages, not docs/blog/posts/** - a moved blog post needs its own redirects config entry instead.
• No wildcard/pattern redirects. Every from is one exact old path - there's no guides/old/* catch-all.