Redirects

Leave a stub at the old path and set redirect in frontmatter:

---
redirect: /getting-started
---

docs.page returns a 307 Temporary Redirect to the destination before any page body renders. You can declare redirects two ways: a per-page redirect in frontmatter (above) for URLs whose file you keep, or a centralized redirects map in docs.json for old URLs whose files were removed. See The centralized redirects map.

For step-by-step rename workflows, see Redirects. Field syntax and other frontmatter options live in Page frontmatter.

On each page request, docs.page fetches the target .mdx file from GitHub and reads its frontmatter. If redirect is a non-empty string, the server returns a 307 Temporary Redirect to the resolved destination. Page body content is ignored.

The redirect runs in the same request path as normal page rendering. There is no separate redirect config to deploy.

External URLs (values starting with http://, https://, or //) are returned unchanged. Use these when the destination lives off your docs site.

Internal paths (root-relative paths such as /getting-started) are resolved against the current request context. You write the path once; docs.page builds the full URL from how the reader opened the page.

---
redirect: https://example.com/docs/new-location
---

The file body can be empty. Only redirect is required for the HTTP redirect. Other frontmatter fields are ignored at request time. Do not rely on query strings or hash anchors in redirect values. They are not part of the redirect contract.

A per-page stub covers one old URL each. When you delete a page and still want its old URL to forward somewhere, add an entry to the top-level redirects object in docs.json instead of leaving a file behind:

"redirects": {
  "/old-guide": "/guides/getting-started",
  "/legacy-api": "https://api.example.com/reference"
}

Keys are old root-relative doc paths; values are the destinations. Keys and values are matched tolerant of leading and trailing slashes, and values follow the same internal/external rules as frontmatter redirect: root-relative paths resolve against the current routing mode and ref, while http(s):// and // URLs are returned unchanged. A match issues the same 307 Temporary Redirect.

The map is consulted only on the 404 branch — that is, only when no .mdx file exists at the requested path. If a file still lives at that path, docs.page renders it (or follows its own frontmatter redirect) and never looks at the config map. Use the map for old URLs whose files were removed; use a frontmatter stub when you keep a file at the old path.

See redirects in the docs.json reference.

Internal redirects stay on the same site mode as the request. docs.page picks a base URL from the active route, appends the current ref segment when present, then appends your path.

With a ref segment on a custom domain, the ref appears after the domain root: https://docs.acme.com/~feature/new-page.

This behavior matters for previews and alternate hosts. A reader on a branch preview who hits a redirect lands on the same branch, not on production. A reader on your vanity subdomain or custom domain stays on that host instead of being sent to the default docs.page/{owner}/{repo} URL.

You do not hard-code https://docs.page/owner/repo in frontmatter for internal moves. Root-relative paths are enough.