Add redirect checker to block PRs with deleted pages missing redirects

[nearestnabors]

I got sick of broken links being reported, so I made this to ensure all deleted/moved markdown files are accounted for with redirects. The workflow does a lot of the heavy lifting of chain collapsing and updating internal links.

Summary

Adds automated redirect management when pages are deleted or moved. This ensures URL stability for bookmarks and SEO.

What's New

1. Pre-commit Hook Integration

When you delete a page file and try to commit:

• Auto-detects deleted .mdx/.md page files
• Auto-adds redirect entries to next.config.ts with placeholder destinations
• Blocks commit until you provide actual redirect destinations

2. Redirect Chain Collapsing

When an old redirect points to a page you're deleting:

• Detects the chain (e.g., old-path → deleted-path → new-path)
• Auto-collapses by updating the old redirect to point directly to the final destination

3. Internal Link Auto-Update

When next.config.ts is staged with new redirects:

• Scans all MDX/TSX files for internal links pointing to redirected paths
• Auto-updates those links to use the new destinations
• Auto-stages the modified files

Workflow

Deleting/Moving a Page

First commit attempt:

$ git rm app/en/guides/old-page/page.mdx
$ git commit -m "Remove old page"

🔗 Detected deleted page(s), checking for redirects...
✓ Added redirect entries to next.config.ts
❌ Commit blocked: Please update the placeholder destinations

Update the placeholder in next.config.ts:

// Change this:
destination: "/:locale/REPLACE_WITH_NEW_PATH",
// To this:
destination: "/:locale/guides/new-location",

Second commit attempt:

$ git add next.config.ts
$ git commit -m "Remove old page"

🔗 Updating internal links for new redirects...
✅ Internal links updated and staged
[commit succeeds]

Scripts Added/Modified

Script	Purpose
scripts/update-internal-links.sh	Updates internal links that point to redirected paths
scripts/check-redirects.sh	Now includes --auto-fix flag for auto-adding redirects
.husky/pre-commit	Integrates both scripts into the commit workflow

Test Plan

• Delete a page → redirect entry auto-added with placeholder
• Fill in placeholder → commit blocked until valid destination
• Enter invalid destination → helpful error message shown
• Old redirect points to deleted page → chain auto-collapsed
• Internal links to old path → auto-updated to new path
• All tests pass

---

🤖 Generated with Claude Code

---

Note

Introduces automated redirect enforcement and link maintenance for documentation.

• Adds GitHub Action check-redirects.yml to detect deleted/renamed markdown pages lacking redirects, comment on PRs with details, and fail the check
• Extends .husky/pre-commit to auto-add missing redirects (with placeholders), block commits until resolved, and auto-update/stage internal links when next.config.ts changes
• New TypeScript utilities: scripts/check-redirects.ts (validates/auto-fixes redirects, collapses redirect chains) and scripts/update-internal-links.ts (rewrites links to new destinations); wired via package.json (check-redirects, update-links)
• Updates next.config.ts with comprehensive redirects (notably moving guides/agent-frameworks and guides/tool-calling/mcp-clients to get-started/...) to preserve URLs
• Adjusts docs and component links (e.g., ToolFooter, multiple page.mdx files) to new get-started structure; minor copy edits and meta cleanup
• Regenerates public/llms.txt

^{Written by Cursor Bugbot for commit f552b84. This will update automatically on new commits. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
docs	Ready	Preview, Comment	Jan 20, 2026 7:47pm

[github-actions]

Style Review

Found 3 style suggestion(s).

Powered by Vale + Claude

[github-actions]

Style Review

Found 3 style suggestion(s).

Powered by Vale + Claude

[evantahler]

A question: Why are your new scripts bash? pnpm run check-redirects seems ok since we are already in TS, and that would allow the use of the node file utilities + glob which would make those scripts much smaller and easier to read

[nearestnabors]

A question: Why are your new scripts bash? pnpm run check-redirects seems ok since we are already in TS, and that would allow the use of the node file utilities + glob which would make those scripts much smaller and easier to read

Great question! I vibecoded this so had 0 opinion! IS this a blocker or a follow up, @evantahler ?

[evantahler]

Yes, I think this would be a blocker because it's adding something that's very hard for the team that normally works on docs to maintain. We will want to adjust and understand these scripts in the future. You can split this PR into 2 - merge in the found redirecet problems now, and work on the script out-of-band?

[nearestnabors]

@evantahler Nah, I'll do it now. We need to move both forward fast. I've tasked @torresmateo to check that it works, then I'll ping you for another look

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[cursor]

Pre-commit hook stages unintended working directory changes

Medium Severity

After running pnpm update-links, the hook uses git diff --name-only to find modified files and stages them. However, this command returns ALL files differing between the working directory and the index, not just files modified by update-links. If a user has other mdx/tsx/md files modified in their working directory but intentionally not staged (perhaps saving changes for a future commit), those files get auto-staged by xargs git add, causing unintended changes to be included in the commit.

 

[evantahler]

let's try it!