Link checker cleanup: Fix 62 broken links across codebase

[ihabadham]

Summary

Link checker (lychee) is currently failing with 62 errors on master. This issue tracks cleaning up all broken links with proper fixes for each category.

Note: This issue has been corrected to fix initial analysis errors (see PR #2229 for details).

Error Breakdown (62 total)

Category 1: Missing Git Tags - CHANGELOG Version Comparisons (9 errors)

Problem: CHANGELOG.md references version comparison links for versions that were never git-tagged.

Affected versions:

• 8.0.7 (line 1944) - tag doesn't exist, only 8.0.6 exists
• 10.1.2 (line 1934) - tag doesn't exist, only 10.1.1 and 10.1.3 exist
• 16.2.0.beta.19 (line 1871) - tag doesn't exist
• 16.2.0.beta.20 (line 1870) - tag doesn't exist
• Plus 5 more old version comparisons (v1.x, v2.x era)

Proposed fix:

• Investigate if these versions were actually released (check git history, releases page)
• If released but not tagged: Create the git tags retroactively
• If never released: Remove the comparison links from CHANGELOG (clean up historical errors)

Command to verify:

git tag | grep -E "^8\.0\.7$|^10\.1\.2$|^16\.2\.0\.beta"

---

Category 2: Moved Files - Local File References (7 errors)

Problem: Local file:// and relative path references use old paths from before docs reorganization.

Affected files and their new locations:

Old Path (404)	New Path (exists)	Referenced in
docs/release-notes/16.0.0.md	docs/upgrading/release-notes/16.0.0.md	CHANGELOG.md:291
docs/additional-reading/turbolinks.md	docs/building-features/turbolinks.md	NEWS.md
docs/guides/i18n.md	docs/building-features/i18n.md	NEWS.md
docs/guides/upgrading-react-on-rails.md	docs/upgrading/upgrading-react-on-rails.md	NEWS.md, README.md
docs/guides/auto-bundling-file-system-based-automated-bundle-generation.md	docs/core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md	README.md
lib/generators/.../react_on_rails.rb#L27	Old initializer path	CHANGELOG.md
sig/README.md	react_on_rails/sig/README.md	docs/contributor-info/rbs-type-signatures.md

Status: ✅ FIXED in PR #2229 - All 7 local file references have been updated.

Note: SUMMARY.md was initially listed here but is actually excluded from lychee checking (.lychee.toml line 49), so it was never an error.

---

Category 2b: Website URLs - Docs Reorganization (11 errors)

Problem: Shakacode.com documentation URLs broken by docs reorganization (PR #1845).

Affected URLs (all in CHANGELOG.md):

Old URL Path	New URL Path
/docs/guides/upgrading-react-on-rails	/docs/upgrading/upgrading-react-on-rails
/docs/guides/configuration	/docs/api-reference/configuration
/docs/guides/rspec_configuration	/docs/building-features/rspec-configuration
/docs/rails/turbolinks	/docs/building-features/turbolinks
/docs/additional-details/migrating-from-react-rails	/docs/migrating/migrating-from-react-rails
/docs/react-on-rails-pro/react-on-rails-pro	/docs/pro/react-on-rails-pro

Status: ✅ FIXED in PR #2229 - All 11 website URLs have been updated to reflect the current docs structure.

---

Category 3: Pro Package Issues (8 errors)

Problem: Old branch references, moved spec/dummy paths, missing files in Pro package.

Errors:

1. react_on_rails_pro/CHANGELOG.md: Compare link 4.0.0-rc.14...4.0.0-rc.15 returns 404
2. react_on_rails_pro/CONTRIBUTING.md:
   • File reference: packages/node-renderer/tests/helper.ts - doesn't exist
   • Old branch: blob/more_test_and_docs/... - branch deleted
3. react_on_rails_pro/docs/caching.md: Old path docs/basics/generator-functions-and-railscontext.md
4. react_on_rails_pro/docs/code-splitting-loadable-components.md: Old spec/dummy paths (2 links)
5. react_on_rails_pro/docs/home-pro.md: Old path docs/configuration.md
6. react_on_rails_pro/README.md: Workflow badge pro-package-tests.yml - doesn't exist

Proposed fix:

• Verify if RC 14→15 was actually released, fix or remove link
• Update or remove reference to helper.ts file
• Update old branch reference to current branch or remove
• Update all docs/basics/ paths to new locations
• Update spec/dummy file references to correct paths
• Fix workflow badge or remove if workflow was renamed

---

Category 4: Deleted GitHub User Accounts (7 errors)

Problem: Contributors deleted their GitHub accounts. Links return 404.

Affected users (all in CHANGELOG.md):

• alleycat-at-git
• Conturbo
• jblasco3
• nostophilia
• railsme
• samphilipd
• wouldntsavezion

Proposed fix:

• Keep the links (historical attribution is important)
• Add these specific URLs to lychee exclusions via regex pattern:

# .lychee.toml
exclude = [
  'https://github\.com/(alleycat-at-git|Conturbo|jblasco3|nostophilia|railsme|samphilipd|wouldntsavezion)(/.*)?'
]

---

Category 5: External Site Issues (15+ errors)

Problem: Third-party sites with various issues. Need to investigate each.

5a. SSL Certificate Issues (4 errors) - PR #2230 will exclude 3

• https://www.blinkinc.com/ - SSL certificate expired (in PROJECTS.md)
• https://www.localwise.com/ - SSL verification failed (in PROJECTS.md)
• https://www.mycfsapp.com/ - SSL hostname mismatch (in PROJECTS.md)
• https://scoutapp.com/ - SSL hostname mismatch (in README.md)

Proposed fix:

• PR Add SSL certificate error exclusions to lychee config #2230 will exclude first 3 from link checking
• For scoutapp.com: Check if domain changed, update or exclude

5b. Dead/Moved Services (3 errors)

• https://ruby-gem-downloads-badge.herokuapp.com/react_on_rails?type=total - Returns 404 (Heroku service shut down)
• https://ror-spec-dummy.reactrails.com/ - Connection failed (demo site down)
• http://www.shakacode.com/work/index.html - Returns 404 (old site)

Proposed fix:

• Remove ruby-gem-downloads-badge (service no longer exists)
• Check if ror-spec-dummy moved, update or remove
• Update shakacode.com/work to current URL or remove

5c. Timeouts/Intermittent (6+ errors)

• https://reactrails.com/ - Sometimes works (200), sometimes 504/timeout
• https://devchat.tv/ruby-rogues/... - Timeout
• https://undeveloped.com/ - Timeout
• http://chlg.co/1GV2m9p - Timeout (short link service)
• http://www.pivotaltracker.com/ - Connection failed
• https://questlab.pro/blog-posts/... - Connection closed

Proposed fix:

• Test each URL multiple times to confirm if truly down or just slow
• For dead short links (chlg.co): Try to find original URL
• For dead services: Find alternatives or remove
• For intermittent sites: Increase timeout in lychee config or exclude

5d. Access Restrictions (2 errors)

• https://badge.fury.io/js/react-on-rails - Returns 403 (but actually works via redirect)
• https://stackoverflow.com/questions/... - Returns 403 (rate limiting?)

Proposed fix:

• Verify badge.fury.io works in browser, adjust lychee config to follow redirects
• Verify StackOverflow link, may need to exclude from checking

---

Category 6: Renamed/Moved Repositories (1 error)

Problem: Redux repository was renamed, old links don't redirect.

• https://github.com/reactjs/redux/issues/1335 → should be https://github.com/reduxjs/redux/issues/1335

Proposed fix:

• Update link to use new repo path: reduxjs/redux

---

Category 7: External Webpacker Reference (1 error)

Problem: Link to external repo's webpacker.yml that no longer exists.

• https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/config/webpacker.yml - Returns 404

Decision made: IGNORE - This is in historical upgrade docs, and line 394 has a working alternative example.

---

Proposed Action Items

Priority 1 (blocking link checker):

• Fix Category 2: Update all local file path references (7 errors) - FIXED in PR Fix broken links from docs reorganization (file paths and website URLs) #2229
• Fix Category 2b: Update shakacode.com docs URLs (11 errors) - FIXED in PR Fix broken links from docs reorganization (file paths and website URLs) #2229
• Fix Category 6: Update Redux repo link (1 error)
• Fix Category 5b: Remove dead service badges (3 errors)

Priority 2 (cleanup):

• Fix Category 1: Handle missing git tags (9 errors)
• Fix Category 3: Pro package link cleanup (8 errors)

Priority 3 (exclusions):

• Add Category 4: Exclude deleted user profiles (7 errors)
• Add Category 5a: Exclude SSL error sites (already in PR Add SSL certificate error exclusions to lychee config #2230 for 3)
• Add Category 5c: Investigate and exclude/fix timeouts (6+ errors)
• Add Category 5d: Configure access restriction handling (2 errors)

Expected Outcome

After completing all fixes:

• ✅ 18 errors fixed in PR Fix broken links from docs reorganization (file paths and website URLs) #2229 (7 local file paths + 11 website URLs)
• ~20 more errors to fix by updating paths and links
• ~20 errors to exclude via lychee config (deleted users, SSL sites, dead services)
• ~10 errors to resolve by investigating/fixing external timeouts
• Link checker passes on master ✅

Related PRs

• PR Fix broken links from docs reorganization (file paths and website URLs) #2229 - ✅ READY TO MERGE - Fixed all docs reorganization links (7 local + 11 website URLs)
• PR Add SSL certificate error exclusions to lychee config #2230 - Adds SSL exclusions for 3 sites (partial fix for Category 5a)

Corrections Made to This Issue

This issue was initially created with some errors, which have been corrected:

1. SUMMARY.md was incorrectly listed - This file is excluded from lychee checking (.lychee.toml line 49), so it never had errors
2. Deleted user count was wrong - 7 users, not 6 (missed wouldntsavezion)
3. Shakacode.com URLs were not properly categorized - Now separated into Category 2b with proper detail

For full details, see the verification report in PR #2229 discussions.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

_{You can configure auto-planning by selecting labels in the issue_enrichment configuration.}

🔗 Similar Issues

Possible Duplicates

• Fix broken internal links from docs reorganization (#1845) #2226

Related Issues

• Fix broken file path links in documentation #2231
• Documentation: Add guide for migrating to Rspack with Shakapacker 9 #1863
• Phase 7-8: Final Monorepo Polish and Documentation #2106
• Monorepo of pro and basic #1765

🔗 Related PRs

#1631 - fix: address a number of typos and grammar issues [merged]
#1747 - Replace all possible links with relative links [merged]
#1800 - Add automated markdown link checking GitHub Action [merged]
#1902 - Optimize CI with change-driven gating [merged]
#1982 - Remove dead links from major-performance-breakthroughs-upgrade-guide.md [merged]
#2219 - Migrate from markdown-link-check to lychee [merged]

👤 Suggested Assignees

• justin808
• ihabadham
• G-Rath
• Judahmeek

---

🧪 Issue enrichment is currently in early access.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false