Skip to content

docs: delete _deprecated/, prune dead-end redirects, add orphan-page check to CI - #2279

Open
palango wants to merge 6 commits into
mainfrom
palango/2252-cleanup-deprecated-redirects-orphan-check
Open

docs: delete _deprecated/, prune dead-end redirects, add orphan-page check to CI#2279
palango wants to merge 6 commits into
mainfrom
palango/2252-cleanup-deprecated-redirects-orphan-check

Conversation

@palango

@palango palango commented Aug 24, 2026

Copy link
Copy Markdown
Contributor

_deprecated/ held 105 unreferenced copies of live pages that contributors occasionally edited by mistake, and 214 of the 635 redirects in docs.json pointed at another redirect or at a path with no page behind it. Nothing in CI noticed when a page on disk fell out of navigation, which is how 25 pages went orphaned. This PR deletes _deprecated/, repairs the redirect graph so every redirect ends at a live page, and adds the orphan check as a report-only step to the existing docs-validation workflow. Closes #2252.

Changes

  1. _deprecated/ is deleted. It had zero references from docs.json or live content. Before deleting, every file was compared against its closest live counterpart: 30 are byte-identical, the other 75 differ only where the live page moved on (fixed links, updated dates, added descriptions) or where the content is retired L1/Alfajores material. Nothing needed porting. No redirects added, since these paths were never reachable.
  2. 49 redirect chains are flattened. AGENTS.md says a redirect points at the final page; these pointed at another redirect's source. Includes the thirdweb chain named in the issue.
  3. 162 dead-end redirects are re-pointed and 3 removed. The issue left removal vs re-pointing open; re-pointing keeps old inbound links working, so every redirect whose chain ended at a missing page now points at the live page that answers the same question (most had near-exact matches, e.g. /cli/account to /tooling/libraries-sdks/cli/account). The 3 removed entries are the /glossary group: no glossary page exists anywhere, and they formed a redirect cycle. Every new destination exists on disk, is listed in navigation, and is not itself a redirect source.
  4. scripts/check-orphans.sh diffs .mdx files on disk against the page paths under navigation in docs.json and exits 1 when it finds orphans. The workflow step has continue-on-error: true, so task: Orphaned-pages audit — re-nav or delete the 22 pages on disk that are missing from navigation #2253 flips it to failing by deleting that single line.

The counts differ from the issue because the redirects drifted since it was measured at bdf40b3; they were re-derived on the branch as the issue asks.

Verification

bash scripts/check-orphans.sh prints the 25 known orphans (the count #2253 tracks) and exits 1.

npx mintlify broken-links:

success no broken links found

Re-running the redirect analysis after the last commit: 632 redirects, 0 chains, 0 dead ends.

Notes for #2253

A few re-pointed redirects have an exact-match target among the 25 orphaned pages (the contractkit migration guides, tooling/overview/setup/*), but orphans cannot be redirect targets, so they point at the nearest in-nav page instead. If #2253 adds those pages to navigation, the redirects can be tightened.

@palango
palango requested a review from a team as a code owner August 24, 2026 09:35
@palango
palango requested a review from GigaHierz August 24, 2026 09:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

task: Cleanup — delete _deprecated/, prune dead-end redirects, add an orphan-page check to CI

1 participant