Move docs home copy upstream and fix tutorial anchor by justin808 · Pull Request #2671 · shakacode/react_on_rails

justin808 · 2026-03-18T05:14:46Z

Summary

Moves the canonical docs-home copy into docs/README.md so reactonrails.com no longer has to own that prose in prepare-docs.mjs.

Also fixes the tutorial table-of-contents anchor so it points to the existing What's Next? section instead of the stale #conclusion anchor.

Changes

Replaces the generic docs README with the canonical docs landing content used by the site
Keeps the GitHub-friendly docs website link in the upstream README
Fixes docs/oss/getting-started/tutorial.md TOC link from #conclusion to #whats-next

Why

This is the remaining upstream/site-boundary cleanup from the docs work. The site repo should present docs, not own canonical docs content.

Validation

reactonrails.com: npm run prepare
reactonrails.com: npm run build

Note

Low Risk
Low risk: documentation-only restructuring and link/anchor fixes with no runtime code changes.

Overview
Updates docs/README.md from a GitHub navigation stub to a more opinionated docs landing page that explains OSS vs Pro, reorganizes entry points by user intent, and adds Pro evaluation/help links.

Fixes the tutorial table-of-contents to link to the existing “What’s Next?” section (#whats-next) instead of a stale conclusion anchor.

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

Summary by CodeRabbit

Documentation
- Renamed top-level docs to "Documentation Guide" and reframed intro to present OSS vs Pro paths with selection criteria.
- Reorganized navigation into path-oriented sections (new app, add-to-app, OSS→Pro evaluation) and consolidated deeper links.
- Reduced main Pro feature listings, updated help links, and added a friendly evaluation policy.
- Tutorial TOC anchor changed: "Conclusion" → "What's Next?"

coderabbitai · 2026-03-18T05:15:04Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: dda59dd1-f0e3-49c9-b192-c925abbb7c4d

📥 Commits

Reviewing files that changed from the base of the PR and between cca476a and 2cc798e.

📒 Files selected for processing (1)

docs/README.md

🚧 Files skipped from review as they are similar to previous changes (1)

docs/README.md

Walkthrough

Top-level documentation was reworked: docs/README.md rewritten as a path-oriented "Documentation Guide" replacing the previous OSS/Pro navigation and trimming several links; docs/oss/getting-started/tutorial.md updated a table-of-contents anchor from #conclusion to #whats-next.

Changes

Cohort / File(s)	Summary
Documentation Restructuring `docs/README.md`	Rewrote top-level README into "Documentation Guide"; replaced OSS/Pro navigation with path-based sections (new app, add to existing, OSS), simplified deep-linking and Pro feature list, adjusted help/support and added an evaluation policy.
Tutorial Navigation `docs/oss/getting-started/tutorial.md`	TOC anchor rename: `#conclusion` → `#whats-next` (label changed to "What's Next?"); no other content edits.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Poem

🐰 I hopped through pages, tidy and bright,
Swapping headings, pruning links just right.
"Conclusion" nudged to "What's Next?" — a tiny dance,
Paths now lined for every app's advance. 🥕✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title concisely and accurately summarizes the two main changes: moving the docs home content upstream to docs/README.md and fixing the tutorial anchor link from `#conclusion` to `#whats-next`.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch jg-codex/docs-home-readme-upstream

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.

❤️ Share

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

greptile-apps · 2026-03-18T05:16:12Z

Greptile Summary

This PR makes two focused documentation changes: it replaces the GitHub-navigation-centric docs/README.md with a leaner, user-journey-oriented landing page (previously owned by the reactonrails.com site repo), and fixes a broken TOC anchor in tutorial.md that pointed to the non-existent #conclusion heading instead of the live #whats-next section.

Key changes:

docs/README.md is rewritten as canonical docs-home prose, reducing it from 76 lines to 43 and organising content around user intent (new app, existing app, evaluating, etc.) rather than a flat category index.
All internal links in the new README were verified against the repository — every target file exists.
The #whats-next anchor in tutorial.md correctly resolves to the ## What's Next? heading at line 255 of the same file.
The Documentation website link is preserved at the bottom of the new README, consistent with the PR goal of keeping the upstream docs self-contained while still pointing readers to the rendered site.

Confidence Score: 5/5

Safe to merge — documentation-only changes with all internal links verified.
Both changes are documentation-only. Every internal link in the new docs/README.md resolves to a file that exists in the repository, and the corrected #whats-next anchor in tutorial.md matches the actual heading. No code, configuration, or runtime behaviour is affected.
No files require special attention.

Important Files Changed

Filename	Overview
docs/README.md	Replaces the verbose GitHub-navigation-focused README with a concise user-journey-oriented landing page; all internal file links verified to exist on disk.
docs/oss/getting-started/tutorial.md	Single TOC anchor fix: `#conclusion` → `#whats-next`, correctly matching the existing `## What's Next?` heading at line 255.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Reader lands on docs/README.md] --> B{What describes you?}
    B --> C[Starting a new app]
    B --> D[Adding React to existing app]
    B --> E[Already using OSS, evaluating Pro]
    B --> F[Evaluating Rails + React options]

    C --> C1[create-react-on-rails-app.md]
    C --> C2[quick-start.md]

    D --> D1[installation-into-an-existing-rails-app.md]
    D --> D2[using-react-on-rails.md]

    E --> E1[oss-vs-pro.md]
    E --> E2[upgrading-to-pro.md]

    F --> F1[reactonrails.com/examples]
    F --> F2[comparison-with-alternatives.md]
    F --> F3[migrating-from-react-rails.md]

    A --> G[Dive deeper]
    G --> G1[introduction.md]
    G --> G2[how-react-on-rails-works.md]
    G --> G3[view-helpers-api.md]
    G --> G4[deployment/README.md]

    A --> H[Need more help?]
    H --> H1[GitHub Discussions]
    H --> H2[reactonrails.com/docs/]

_{Last reviewed commit: "Move docs home copy ..."}

claude · 2026-03-18T05:19:18Z

Review

All internal links verified — every relative path in the new docs/README.md resolves to an existing file, and the #whats-next anchor fix in tutorial.md is correct (maps to the ## What's Next? heading on line 255).

One usability concern: The previous README included a direct link to the Changelog (./oss/upgrading/changelog.md), which is a common first stop for users after upgrading. The new structure drops it entirely — it isn't reachable from any of the listed paths. Consider adding it to the "Dive deeper" section.

Minor: https://reactonrails.com/examples is the only hardcoded external URL in the new file. If the site reorganizes that path, this becomes a silent broken link with no in-repo way to catch it. Worth noting for future site maintenance.

Otherwise this is a clean, low-risk docs cleanup. The user-journey structure is clearer than the previous categorical index.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

coderabbitai

🧹 Nitpick comments (1)

docs/README.md (1)
20-21: Consider consolidating duplicated “Upgrade to Pro” links.

Line 20 and Line 41 both point to the same page. Keeping one primary CTA can reduce repetition in the landing flow.

Also applies to: 41-42
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/README.md` around lines 20 - 21, Remove the duplicated "[Upgrade to
Pro]" link pointing to "./pro/upgrading-to-pro.md" so only one primary CTA
remains; locate both occurrences of the link text "[Upgrade to Pro]" and the
target "./pro/upgrading-to-pro.md" in README.md, keep the more
context-appropriate instance (e.g., the primary landing CTA) and delete the
other, ensuring surrounding copy still reads naturally and any list/spacing is
adjusted accordingly.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@docs/README.md`:
- Around line 20-21: Remove the duplicated "[Upgrade to Pro]" link pointing to
"./pro/upgrading-to-pro.md" so only one primary CTA remains; locate both
occurrences of the link text "[Upgrade to Pro]" and the target
"./pro/upgrading-to-pro.md" in README.md, keep the more context-appropriate
instance (e.g., the primary landing CTA) and delete the other, ensuring
surrounding copy still reads naturally and any list/spacing is adjusted
accordingly.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4e82e695-eddf-40e8-9474-b398cc2de451

📥 Commits

Reviewing files that changed from the base of the PR and between 38740d5 and cca476a.

📒 Files selected for processing (2)

docs/README.md
docs/oss/getting-started/tutorial.md

✅ Files skipped from review due to trivial changes (1)

docs/oss/getting-started/tutorial.md

claude · 2026-03-21T08:54:44Z

Review: Move docs home copy upstream and fix tutorial anchor

Overall this is a clean, low-risk docs restructuring. The tutorial anchor fix (#conclusion → #whats-next) is correct — verified that the ## What's Next? section exists at line 255 of tutorial.md and the generated anchor matches. All internal links in the new README resolve to existing files.

Strengths

Path-oriented structure (new app / existing app / evaluating) is more user-friendly than the old category-based layout.
Pro features section correctly groups only Pro content (verified node-renderer and streaming SSR are both marked as Pro features in their respective docs).

Issues found (inline comments posted)

Missing Tutorial link — The tutorial (docs/oss/getting-started/tutorial.md) was a prominent resource in the old README and is now unreachable from the landing page.
Configuration docs no longer discoverable — ./oss/configuration/README.md was removed with no replacement link. Users who need to configure React on Rails have no path to find it from the docs home.
"Contact us" in evaluation policy has no contact target — Says "contact us" but provides no email or link. The original README had justin@shakacode.com for this purpose.

None are blocking — all are minor content gaps rather than errors.

Address review feedback: restore the tutorial link in the getting-started section, add configuration docs to the dive-deeper section, and make "contact us" actionable with a mailto link. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

justin808 · 2026-03-21T08:59:00Z

Thanks for the walkthrough and summary. No action needed — this was an automated overview.

justin808 · 2026-03-21T08:59:02Z

Thanks for the review. The confidence assessment and link verification were helpful. No action items here — the concerns raised were addressed via the inline review comments.

justin808 · 2026-03-21T08:59:05Z

Both concerns from this review have been addressed:

Changelog link: Was already added in the previous commit (cca476a).
External URL note (reactonrails.com/examples): Acknowledged — this is an intentional link to the live site. If the site path changes, it will be caught during docs site maintenance.

justin808 · 2026-03-21T08:59:07Z

All three issues from this review have been addressed in 2cc798e:

Tutorial link — added to the "Starting a new app" section.
Configuration docs — added to the "Dive deeper" section.
"Contact us" link — now includes a mailto link to justin@shakacode.com.

claude · 2026-03-21T09:01:35Z

Review

Good clean-up. The restructuring is clear and purposeful, and the anchor fix in the tutorial TOC is correct (whats-next matches the existing What's Next heading at line 255).

One broken link found:

docs/README.md line 36 links to ./oss/upgrading/changelog.md, but that file does not exist. The only file in docs/oss/upgrading/ is upgrading-react-on-rails.md. I left an inline suggestion on that line.

Minor observations (no action required):

The old README had a prominent callout pointing GitHub readers to the docs website. That is now demoted to the last bullet in 'Need more help?'. For users landing directly on this file via GitHub, a short note near the top would help them find the rendered site.
The 'Pro features' section includes Node Renderer which is also available in OSS. The heading may be slightly misleading -- 'Pro and advanced features' might be clearer.

Otherwise LGTM -- documentation-only change with no runtime impact.

## Summary - Stamp `### [16.5.0.rc.0]` version header with today's date - Add 10 new changelog entries for PRs merged since v16.4.0 - Fix incomplete PR 2818 entry (missing author link) ### New entries added **Added:** - `create-react-on-rails-app --pro` support (PR 2818) - Global prerender env override `REACT_ON_RAILS_PRERENDER_OVERRIDE` (PR 2816) - `react_on_rails:sync_versions` rake task (PR 2797) - Pro/RSC setup checks in `react_on_rails:doctor` (PR 2674) **Changed:** - [Pro] Canonical env var for worker count is now `RENDERER_WORKERS_COUNT` (PR 2611) **Improved:** - Smoother `create-react-on-rails-app` and install generator flows (PR 2650) - Pro upgrade hint after install (PR 2642) **Fixed:** - Preserve runtime env vars across `Bundler.with_unbundled_env` (PR 2836) - Fix doctor prerender check and ExecJS display for Pro/RSC apps (PR 2773) - Fix doctor false positives for custom layouts (PR 2612) ### Skipped PRs (not user-visible) Docs-only: #2845, #2842, #2826, #2830, #2820, #2809, #2803, #2785, #2801, #2791, #2789, #2788, #2772, #2778, #2780, #2784, #2671, #2676, #2662, #2657, #2669 CI/internal tooling: #2825, #2817, #2819, #2812, #2815, #2810, #2808, #2807, #2634, #2798, #2761, #2760, #2658, #2639, #2667, #2656 ## Test plan - [x] Verified version header and diff links are correct - [x] Verified all entries follow changelog formatting conventions - [x] Verified file ends with newline - [ ] After merge, run `rake release` to publish 16.5.0.rc.0 🤖 Generated with [Claude Code](https://claude.com/claude-code)  --- > [!NOTE] > **Low Risk** > Documentation-only change updating `CHANGELOG.md` with a new `16.5.0.rc.0` section and compare links; no runtime code is modified. > > **Overview** > Adds a new `16.5.0.rc.0` (2026-03-25) section to `CHANGELOG.md`, consolidating recent PR entries under **Added/Changed/Improved/Fixed** and correcting the previously incomplete `--pro` CLI entry author attribution. > > Updates the bottom compare links so `[unreleased]` now compares from `v16.5.0.rc.0` and adds a link definition for `[16.5.0.rc.0]`. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 481a71c. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup>   ## Summary by CodeRabbit ## Release Notes - v16.5.0.rc.0 * **New Features** * Added sync_versions task for streamlined version management * Expanded doctor checks for Pro and RSC support * **Improvements** * Enhanced generator workflow and Pro upgrade guidance * Improved environment variable handling and preservation * **Bug Fixes** * Fixed detection issues with doctor tools and ExecJS/prerender functionality  Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Moves the canonical docs-home copy into `docs/README.md` so `reactonrails.com` no longer has to own that prose in `prepare-docs.mjs`. Also fixes the tutorial table-of-contents anchor so it points to the existing `What's Next?` section instead of the stale `#conclusion` anchor. - Replaces the generic docs README with the canonical docs landing content used by the site - Keeps the GitHub-friendly docs website link in the upstream README - Fixes `docs/oss/getting-started/tutorial.md` TOC link from `#conclusion` to `#whats-next` This is the remaining upstream/site-boundary cleanup from the docs work. The site repo should present docs, not own canonical docs content. - `reactonrails.com`: `npm run prepare` - `reactonrails.com`: `npm run build`  --- > [!NOTE] > **Low Risk** > Low risk: documentation-only restructuring and link/anchor fixes with no runtime code changes. > > **Overview** > Updates `docs/README.md` from a GitHub navigation stub to a more opinionated docs landing page that explains OSS vs Pro, reorganizes entry points by user intent, and adds Pro evaluation/help links. > > Fixes the tutorial table-of-contents to link to the existing **“What’s Next?”** section (`#whats-next`) instead of a stale conclusion anchor. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 2cc798e. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup>   * **Documentation** * Renamed top-level docs to "Documentation Guide" and reframed intro to present OSS vs Pro paths with selection criteria. * Reorganized navigation into path-oriented sections (new app, add-to-app, OSS→Pro evaluation) and consolidated deeper links. * Reduced main Pro feature listings, updated help links, and added a friendly evaluation policy. * Tutorial TOC anchor changed: "Conclusion" → "What's Next?"  --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

This was referenced Mar 18, 2026

Deferred follow-ups from review triage for PRs #17, #18, and #19 shakacode/reactonrails.com#24

Closed

Increase navbar logo size and brand presence shakacode/reactonrails.com#22

Merged

justin808 force-pushed the jg-codex/docs-home-readme-upstream branch from 9369023 to 38740d5 Compare March 18, 2026 05:17

coderabbitai Bot approved these changes Mar 18, 2026

View reviewed changes

claude Bot reviewed Mar 18, 2026

View reviewed changes

Comment thread docs/README.md

justin808 and others added 2 commits March 18, 2026 17:06

Move docs home copy upstream and fix tutorial anchor

1fa0b7d

Add Pro features section and changelog link to docs landing page

cca476a

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

justin808 force-pushed the jg-codex/docs-home-readme-upstream branch from 38740d5 to cca476a Compare March 21, 2026 08:52

claude Bot reviewed Mar 21, 2026

View reviewed changes

Comment thread docs/README.md

claude Bot reviewed Mar 21, 2026

View reviewed changes

Comment thread docs/README.md Outdated

claude Bot reviewed Mar 21, 2026

View reviewed changes

Comment thread docs/README.md

coderabbitai Bot reviewed Mar 21, 2026

View reviewed changes

claude Bot reviewed Mar 21, 2026

View reviewed changes

Comment thread docs/README.md

justin808 merged commit 3281515 into main Mar 21, 2026
20 checks passed

justin808 deleted the jg-codex/docs-home-readme-upstream branch March 21, 2026 20:27

justin808 mentioned this pull request Mar 25, 2026

Update CHANGELOG.md for 16.5.0.rc.0 #2847

Merged

4 tasks

justin808 mentioned this pull request Apr 4, 2026

Move docs home copy upstream and fix tutorial anchor #3001

Closed

Uh oh!

Conversation

justin808 commented Mar 18, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Why

Validation

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

greptile-apps Bot commented Mar 18, 2026

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Flowchart

Uh oh!

claude Bot commented Mar 18, 2026

Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

claude Bot commented Mar 21, 2026

Review: Move docs home copy upstream and fix tutorial anchor

Strengths

Issues found (inline comments posted)

Uh oh!

justin808 commented Mar 21, 2026

Uh oh!

justin808 commented Mar 21, 2026

Uh oh!

justin808 commented Mar 21, 2026

Uh oh!

justin808 commented Mar 21, 2026

Uh oh!

Uh oh!

claude Bot commented Mar 21, 2026

Review

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

justin808 commented Mar 18, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Mar 18, 2026 •

edited

Loading