docs: document config-level redirects map

[claude]

Requested by Elliot Hesp · Slack thread

Fixes #

Summary

The config-level redirects map (shipped in #503) had no user documentation. This documents it.

Before: the redirects map in docs.json shipped in #503, but nothing in the docs told authors it existed or how it behaves.

After: the redirects authoring guide and the docs.json config reference both document the feature with examples — a central old-path -> new-destination map that returns a 307 temporary redirect on documentation page loads (including deleted/moved pages), does not affect platform API routes, and accepts root-relative, relative, or external URL destinations.

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 content change.

• Production build passes (NODE_ENV=production bun run --cwd app build)
• Format check clean on changed files
• Tested locally (bun dev, CLI command, or other relevant command)
• Updated docs/ (if user-facing)

Notes for reviewers

Two pages changed:

• docs/authoring/redirects.mdx — new "Redirect many URLs from docs.json" section: what the map is, when to use it vs a per-page frontmatter redirect (many/central vs one-off), a docs.json example, the 307/temporary behavior, coverage of deleted/moved pages, exclusion of API routes, and the supported value forms.
• docs/reference/docs-json.mdx — added the redirects top-level key to the config reference (index table + a <Property> section with description, type, and example), matching the format used for other keys.

Wording verified against the shipped code: app/src/server/config/schema.ts (redirects: z.record(z.string(), z.string())), app/src/lib/docs-redirect.ts (slash-tolerant key matching, external URLs verbatim, otherwise resolved against doc-root + ref), and app/src/pages/[[...path]].tsx (fires on the not-found branch with permanent: false = 307; API routes live in the App Router and never reach this catch-all).

🤖 Generated with Claude Code

https://claude.ai/code/session_01TfgQUAgxYfQb2La2Lvbi16

---

Generated by Claude Code

[docs-page]

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

use.docs.page/~507

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-507 environment in docs.page

2 services not affected by this PR

• Redis
• docs.page