Walkthrough

Standardized documentation links: converted broken relative links (pointing outside deployed docs) to absolute GitHub URLs and converted GitHub URLs to relative paths for docs that live within the deployed docs/ directories. No code or public API changes.

Changes

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• #2229: Overlapping documentation link updates across similar doc paths.
• #2276: Related edits to Pro docs and license/setup link handling.
• #1747: Introduced the relative-link standard that motivated many of these changes.

Suggested labels

bug

Suggested reviewers

• Judahmeek
• alexeyr-ci2

Poem

🐰 A hop, a nibble, links made right,
Paths now land from left to right,
GitHub where needed, local where not,
Docs now find their proper spot—hooray, a carrot plot! 🥕

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Code Review: Documentation Link Fixes

Overall Assessment ✅

This PR successfully addresses the documentation link issues identified in #2317. The changes are well-thought-out and follow a clear, logical strategy: use GitHub URLs for files not deployed to the website, and relative links for files that exist on the website.

Strengths 💪

1. Clear Problem Categorization: The PR correctly identifies two distinct issues:

   • Broken relative links pointing to files outside deployed docs
   • Suboptimal GitHub URLs for files within the docs structure

2. Correct Link Strategy:

   • ✅ CHANGELOG.md → GitHub URL (lives at root, not deployed to website)
   • ✅ LICENSE_SETUP.md → GitHub URL (lives in react_on_rails_pro/, not deployed)
   • ✅ Internal docs → Relative paths (deployed to website, better UX)

3. Verification: The PR author verified:

   • Links resolve to existing files
   • GitHub URLs return 200
   • CHANGELOG 404 confirmed on live site

4. Consistent Pattern: Follows PR Replace all possible links with relative links #1747 guidelines for using relative links within docs

Code Quality ✅

All changes are documentation-only with no code modifications:

• 8 files changed
• 11 additions, 11 deletions (net zero impact)
• Simple link URL replacements

Verified Link Targets:

• CHANGELOG.md exists at root ✅
• react_on_rails_pro/LICENSE_SETUP.md exists ✅
• react_on_rails_pro/docs/configuration.md exists ✅
• docs/core-concepts/render-functions-and-railscontext.md exists ✅
• docs/configuration/configuration.md exists ✅
• react_on_rails_pro/docs/code-splitting-loadable-components.md exists ✅

Relative Path Analysis 🔍

Let me verify the relative paths resolve correctly:

From docs/api-reference/view-helpers-api.md:

• Link: ../../react_on_rails_pro/docs/configuration.md
• Resolves to: react_on_rails_pro/docs/configuration.md ✅

From docs/configuration/configuration-pro.md:

• Link: ../../react_on_rails_pro/docs/configuration.md
• Resolves to: react_on_rails_pro/docs/configuration.md ✅

From react_on_rails_pro/docs/caching.md:

• Link: ../../docs/core-concepts/render-functions-and-railscontext.md
• Resolves to: docs/core-concepts/render-functions-and-railscontext.md ✅

From react_on_rails_pro/docs/home-pro.md:

• Link: ./code-splitting-loadable-components.md
• Resolves to: react_on_rails_pro/docs/code-splitting-loadable-components.md ✅
• Link: ../../docs/configuration/configuration.md
• Resolves to: docs/configuration/configuration.md ✅

From react_on_rails_pro/docs/troubleshooting.md:

• Link: ./installation.md (x2)
• Resolves to: react_on_rails_pro/docs/installation.md ✅

All relative paths are correct! ✅

Potential Concerns ⚠️

1. Cross-Package Relative Links

The changes introduce relative links between the main docs and pro docs:

# From docs/api-reference/view-helpers-api.md:
../../react_on_rails_pro/docs/configuration.md

Consideration: If the documentation deployment structure ever separates open-source docs from Pro docs (e.g., hosting them at different domains), these cross-package relative links would break.

Current Status: This appears to be the intended structure based on the sc-website deployment, so this is acceptable.

2. GitHub URLs Point to master Branch

The GitHub URLs use /blob/master/:

https://github.com/shakacode/react_on_rails/blob/master/CHANGELOG.md

Consideration: If users are viewing docs for a specific version/tag, they'll always see the master branch version of CHANGELOG/LICENSE_SETUP.

Alternatives:

• Use tagged URLs for releases (e.g., /blob/v16.2.0/CHANGELOG.md)
• Use GitHub's default branch reference

Current Approach: Using master is simpler and ensures users always see the latest, which is probably desirable for CHANGELOG and LICENSE_SETUP docs.

Security ✅

No security concerns. This is documentation-only with no code execution.

Performance ✅

No performance impact. Static documentation links have zero runtime cost.

Test Coverage ✅

Test Plan from PR:

• Verify links work on local markdown preview
• After deploy, verify links work on shakacode.com

Recommendation: After merging, verify on the live website:

1. https://www.shakacode.com/react-on-rails/docs/configuration/configuration-deprecated/ → CHANGELOG link
2. https://www.shakacode.com/react-on-rails-pro/docs/installation/ → LICENSE_SETUP link
3. Verify relative links navigate correctly within the website

Best Practices & Conventions ✅

Follows repository guidelines from CLAUDE.md:

• ✅ Documentation-only changes (no changelog entry needed)
• ✅ Builds on previous work (PR Replace all possible links with relative links #1747)
• ✅ Clearly documented in PR description
• ✅ References related issue (Docs: Fix broken links and inconsistent URL patterns #2317)
• ✅ Separates concerns (created Docs: Remove or update outdated 'Invalid Token Workaround' section in troubleshooting.md #2321 for content issues)

Recommendations 📝

1. After Merge: Test the links on the live deployed website to confirm they work as expected

2. Future Enhancement: Consider adding a CI check that validates:

   • Relative links point to files that exist
   • Relative links point to files in the docs/ directories (deployed to website)
   • GitHub URLs are used for files outside docs/ directories

3. Documentation: Consider documenting the link strategy somewhere (e.g., in CONTRIBUTING.md):

   • Use relative links for files within docs/ directories
   • Use GitHub URLs for files outside docs/ (CHANGELOG, LICENSE, etc.)

Final Verdict: ✅ APPROVE

This is a clean, well-documented fix for legitimate documentation issues. The changes are:

• Low risk (documentation only)
• Well-verified (author checked all paths)
• Strategically sound (correct use of relative vs. GitHub URLs)
• Following established patterns (PR Replace all possible links with relative links #1747)

Recommend merging after CI passes, then verify on the live website.

Great work addressing these documentation issues systematically! 🎉

Greptile Overview

Greptile Summary

This PR systematically fixes documentation link issues by applying a clear strategy: use GitHub URLs for files not deployed to the website (CHANGELOG.md, LICENSE_SETUP.md), and use relative links for documentation files that exist on the website.

Changes Made

Files converted from relative → GitHub URLs (not on website):

• CHANGELOG.md references in docs/configuration/configuration-deprecated.md (2 links)
• LICENSE_SETUP.md references in react_on_rails_pro/docs/installation.md and react_on_rails_pro/docs/updating.md (2 links)

Files converted from GitHub URLs → relative links (on website):

• Pro configuration docs in docs/api-reference/view-helpers-api.md and docs/configuration/configuration-pro.md
• Rails Context docs in react_on_rails_pro/docs/caching.md
• Installation and loadable-components docs in react_on_rails_pro/docs/home-pro.md and react_on_rails_pro/docs/troubleshooting.md

Verification

All relative paths have been validated to resolve correctly:

• Paths use correct ../../ navigation between docs/ and react_on_rails_pro/docs/ directories
• Local paths within react_on_rails_pro/docs/ use ./ prefix for clarity
• All target files exist in the repository

Impact

This improves documentation UX by keeping users on the website when browsing docs (rather than redirecting to GitHub), while ensuring links to non-deployed files point to the correct GitHub URLs instead of 404ing.

Confidence Score: 5/5

• This PR is safe to merge with no issues found
• The changes are purely documentation link updates with a clear, consistent strategy. All relative paths have been verified to resolve correctly, and the approach (GitHub URLs for non-website files, relative links for website files) is sound and well-documented in the PR description.
• No files require special attention

Important Files Changed

Sequence Diagram

sequenceDiagram
    participant User
    participant Website as shakacode.com/docs
    participant GitHub as github.com

    Note over User,GitHub: Scenario 1: User clicks link to website docs
    User->>Website: Browse docs/configuration/configuration-pro.md
    User->>Website: Click link to react_on_rails_pro/docs/configuration.md
    Note over Website: Uses relative link (../../react_on_rails_pro/docs/configuration.md)
    Website->>Website: Navigate to same site
    Note over User,Website: ✅ Better UX: Stay on website

    Note over User,GitHub: Scenario 2: User clicks link to non-website files
    User->>Website: Browse docs/configuration/configuration-deprecated.md
    User->>Website: Click link to CHANGELOG.md
    Note over Website: Uses GitHub URL (CHANGELOG not deployed to website)
    Website->>GitHub: Redirect to github.com/.../CHANGELOG.md
    GitHub->>User: Show CHANGELOG on GitHub
    Note over User,GitHub: ✅ Correct: File only exists on GitHub

Code Review - PR #2322

✅ Overall Assessment

This PR correctly addresses the documentation link issues identified in #2317. The changes are well-structured, properly motivated, and follow established conventions from PR #1747.

🎯 Code Quality & Best Practices

Strengths:

• ✅ Clear commit separation: Two commits with distinct purposes (broken links → GitHub URLs, GitHub URLs → relative links)
• ✅ Follows established patterns: Adheres to PR Replace all possible links with relative links #1747 guidelines for relative vs absolute links
• ✅ Well-documented rationale: PR description clearly explains why each change was made
• ✅ Proper link syntax: All GitHub URLs use correct format with /blob/master/ path
• ✅ User experience improvement: Keeps users on website instead of redirecting to GitHub unnecessarily

Link Strategy (Correctly Applied):

1. Files NOT deployed to website (CHANGELOG.md, LICENSE_SETUP.md, sig/README.md) → GitHub URLs ✅
2. Files deployed to website (docs within docs/ and react_on_rails_pro/docs/) → Relative paths ✅

🔍 Technical Verification

Relative Path Validation:

I verified the relative paths resolve correctly:

• docs/api-reference/ → ../../react_on_rails_pro/docs/configuration.md ✅
• docs/configuration/ → ../../react_on_rails_pro/docs/configuration.md ✅
• react_on_rails_pro/docs/caching.md → ../../docs/core-concepts/render-functions-and-railscontext.md ✅
• react_on_rails_pro/docs/home-pro.md → ./code-splitting-loadable-components.md ✅
• react_on_rails_pro/docs/home-pro.md → ../../docs/configuration/configuration.md ✅

GitHub URL Targets (All Exist):

• ✅ CHANGELOG.md
• ✅ react_on_rails_pro/LICENSE_SETUP.md
• ✅ react_on_rails/sig/README.md

🚀 Performance Considerations

No performance impact. This is a documentation-only change affecting:

• 8 markdown files
• 10 additions, 10 deletions (net zero)
• No code changes to runtime behavior

🔒 Security Concerns

None. All changes are to documentation links. No sensitive data, no security implications.

🧪 Test Coverage

Not applicable - Documentation changes only.

Suggested verification steps (as noted in PR description):

• Verify links work in local markdown preview
• After deploy, verify links work on shakacode.com

Additional suggestion:
Consider running the link checker after deployment:

# From sc-website repo after deploying these changes
bundle exec rake linkchecker:check

📋 Minor Observations

1. Consistency check: The change in docs/contributor-info/rbs-type-signatures.md (line 60) changes a relative link to GitHub URL. This is correct since react_on_rails/sig/README.md is not deployed to the website, but worth noting for consistency.

2. Documentation note: The PR correctly identifies that Pro documentation is in a separate directory. The note in configuration-pro.md about future consolidation is helpful context.

✅ Recommendation

APPROVE - This PR is ready to merge.

Rationale:

• Fixes real broken links (404s on production website)
• Improves UX by using relative links where appropriate
• No code changes, no test impact, no security concerns
• Well-documented and follows established patterns
• All link targets verified to exist

Post-merge action items:

• Verify links work correctly on shakacode.com after deployment
• Consider documenting the "files deployed vs not deployed" distinction in contributor docs to prevent future confusion

Great work @ihabadham! This is exactly the right approach for fixing documentation links. 🎉