Redirects

Before you begin

• The new URL path decided before you change files, see Write → Where pages live for how file paths map to URLs
• Preview running locally when you want to confirm the new page and redirect

For how redirects behave in production, branch previews, vanity subdomains, and custom domains, see Redirects. Field syntax lives in Page frontmatter.

When you change a published URL, update three things: the file at the new path, the sidebar entry, and a redirect stub at the old path.

• Serve content from the new URL

  Rename or move the file under docs/ to match the new URL. For example, move docs/installation.mdx to docs/getting-started.mdx so the page serves at /getting-started.

• Point sidebar at the new href

  Update the sidebar in docs.json so the entry points at the new href. Remove or replace the old path, readers should not land on a dead link from navigation. See Organize.

• Keep bookmarks working with a redirect stub

  Create a redirect stub at the old file path (next section). Without it, bookmarks and external links to the old URL return 404 (which can negatively impact SEO rankings).

Leave a minimal file at the old path and set redirect in frontmatter to the destination.

• Keep a stub file at the old path

  Create or replace the file at the old location, for example docs/installation.mdx after you moved content to docs/getting-started.mdx.

• Declare the destination in frontmatter

  Set redirect pointing at the new location:

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

  title and description are not required. The body can be empty. docs.page reads redirect and returns a 307 Temporary Redirect before any page content renders.

• Resolve targets correctly across hosts

  Internal moves: use a root-relative path: /getting-started. No domain, no .mdx extension.

  External destinations: use a full URL starting with https://.

  Internal paths resolve against the same routing mode as the request (production, branch preview (~ref), vanity subdomain, or custom domain), so readers stay on the host and ref they started on. You do not need to hard-code https://docs.page/owner/repo for in-repo moves.

Stubs work when you keep a file at the old path. When you delete pages outright — or need to forward many old URLs at once — add a centralized redirects map to docs.json instead of leaving a file behind for each one:

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

Keys are the old root-relative paths; values are internal paths or external https:// URLs. docs.page consults this map only when no file exists at the requested path, so it is the tool for URLs whose files were removed. Keep frontmatter stubs for the case where a file still lives at the old path.

See redirects and Redirects → The centralized redirects map.

After you add or change redirect stubs:

• See the new page at its updated URL

  Open Preview and confirm the moved page renders at the new path. Confirm sidebar links point to the right href.

• Confirm the old URL redirects in preview

  Open the old URL in the same preview session, for example /installation after you moved content to /getting-started. The browser should land on the new page without a 404.

• Catch broken redirect targets before merge

  npx @docs.page/cli check

  The CLI scans frontmatter redirect targets the same way it validates internal links in page content. Fix any broken targets before you merge.

  For severity flags, monorepo paths, and CI setup, see CLI → Check documentation.

• Redirects: How per-page redirects work across routing modes, HTTP status, and limits.
• Page frontmatter: Field reference for redirect and other per-page YAML options.
• Organize: Point sidebar entries at the new URL after you move a page.
• Preview: Confirm the new page and redirect locally.