docs: document the docs.json redirects map

[claude]

Requested by Ben Cook · Slack thread

Summary

Before: the docs only described per-page redirect: frontmatter and explicitly stated that redirects are "not a central table in docs.json" (and that there are "no wildcard or catch-all rules in docs.json").

After: the docs also document the supported centralized docs.json redirects object-map — its 307 Temporary Redirect behavior, external-URL support (http(s):// / // values returned unchanged), and the important 404-branch-only caveat: the map is consulted only when no .mdx file exists at the requested path (a deleted/moved page). If a file still lives at that path, its own frontmatter redirect governs and the config map is not consulted.

How

• docs/reference/docs-json.mdx — added redirects to the field overview table and a full ## redirects section showing the { "from": "to" } object-map shape, an example, internal/external value rules, the 307 status, and the 404-branch-only behavior.
• docs/features/redirects.mdx — corrected the stale "per page file, not a central table in docs.json" sentence and the "no wildcard or catch-all rules in docs.json" table row; added a "The centralized redirects map" section covering the 404-branch-only behavior, 307 status, and internal/external destinations.
• docs/authoring/redirects.mdx — added a "Forward deleted pages in bulk" section recommending the docs.json map for removed pages, and noted the alternative in the stub callout, while keeping the frontmatter-stub guidance for the keep-a-file case.

Source of truth: schema at app/src/server/config/schema.ts:43 (redirects: z.record(z.string(), z.string()).catch({})) and runtime resolveConfigRedirectDestination in app/src/lib/docs-redirect.ts, called on the not-found (404) branch from app/src/pages/[[...path]].tsx. The redirects key is already emitted in the generated /schema.json because that schema is derived from ConfigSchema, so no separate JSON file needed updating.

Scope

• app/ (hosted site, MCP, Ask AI)
• packages/cli/
• packages/mdx-bundler/
• docs/ (product documentation)
• Repo / CI / other

Type of change

• Bug fix
• New feature
• Documentation
• Refactor / chore

Test plan

Docs-only change; no runtime behavior touched.

• bun run check passes locally
• Updated docs/ (if user-facing)

Notes for reviewers

Documentation-only. All documented behavior was verified against the schema and runtime cited above — no behavior was invented. Anchor links (#the-centralized-redirects-map, #redirects, #forward-deleted-pages-in-bulk) assume the standard slugger (lowercase, spaces to hyphens, punctuation stripped); please confirm they resolve in preview.

---

Generated by Claude Code

[docs-page]

To preview the documentation for this pull request, visit the following URL:

use.docs.page/~508

Documentation is deployed and generated using docs.page

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[railway-app]

🚅 Deployed to the docs.page-pr-508 environment in docs.page

2 services not affected by this PR

• Redis
• docs.page