docs: Entry Point Consolidation and Tutorial Improvements #1860
Conversation
WalkthroughConsolidates and reorganizes documentation: adds Changes
Sequence Diagram(s)Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related issues
Possibly related PRs
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
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 |
ihabadham
changed the title
PR Review: Phase 3 - Entry Point Consolidation and Tutorial ImprovementsOverall Assessment✅ Strong approval - This is excellent documentation work that significantly improves the user experience. The consolidation of entry points and modernization of the tutorial are well-executed. Strengths1. Clear Entry Point Strategy ✅
2. Improved Tutorial Structure ✅
3. Better Content Organization ✅
4. Documentation Quality ✅
Code Quality & Best PracticesExcellent ✅
Specific Review Points1. Was deleting
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
docs/getting-started/tutorial.md (1)
125-128: Tag the environment variables code fence.Markdownlint MD040 flags this block. Add a language (e.g.,
bash) to satisfy linting.-``` +```bash EXECJS_RUNTIME=Nodedocs/planning/docs-improvement/ia-redesign-live.md (1)
402-478: Add a language tag to the folder-structure fence.Markdownlint complains about this fence lacking a language. Tag it as
text(or similar) to keep lint happy.-``` +```text docs/ ├── introduction.md # ✅ Created - new unified homepage ├── README.md # ✅ Simplified for GitHub users @@ └── advanced-topics/ (1 file - KEEPING as category) └── rails-engine-integration.md # Step 5 correction: from deployment
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (15)
docs/README.md(3 hunks)docs/advanced-topics/manual-installation-overview.md(0 hunks)docs/core-concepts/react-on-rails-overview.md(0 hunks)docs/deployment/heroku-deployment.md(2 hunks)docs/getting-started.md(0 hunks)docs/getting-started/installation-into-an-existing-rails-app.md(0 hunks)docs/getting-started/quick-start.md(1 hunks)docs/getting-started/tutorial.md(8 hunks)docs/getting-started/using-react-on-rails.md(1 hunks)docs/guides/advanced/README.md(0 hunks)docs/home.md(0 hunks)docs/introduction.md(1 hunks)docs/misc/doctrine.md(1 hunks)docs/planning/docs-improvement/04-ia-redesign-plan.md(1 hunks)docs/planning/docs-improvement/ia-redesign-live.md(2 hunks)
💤 Files with no reviewable changes (6)
- docs/guides/advanced/README.md
- docs/advanced-topics/manual-installation-overview.md
- docs/getting-started.md
- docs/home.md
- docs/core-concepts/react-on-rails-overview.md
- docs/getting-started/installation-into-an-existing-rails-app.md
🧰 Additional context used
📓 Path-based instructions (1)
**/*.{js,jsx,ts,tsx,css,scss,json,yml,yaml,md}
📄 CodeRabbit inference engine (CLAUDE.md)
Prettier is the sole authority for formatting all non-Ruby files; never manually format them
Files:
docs/getting-started/quick-start.mddocs/misc/doctrine.mddocs/getting-started/using-react-on-rails.mddocs/introduction.mddocs/README.mddocs/deployment/heroku-deployment.mddocs/getting-started/tutorial.mddocs/planning/docs-improvement/04-ia-redesign-plan.mddocs/planning/docs-improvement/ia-redesign-live.md
🪛 markdownlint-cli2 (0.18.1)
docs/getting-started/using-react-on-rails.md
150-150: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/deployment/heroku-deployment.md
100-100: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/getting-started/tutorial.md
150-150: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/planning/docs-improvement/ia-redesign-live.md
402-402: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (10)
- GitHub Check: dummy-app-integration-tests (3.4, 22)
- GitHub Check: dummy-app-integration-tests (3.2, 20)
- GitHub Check: rspec-package-tests (3.2, minimum)
- GitHub Check: rspec-package-tests (3.4, minimum)
- GitHub Check: rspec-package-tests (3.2, latest)
- GitHub Check: rspec-package-tests (3.4, latest)
- GitHub Check: claude-review
- GitHub Check: markdown-link-check
- GitHub Check: build
- GitHub Check: build-and-test
| ``` | ||
| web: bundle exec puma -C config/puma.rb | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Specify the Procfile language for markdownlint.
MD040 fires here; add a language hint (Procfile) so CI linting passes.
-```
+```Procfile
web: bundle exec puma -C config/puma.rb🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
100-100: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In docs/deployment/heroku-deployment.md around lines 100 to 103, the fenced code
block for the Procfile lacks a language hint causing MD040; update the markdown
block to include the Procfile language identifier (i.e., replace the
triple-backtick fence with ```Procfile) so the code block is fenced as Procfile
and CI markdownlint passes.
| "engines": { | ||
| "node": "16.19.0", | ||
| "yarn": "1.22.4" | ||
| }, | ||
| ``` |
There was a problem hiding this comment.
Update the Heroku engines to match our supported runtime.
We now require Node 18+ (see Introduction/Quick Start), but this guide still pins Node 16.19.0, which is end-of-life. Following these steps will deploy on an unsupported runtime. Please bump the engines block to Node 18 (and adjust Yarn if needed) to stay consistent.
🤖 Prompt for AI Agents
In docs/deployment/heroku-deployment.md around lines 131 to 135, the engines
block pins Node to 16.19.0 which is EOL and mismatches our required Node 18+;
update the "engines" block to specify a supported Node 18+ version (e.g.,
">=18.0.0" or a specific 18.x release) and adjust the yarn entry if necessary
(either remove Yarn if irrelevant to current install flow or set a compatible
Yarn version), then run a quick lint/spell check to ensure the markdown still
renders correctly.
| ``` | ||
| app/javascript/ | ||
| └── bundles/HelloWorld/ # or src/HelloWorld/ror_components/ with auto-bundling | ||
| └── HelloWorld.jsx | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Add language hint to the directory tree code fence.
Markdown lint (MD040) flags this fence because no language is specified. Tag it (e.g., text) to keep the CI green.
-```
+```text
app/javascript/
└── bundles/HelloWorld/ # or src/HelloWorld/ror_components/ with auto-bundling
└── HelloWorld.jsx🤖 Prompt for AI Agents
In docs/getting-started/using-react-on-rails.md around lines 118 to 123 the
fenced code block showing the directory tree lacks a language hint which
triggers MD040; update the opening fence from ``` to a fenced block with a
language tag (for example ```text) so the code fence includes a language hint
and the CI linter passes.
Pull Request Review: Entry Point Consolidation and Tutorial ImprovementsOverall Assessment ✅This is an excellent documentation improvement that successfully addresses the problem of multiple conflicting entry points. The changes are well-thought-out and significantly improve the user experience. I recommend approval with minor suggestions below. Strengths 🎯1. Clear Information Architecture
2. Content Quality
3. Documentation Hygiene
Suggestions for Improvement 💡Minor Issues1. Heroku Deployment Content (Low Priority)The merged Heroku deployment guide contains some older patterns: Lines 52-75 ( default: &default
adapter: postgresql
username:
password:
host: localhostSuggestion: Modern Rails 7+ uses Lines 86-98 (
Severity: Low - The disclaimer at the top addresses this adequately. 2. Tutorial Version ReferencesLine 113 ( **Note on Redux:** The basic installer uses React Hooks for state management...Observation: This is clear and helpful! The clarification about Redux vs Hooks is excellent. ✅ Lines 60-61 mention checking Rails 7.0+, which is good and matches the stated requirements. 3. Introduction.md Minor PolishLine 199 ( {
renderedHtml: {
componentHtml, redirectLocation, error; // ← Semicolons should be commas
}
}Issue: JavaScript object syntax error - should use commas, not semicolons between properties. Fix: {
renderedHtml: {
componentHtml,
redirectLocation,
error
}
}Severity: Medium - This is example code that won't run as written. 4. README.md SimplificationThe simplified Minor suggestion: Consider whether lines 44-50 (the "I want to..." table) duplicates content from Validation Checklist ✅Based on CLAUDE.md requirements:
Performance Considerations ⚡Not applicable - documentation changes only. No runtime performance impact. Security Concerns 🔒None identified. Documentation changes pose no security risks. Test Coverage 🧪Not applicable for documentation. However, consider:
Recommended Next Steps 🚀As noted in the PR description:
Final Recommendation✅ APPROVE with one minor fix required: Required: Fix JavaScript syntax error in Optional: Consider updating Heroku database.yml example to modern pattern (or keep with disclaimer) This PR significantly improves documentation usability and follows the Rails doctrine of "convention over configuration" by establishing clear, opinionated entry points. Excellent work! 🎉 Review Philosophy NoteFollowing the project's doctrine of professional objectivity: While this is overwhelmingly positive feedback, I've highlighted the genuine issues found (JavaScript syntax error) and areas where current best practices have evolved (Heroku config). The consolidation strategy is sound and well-executed. |
Code Review: Entry Point Consolidation and Tutorial ImprovementsI've reviewed PR #1860, which addresses Phase 3 of the IA redesign by consolidating entry points and improving the tutorial. Overall, this is excellent work that significantly improves documentation clarity and user experience. ✅ Strengths1. Entry Point Consolidation (Problem 1.2 - Solved!)Excellent execution. The new structure creates a clear, single source of truth:
2. Tutorial Improvements
3. Heroku Deployment Guide
|
| Category | Rating |
|---|---|
| Code Quality | ⭐⭐⭐⭐⭐ |
| Documentation | ⭐⭐⭐⭐⭐ |
| Best Practices | ⭐⭐⭐⭐⭐ |
| Security | ✅ |
🚀 Recommendation: APPROVE with minor suggestions
This PR successfully achieves its goals. The minor suggestions above are optional improvements.
Before merging:
- Verify all new files are committed (especially using-react-on-rails.md)
- Run rake autofix for Prettier formatting
- Consider addressing Puma duplication
Great work! 🎉
- Add docs/introduction.md as unified homepage - Explains what React on Rails is and why to use it - Clear when to use / when not to use decision guide - Three clear paths: Quick Start, Installation, Tutorial - Built from actual docs (overview, doctrine, system requirements) - Added community stat (thousands of production sites) - Delete docs/core-concepts/react-on-rails-overview.md - Content consolidated into introduction.md - Outdated prerequisites (Rails >=5 vs current Rails 7+) - Creates confusion with two similar entry points - Update links to overview.md: - docs/home.md: Overview → Introduction - docs/misc/doctrine.md: Overview → Introduction Solves Problem 1.2 (Multiple Conflicting Entry Points) from docs improvement plan. Next: Handle remaining entry point files (home.md, README.md, getting-started.md).
- Simplify docs/README.md for GitHub users: - Direct users to website first - Keep valuable learning paths from PR #1813 - Keep popular use cases table - Add documentation categories overview - Remove duplicate content (now in introduction.md) - Reduced from 173 lines to 65 lines - Enhance introduction.md: - Add missing react_on_rails_demo_ssr_hmr example repo - Now has all 3 example repos (spec/dummy, demo SSR/HMR, live reactrails.com) Purpose: docs/README.md serves GitHub users browsing repo structure, while introduction.md serves as website homepage. Different audiences, minimal duplication.
Document completion of entry point consolidation work: - Created introduction.md - Deleted overview.md - Simplified docs/README.md - Updated folder structure to reflect changes Next: Delete home.md, handle getting-started.md
- Was the current website homepage (29 lines of links) - All valuable content already in introduction.md or README.md - No unique content lost (example repos, use cases, help links all covered) - Replaced by introduction.md as new website homepage Updated ia-redesign-live.md to reflect completion. Next: Extract content from getting-started.md then delete it.
Transform docs/getting-started.md (253 lines) into a focused conceptual guide: docs/getting-started/understanding-react-on-rails.md (238 lines). Changes: - Removed redundant sections (Choose Starting Point, System Requirements, More Reading) - Transformed installation section into brief conceptual overview with links - Kept and refined: Basic Usage, Auto-Bundling, Render-Functions, Error Handling - Added clear 'Next Steps' section with organized learning paths - Updated link in quick-start.md to point to new file - Deleted original docs/getting-started.md Purpose: This is now a conceptual journey guide explaining how React on Rails works, complementing the hands-on tutorial and quick-start guides. Addresses user feedback that tutorial was too overwhelming and mixed audiences. Next: Website config updates (keeping for last as requested)
Rationale: - "understanding" is vague and confusing next to how-react-on-rails-works.md - "using" clearly indicates practical usage guide - Better distinction: how-react-on-rails-works.md (architecture) vs using-react-on-rails.md (practical usage) Changes: - Renamed docs/getting-started/understanding-react-on-rails.md → using-react-on-rails.md - Updated link in quick-start.md - Updated references in ia-redesign-live.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
… structure Changes to tutorial.md: 1. Replaced Heroku deployment section (139 lines) with brief Deployment section linking to deployment guides 2. Updated versions: Ruby 2.7 → 3.0+, Rails 5.1.3 → 7.0+, RoR v13 → v16 3. Clarified Redux usage: tutorial demonstrates Redux, but basic installer uses Hooks (user choice) 4. Merged duplicate HMR sections into one cohesive section using ./bin/dev 5. Renamed "Other features" → "Going Further" with better organization: - Server Rendering (important) - Optional Configuration subsection (/client structure, Cloud9, RubyMine) Changes to heroku-deployment.md: 1. Merged tutorial's detailed Heroku instructions with existing guide 2. Added note about older versions with link to current Heroku Rails 7 guide 3. Organized into clear sections: Create App, Buildpacks, Postgres, Puma, Node/Yarn, Assets, Deploy Rationale: - Tutorial was overwhelming with platform-specific deployment before core features - Heroku content now in dedicated guide (reusable, maintainable) - Clear separation: tutorial teaches React on Rails, deployment guides teach platforms - Better progression: install → run → features → deploy → advanced 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Rationale: - File has been outdated since 2018 (had "TODO: Review this file" for 7 years) - Confused purpose: title says "Manual Installation" but subtitle says "summarizes what generator does" - Outdated content: references /client directory, webpacker, missing auto-bundling - No clear use case: rails generate react_on_rails:install IS the manual installation (not external CLI like create-react-app) - Content is better covered in: - how-react-on-rails-works.md (architecture) - using-react-on-rails.md (usage) - Generator source code (what files are created) Changes: - Deleted docs/advanced-topics/manual-installation-overview.md - Removed link in installation-into-an-existing-rails-app.md - Updated ia-redesign-live.md tracker Decision discussed with team in Slack. Can be reverted if use case is identified. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Mark Phase 3 as completed with notes on what actually happened vs what was planned: - ✅ Created introduction.md (as planned) - ✅ Transformed getting-started.md → using-react-on-rails.md (adapted from original plan) - ✅ Simplified README.md (kept, not deleted) - ✅ Deleted home.md (as planned) - ✅ Added tutorial improvements (discovered during work) - ✅ Deleted manual-installation-overview.md (discovered during work) - ✅ Updated cross-references manually (not scripted) Updated testing checklist to show what's complete and what's deferred to Phase 1.
Escape <head> tag in prose to prevent MDX from expecting closing tag. Changed "in the <head>:" to "in the `<head>` section:" to use inline code. This fixes gatsby-plugin-mdx compilation error: "Expected a closing tag for <head> before the end of paragraph"
ihabadham
force-pushed
the
feature/docs-ia-redesign-1845-continue
branch
from
5388efb to
5e71aeb
Compare
PR Review: Entry Point Consolidation and Tutorial ImprovementsThis is excellent work that significantly improves documentation structure! Here is my detailed review: Strengths1. Excellent Entry Point Consolidation
2. Strong Conceptual Guide
3. Tutorial Improvements
4. README Simplification
Issues Found1. Syntax Error in using-react-on-rails.md line 192 2. Formatting Check Required
3. Link Validation Needed Deleted Files AssessmentAll deletions are appropriate:
Recommendations Before Merge
Overall AssessmentQuality: 5/5 Final Verdict: Approve with Minor Changes Once the syntax error is fixed and formatting tools are run, this is ready to merge. Great job on the thoughtful consolidation and improved information architecture! Reviewed by: Claude Code |
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
docs/getting-started/tutorial.md (2)
125-127: Add a language to the fenced block (MD040).Tag this as shell/env so markdownlint passes.
-``` +```bash EXECJS_RUNTIME=Node
185-186: Fix path typo: “initializers.”Correct “config/intializers/react_on_rails.rb” to “config/initializers/react_on_rails.rb”.
-`config/intializers/react_on_rails.rb` +`config/initializers/react_on_rails.rb`
♻️ Duplicate comments (3)
docs/deployment/heroku-deployment.md (2)
100-103: Tag the Procfile code fence with a language.Add a language hint so markdownlint (MD040) passes.
-``` +```Procfile web: bundle exec puma -C config/puma.rb
131-135: Update Node/Yarn engines to supported versions (Node 18+).This still pins Node 16.19.0, which is EOL and inconsistent with prerequisites. Bump to Node 18+ (and adjust Yarn) for alignment.
- "engines": { - "node": "16.19.0", - "yarn": "1.22.4" - }, + "engines": { + "node": ">=18 <21", + "yarn": ">=1.22" + },docs/getting-started/using-react-on-rails.md (1)
126-130: Add a language to the directory tree fence (MD040).Tag this block (e.g.,
text) so markdownlint passes.-``` +```text app/javascript/ └── bundles/HelloWorld/ # or src/HelloWorld/ror_components/ with auto-bundling └── HelloWorld.jsx
🧹 Nitpick comments (7)
docs/planning/docs-improvement/ia-redesign-live.md (2)
28-38: Clarify status consistency (Step 0 vs. Completion Summary).Step 0 shows "In Progress" with unchecked items, while the Completion Summary says all steps are complete. Update Step 0 checkboxes/status to reflect completion or annotate as historical to avoid confusion.
Also applies to: 304-314
115-121: Align Step 8 task with actual changes (README.md not deleted).Step 8 lists “Delete/archive README.md,” but this PR simplified
docs/README.md. Revise the Step 8 bullet to “SimplifyREADME.mdfor GitHub users” to match what shipped.Also applies to: 359-368
docs/deployment/heroku-deployment.md (3)
168-170: Use correct language for Ruby config snippet.This is Ruby code, not bash. Tag the fence as Ruby.
-```bash +```ruby config.build_production_command = "RAILS_ENV=production NODE_ENV=production bin/shakapacker"
177-179: Use Ruby fence for Rake task clear example.This is Ruby that's added to a Rakefile/initializer, not a shell command.
-```bash +```ruby Rake::Task['shakapacker:clean'].clear
79-82: Prefer modern Rails tasks over rake aliases.Use
rails db:setupandrails db:migrateto match current Rails conventions.- rake db:setup - rake db:migrate + rails db:setup + rails db:migratedocs/getting-started/tutorial.md (1)
145-153: Clarify HMR vs full page reload; update links.The text implies HMR but describes full page refresh (live reload). Clarify that without React Refresh you get full reloads; for state‑preserving updates enable React Fast Refresh. Also replace the deprecated Webpacker link with current Webpack docs (and/or Shakapacker docs).
docs/getting-started/quick-start.md (1)
127-133: Verify helper names/necessity with auto-bundling (Shakapacker v7).Confirm
stylesheet_pack_tag/javascript_pack_tagare the intended helpers and still required when usingauto_load_bundle: true. If not, update to current helpers or note when they’re needed.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (15)
docs/README.md(3 hunks)docs/advanced-topics/manual-installation-overview.md(0 hunks)docs/core-concepts/react-on-rails-overview.md(0 hunks)docs/deployment/heroku-deployment.md(2 hunks)docs/getting-started.md(0 hunks)docs/getting-started/installation-into-an-existing-rails-app.md(0 hunks)docs/getting-started/quick-start.md(2 hunks)docs/getting-started/tutorial.md(8 hunks)docs/getting-started/using-react-on-rails.md(1 hunks)docs/guides/advanced/README.md(0 hunks)docs/home.md(0 hunks)docs/introduction.md(1 hunks)docs/misc/doctrine.md(1 hunks)docs/planning/docs-improvement/04-ia-redesign-plan.md(1 hunks)docs/planning/docs-improvement/ia-redesign-live.md(2 hunks)
💤 Files with no reviewable changes (6)
- docs/guides/advanced/README.md
- docs/core-concepts/react-on-rails-overview.md
- docs/getting-started.md
- docs/advanced-topics/manual-installation-overview.md
- docs/home.md
- docs/getting-started/installation-into-an-existing-rails-app.md
🚧 Files skipped from review as they are similar to previous changes (3)
- docs/introduction.md
- docs/misc/doctrine.md
- docs/planning/docs-improvement/04-ia-redesign-plan.md
🧰 Additional context used
📓 Path-based instructions (1)
**/*.{js,jsx,ts,tsx,css,scss,json,yml,yaml,md}
📄 CodeRabbit inference engine (CLAUDE.md)
Prettier is the sole authority for formatting all non-Ruby files; never manually format them
Files:
docs/getting-started/quick-start.mddocs/getting-started/using-react-on-rails.mddocs/planning/docs-improvement/ia-redesign-live.mddocs/README.mddocs/getting-started/tutorial.mddocs/deployment/heroku-deployment.md
🪛 markdownlint-cli2 (0.18.1)
docs/deployment/heroku-deployment.md
150-150: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (10)
- GitHub Check: dummy-app-integration-tests (3.4, 22)
- GitHub Check: dummy-app-integration-tests (3.2, 20)
- GitHub Check: claude-review
- GitHub Check: build
- GitHub Check: rspec-package-tests (3.4, latest)
- GitHub Check: rspec-package-tests (3.2, minimum)
- GitHub Check: markdown-link-check
- GitHub Check: rspec-package-tests (3.4, minimum)
- GitHub Check: rspec-package-tests (3.2, latest)
- GitHub Check: build-and-test
🔇 Additional comments (2)
docs/getting-started/quick-start.md (1)
162-165: Good redirect to the new concepts guide.Pointing to “Using React on Rails” aligns with the new IA.
docs/README.md (1)
3-6: Solid simplification and IA alignment.Concise GitHub-oriented README with clear learning paths and category index. Links align with the new structure.
Also applies to: 15-26, 45-55, 60-64
| ```js | ||
| { | ||
| renderedHtml: { | ||
| componentHtml, redirectLocation, error; | ||
| } | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Fix JS example syntax (remove stray semicolon).
The object example includes a semicolon inside an object literal. Remove it.
-{
- renderedHtml: {
- componentHtml, redirectLocation, error;
- }
-}
+{
+ renderedHtml: {
+ componentHtml,
+ redirectLocation,
+ error
+ }
+}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ```js | |
| { | |
| renderedHtml: { | |
| componentHtml, redirectLocation, error; | |
| } | |
| } | |
| ``` | |
| { | |
| renderedHtml: { | |
| componentHtml, | |
| redirectLocation, | |
| error | |
| } | |
| } |
🤖 Prompt for AI Agents
In docs/getting-started/using-react-on-rails.md around lines 189 to 195 the
JavaScript object example includes an invalid stray semicolon inside the object
literal; update the example to use valid object property syntax by removing the
semicolon so the properties are comma-separated or individually declared
correctly (e.g., use renderedHtml: { componentHtml, redirectLocation, error } or
explicit key: value pairs) to ensure the snippet is valid JS.
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (2)
docs/deployment/heroku-deployment.md (2)
100-102: Restore the Procfile fence language hint.This fenced block still lacks the
Procfilelanguage tag that markdownlint flagged earlier, so CI will fail the same MD040 check unless we add it back.-``` +```Procfile web: bundle exec puma -C config/puma.rb
131-134: Align Heroku engines with our supported runtime.We still pin Heroku to Node 16.19.0, which is EOL and contradicts the Node 18+ requirement documented elsewhere in this PR. Please bump Node (and Yarn if you want to keep it) to a supported release before merging.
"engines": { - "node": "16.19.0", - "yarn": "1.22.4" + "node": ">=18.18.0", + "yarn": "1.22.22" },
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (15)
docs/README.md(3 hunks)docs/advanced-topics/manual-installation-overview.md(0 hunks)docs/core-concepts/react-on-rails-overview.md(0 hunks)docs/deployment/heroku-deployment.md(2 hunks)docs/getting-started.md(0 hunks)docs/getting-started/installation-into-an-existing-rails-app.md(0 hunks)docs/getting-started/quick-start.md(2 hunks)docs/getting-started/tutorial.md(8 hunks)docs/getting-started/using-react-on-rails.md(1 hunks)docs/guides/advanced/README.md(0 hunks)docs/home.md(0 hunks)docs/introduction.md(1 hunks)docs/misc/doctrine.md(1 hunks)docs/planning/docs-improvement/04-ia-redesign-plan.md(1 hunks)docs/planning/docs-improvement/ia-redesign-live.md(2 hunks)
💤 Files with no reviewable changes (6)
- docs/home.md
- docs/core-concepts/react-on-rails-overview.md
- docs/getting-started/installation-into-an-existing-rails-app.md
- docs/guides/advanced/README.md
- docs/getting-started.md
- docs/advanced-topics/manual-installation-overview.md
✅ Files skipped from review due to trivial changes (1)
- docs/introduction.md
🚧 Files skipped from review as they are similar to previous changes (3)
- docs/misc/doctrine.md
- docs/getting-started/using-react-on-rails.md
- docs/getting-started/quick-start.md
🧰 Additional context used
📓 Path-based instructions (1)
**/*.{js,jsx,ts,tsx,css,scss,json,yml,yaml,md}
📄 CodeRabbit inference engine (CLAUDE.md)
Prettier is the sole authority for formatting all non-Ruby files; never manually format them
Files:
docs/README.mddocs/planning/docs-improvement/ia-redesign-live.mddocs/deployment/heroku-deployment.mddocs/getting-started/tutorial.mddocs/planning/docs-improvement/04-ia-redesign-plan.md
🪛 markdownlint-cli2 (0.18.1)
docs/getting-started/tutorial.md
7-7: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: build-and-test
| --- | ||
|
|
||
| _Updated for Ruby 2.7, Rails 7, React on Rails v13, and Shakapacker v7_ | ||
| _Updated for Ruby 3.0+, Rails 7, React on Rails v16, and Shakapacker v7_ |
There was a problem hiding this comment.
Fix the markdownlint MD036 violation.
Using italics as a heading trips markdownlint (MD036). Switching this line to a callout keeps the note while satisfying lint.
-_Updated for Ruby 3.0+, Rails 7, React on Rails v16, and Shakapacker v7_
+> **Note:** Updated for Ruby 3.0+, Rails 7, React on Rails v16, and Shakapacker v7.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| _Updated for Ruby 3.0+, Rails 7, React on Rails v16, and Shakapacker v7_ | |
| > **Note:** Updated for Ruby 3.0+, Rails 7, React on Rails v16, and Shakapacker v7. |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
7-7: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🤖 Prompt for AI Agents
In docs/getting-started/tutorial.md around line 7, the line currently uses
italics as a heading ("_Updated for Ruby 3.0+, Rails 7, React on Rails v16, and
Shakapacker v7_"), which triggers markdownlint MD036; replace the italicized
heading with a non-heading callout/note (for example start the line with "Note:"
or a blockquote ">" or a fenced admonition) so it remains a visible update
notice but is not parsed as a heading and thus satisfies MD036.
1 participant
What Changed
Phase 3 of the IA redesign: consolidated multiple conflicting entry points, improved the tutorial, and cleaned up outdated documentation.
1. Entry Point Consolidation
Created unified homepage:
docs/introduction.md- New comprehensive homepage with clear learning pathsRemoved/simplified conflicting entry points:
docs/home.md- old website homepage (replaced by introduction.md)docs/README.md(173→65 lines) - now serves GitHub users onlydocs/core-concepts/react-on-rails-overview.md- content consolidated into introduction.mdTransformed getting-started guide:
docs/getting-started.md→docs/getting-started/using-react-on-rails.mdCleanup:
docs/guides/advanced/README.md2. Tutorial Improvements
Enhanced
docs/getting-started/tutorial.md:Enhanced
docs/deployment/heroku-deployment.md:3. Documentation Cleanup
Deleted outdated manual installation guide:
docs/advanced-topics/manual-installation-overview.md4. Planning Documentation Updates
Updated tracker docs:
04-ia-redesign-plan.md- marked Phase 3 complete, noted actual vs planned changesia-redesign-live.md- comprehensive Phase 3 completion documentationFiles Changed (10 commits)
Created:
docs/introduction.md(new unified homepage)docs/getting-started/using-react-on-rails.md(transformed from getting-started.md)Modified:
docs/README.md(simplified for GitHub users)docs/getting-started/tutorial.md(extracted deployment, fixed versions, reorganized)docs/deployment/heroku-deployment.md(merged tutorial content)docs/planning/docs-improvement/04-ia-redesign-plan.md(updated status)docs/planning/docs-improvement/ia-redesign-live.md(documented Phase 3)Deleted:
docs/home.mddocs/core-concepts/react-on-rails-overview.mddocs/guides/advanced/README.mddocs/advanced-topics/manual-installation-overview.mdWhy
Problem 1.2: Multiple Conflicting Entry Points
Users faced 4+ different starting points with conflicting information:
README.md(GitHub)home.md(website homepage)getting-started.md(mixed purposes)react-on-rails-overview.md(outdated prereqs)Each had different content, creating confusion about where to start.
Tutorial overwhelm:
Outdated documentation:
What's Next
Website Configuration (sc-website repo)
gatsby-node.jsto useintroduction.mdas homepage/docs/planning/from website buildFuture phases:
(Future phases are repo cleanup tasks - website filtering will hide them from users)
Review Focus
introduction.mdprovide a clear, unified starting point?using-react-on-rails.mdmore focused as a conceptual guide?manual-installation-overview.mdthe right call?Note: Planning docs in
/docs/planning/docs-improvement/are for development only and will be filtered from the website in Phase 1.This change is
Summary by CodeRabbit