Fix legacy documentation 404s: 67 redirects plus 4 pre-existing defects

[danstotts-ops]

Summary

Closes the legacy-URL 404 gap on docs.runpod.io. 67 new redirect entries, plus repairs to four pre-existing defects in the redirects array. Scoped entirely to docs.json.

Source of truth: the GSC "Not found (404)" export (1,000 of 1,095 rows; GSC caps the export).

What the 1,095 actually is

The headline number is not 1,095 broken doc pages. Broken down:

Bucket	Count	Action
Non-docs-host paths	438	Out of scope for this repo
Docs asset / code / example paths	178	Not pages, no redirect appropriate
Actual unique docs paths	319	In scope
... already covered by existing redirects	35	No change
... covered by this PR	67	Added here
... deliberately left 404	remainder	See below

Why this is not a wildcard

Mintlify supports { "source": "/docs/:slug*", "destination": "/:slug*" }, and it is the obvious-looking fix. It does not work here and would make things worse.

The legacy structure used flat GitBook slugs (/docs/create-pod, /docs/handler-async); the current IA is nested (/pods/manage-pods, /serverless/handlers/...). Tested against the live sitemap, stripping the /docs prefix resolves 1 of 71 archived legacy paths. Shipping the wildcard would convert hard 404s into 308-redirects-to-404: it burns crawl budget, creates soft-404 signals, and hides the problem from the Page Indexing report without fixing it.

Same trap on the CLI block: dead paths use underscores (/references/runpodctl/runpodctl_config), live pages use hyphens (/runpodctl/reference/runpodctl-config). Every one of these migrations changed the slug shape, not just the prefix, so each needs an explicit entry.

Two additions that carry real traffic

Both still 404'd after the main pass and both have twelve-month GSC demand:

Path	Impressions	Clicks	Destination
/tutorials/pods/run-fooocus	7,386	218	/tutorials/pods/comfyui
/category/vllm-endpoints	411	5	/serverless/vllm/overview

The Fooocus tutorial was removed with no direct replacement. ComfyUI is the closest surviving equivalent (same task, image-generation UI on a Pod). Flagging it as a judgment call, happy to change it.

Pre-existing defects repaired (drive-by, separate commit)

All four were on main before this branch:

• pods/references/environment-variables had no leading slash on source or destination, producing a relative redirect target.
• Three 2-hop chains flattened to their final destination:
  • /serverless/endpoints/job-operations -> /serverless/endpoints/send-requests
  • /endpoints/health -> /serverless/endpoints/send-requests
  • /glossary -> /get-started/concepts

Deliberately left as 404

Paths with no inbound links, no impressions, and no surviving equivalent. A 404 is the correct response for content that no longer exists, and Google drops these on its own. Mintlify cannot emit 410, so 404 is also the only option. Redirecting them to a section hub would manufacture soft 404s and make the property worse.

Example: /pods/monitoring/prometheus (one inbound link, zero impressions, no equivalent page).

The right success metric is zero dead paths with external signal, not zero 404s.

Verification

• All 99 unique redirect destinations return HTTP 200 live. No exceptions.
• 0 duplicate sources.
• 0 redirect chains (a destination that is itself a source).
• 0 malformed entries (every source and destination is root-relative).
• docs.json parses as valid JSON; redirect count 223 -> 290.
• node scripts/validate-tooltips.js passes.

Not addressed here, worth a separate conversation

The largest single traffic loss in the dead set is the /hosting/* cluster, deleted with no replacement: /hosting/overview (11,750 impressions), /hosting/maintenance-and-reliability (2,567), /hosting/burn-testing (820). Roughly 15,100 impressions a year of host and partner facing documentation with no equivalent anywhere in the current 304-page site. Those three currently redirect to /references/security-and-compliance, which is a holding pattern, not an answer. That is a content decision, not a redirect decision.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
runpod-docs	🟢 Ready	View Preview	Jul 28, 2026, 5:06 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.