docs: Reorganize documentation into 10 user-journey-based categories #1845
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This commit establishes the baseline for the documentation Information Architecture redesign project. It includes: - Problem analysis identifying 6 major documentation issues - Detailed IA redesign plan with 6 implementation phases - GitHub issue draft for team review - Live implementation tracker for step-by-step progress These planning docs will serve as reference as we reorganize ~80 documentation files into a clearer 7-category structure based on user journey rather than implementation details. Related to documentation improvement initiative. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
After researching documentation patterns in popular frameworks, we've decided to split the original "Migration & Upgrading" category into two separate categories: 1. Upgrading (upgrading/) - Version upgrades, release notes 2. Migrating (migrating/) - From other tools (react-rails, angular, etc.) This provides clearer user intent as these represent different use cases. Final structure is 8 categories vs original 11. Changes: - Created upgrading/ folder - Renamed migration/ to migrating/ - Updated ia-redesign-live.md with Decision Log entry - Updated folder structure reference 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Moved 4 files to getting-started/ folder: - quick-start/README.md → getting-started/quick-start.md - guides/installation-into-an-existing-rails-app.md → getting-started/installation-into-an-existing-rails-app.md - guides/tutorial.md → getting-started/tutorial.md - additional-details/recommended-project-structure.md → getting-started/project-structure.md All files verified to match Getting Started category purpose. Git history preserved with git mv. Part of IA redesign Phase 2, Step 1. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Added Decision 2: Keep descriptive long filenames - Decided to keep installation-into-an-existing-rails-app.md (not shorten) - Rationale: meaningful distinction between new vs existing Rails apps - Pattern: prefer descriptive over short when distinction matters Added Issue 1: Content overlap in Getting Started - Identified redundancy between quick-start, installation, and tutorial - Flagged for Section 2 (Content Improvements) - not fixing during IA reorg - This is a content problem, not structure problem Updated folder structure reference with correct filenames. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Changes: - Updated category count from 7 to 8 (split Upgrading/Migrating) - Split category 6 "Migration & Upgrading" into: - Category 6: Upgrading (version upgrades, release notes) - Category 7: Migrating (from other tools) - Category 8: Pro (unchanged) - Updated Getting Started file mappings with actual filenames - Updated Upgrading/Migrating sections with correct file paths - Updated Pro section file paths Plan now reflects current implementation decisions. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Core Concepts (7 files): - guides/how-react-on-rails-works.md → core-concepts/how-it-works.md - guides/react-on-rails-overview.md → core-concepts/overview.md - guides/client-vs-server-rendering.md → core-concepts/client-vs-server-rendering.md - guides/react-server-rendering.md → core-concepts/server-rendering.md - guides/render-functions-and-railscontext.md → core-concepts/render-functions-and-railscontext.md - guides/auto-bundling-file-system-based-automated-bundle-generation.md → core-concepts/auto-bundling.md - guides/webpack-configuration.md → core-concepts/webpack-configuration.md API Reference (1 file): - guides/configuration.md → api-reference/configuration.md Decision: configuration.md is a reference list of all config options (like view-helpers-api.md), not a conceptual guide. Moved to API Reference. Part of IA redesign Phase 2, Step 2. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Added Decision 3 to live tracker: - configuration.md is a 391-line reference list (not conceptual) - Same format as view-helpers-api.md and javascript-api.md - Users look it up for specific settings (reference pattern) - Moved to API Reference instead of Core Concepts Updated plan: - Removed configuration.md from Core Concepts contents - Updated Core Concepts file mappings (7 files) - Updated API Reference to include configuration.md - Clarified configuration.md is full config options reference 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Reverted Step 2 filename changes: - how-it-works.md → how-react-on-rails-works.md - overview.md → react-on-rails-overview.md - server-rendering.md → react-server-rendering.md - auto-bundling.md → auto-bundling-file-system-based-automated-bundle-generation.md Rationale: - Filenames are content, not structure - Current phase is reorganization (moving files), not content changes - Renaming should be discussed separately as content improvement - Consistent with Decision 2: keep descriptive names 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Moved 14 files to building-features/: Common Patterns (4): - guides/hmr-and-hot-reloading-with-the-webpack-dev-server.md - guides/i18n.md - guides/rspec-configuration.md - guides/minitest-configuration.md Advanced Techniques (3): - guides/streaming-server-rendering.md - guides/how-to-conditionally-server-render-based-on-device-type.md - guides/how-to-use-different-files-for-client-and-server-rendering.md Integration Guides (4): - javascript/react-router.md - javascript/react-and-redux.md - javascript/react-helmet.md - guides/rails-webpacker-react-integration-options.md Tools & Workflow (3): - javascript/code-splitting.md - javascript/images.md - javascript/foreman-issues.md All filenames kept as original (no renaming). Part of IA redesign Phase 2, Step 3. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Moved 4 files to api-reference/: - api/view-helpers-api.md → api-reference/view-helpers-api.md - api/javascript-api.md → api-reference/javascript-api.md - api/redux-store-api.md → api-reference/redux-store-api.md - additional-details/generator-details.md → api-reference/generator-details.md Note: configuration.md already moved to api-reference in Step 2. Total in api-reference: 5 files (reference docs for view helpers, JS API, Redux, configuration options, and generator flags). Part of IA redesign Phase 2, Step 4. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Moved 9 files to deployment/: Production Setup (2): - guides/deployment.md - javascript/capistrano-deployment.md Troubleshooting (4): - troubleshooting/README.md (already in deployment/) - javascript/troubleshooting-build-errors.md - javascript/troubleshooting-when-using-shakapacker.md - javascript/troubleshooting-when-using-webpacker.md Maintenance (1): - additional-details/updating-dependencies.md Rails-Specific (3): - rails/turbolinks.md - rails/rails-engine-integration.md - rails/convert-rails-5-api-only-app.md All deployment, troubleshooting, and production-related docs now in one place. Part of IA redesign Phase 2, Step 5. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
After reviewing Step 5, found 5 files that don't belong in deployment/: Moved to better homes (keeping original filenames): - turbolinks.md → building-features/ (feature integration, not deployment) - updating-dependencies.md → misc/ (generic maintenance, temporary holding) - rails-engine-integration.md → advanced-topics/ (advanced setup, temporary holding) - convert-rails-5-api-only-app.md → migrating/ (prerequisite migration) - rails_view_rendering_from_inline_javascript.md → api-reference/ (API reference) Created temporary folders for review later: - misc/ (for orphaned generic files) - advanced-topics/ (for advanced setup scenarios) Deployment now focused on actual deployment (7 files): - Production setup (4 files) - Troubleshooting (3 files) See Decision 4 & 5 in ia-redesign-live.md for rationale.
Decision 4: Rethink Deployment Category - Analyzed files that ended up in deployment/ - Found 5 files that don't belong (not deployment-specific) - Moved to better categories keeping original filenames - Pattern: Categorize by WHEN and WHY users need info Decision 5: No "Rails" Category Needed - Considered creating Rails category for Rails-specific files - Decided against it - would become dumping ground - React on Rails IS Rails integration - everything is Rails-related - Pattern: Intent-based beats technology-based categorization All filenames kept original per Decision 2 (no renaming). Updated folder structure reference to reflect actual filenames.
Moved 4 files to upgrading/: - guides/upgrading-react-on-rails.md - react-on-rails-pro/major-performance-breakthroughs-upgrade-guide.md - release-notes/ folder (2 files: 15.0.0.md, 16.0.0.md) All files kept original names per Decision 2.
Moved 2 files to migrating/: - additional-details/migrating-from-react-rails.md - javascript/angular-js-integration-migration.md Combined with convert-rails-5-api-only-app.md from Step 5 corrections, migrating/ now has 3 files total. All files kept original names per Decision 2.
Moved 1 file to pro/: - react-on-rails-pro/react-on-rails-pro.md Note: major-performance-breakthroughs-upgrade-guide.md was already moved to upgrading/ in Step 6 (it's an upgrade guide, not Pro features doc). Kept old react-on-rails-pro/ folder for reference (will clean up later).
This file is a Pro features announcement (React Server Components, SSR Streaming, Early Hydration), not upgrade instructions. Better suited for pro/ folder as it showcases Pro v4 capabilities. upgrading/ now has 3 files: - upgrading-react-on-rails.md (upgrade HOW-TO) - release-notes/ folder (2 files) pro/ now has 2 files: - react-on-rails-pro.md (Pro overview) - major-performance-breakthroughs-upgrade-guide.md (Pro features)
Moved to existing categories (7 files): - manual-installation-overview.md → advanced-topics/ - render-functions.md → core-concepts/ - server-rendering-tips.md → deployment/ - credits.md → misc/ - asset-pipeline.md → misc/ (warning guide) - api/README.md → api-reference/README.md - troubleshooting/README.md → deployment/troubleshooting.md Moved to outdated/ (4 files): - tips-for-usage-with-sp6.md (Shakapacker 6 legacy) - upgrade-webpacker-v3-to-v4.md (explicitly outdated) - converting-from-custom-webpack-config-to-rails-webpacker-config.md (webpacker legacy) - webpack.md (outdated Webpack v2 content) Merged and deleted (1 file): - node-dependencies-and-npm.md merged into updating-dependencies.md (combined yarn upgrade, yarn add, and ncu workflows) All orphaned files from Steps 1-8 now have homes!
Steps 1-8 complete + all orphaned files reorganized. Updated: - Completion summary showing all steps done - Final folder structure with accurate file counts - Marked misc/ and advanced-topics/ as permanent categories - Documented all orphaned file decisions Total: ~50+ files moved across 10 categories.
|
Warning Rate limit exceeded@justin808 has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 18 minutes and 56 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (6)
WalkthroughRemoved two legacy dependency how-tos and consolidated dependency guidance into a single misc doc. Added multiple planning and tracking documents to support a documentation Information Architecture (IA) redesign and updated many internal doc links to reflect the new structure. No exported/public API or runtime code changes. Changes
Sequence Diagram(s)(omitted — changes are documentation content and link reorganizations; no control-flow or runtime feature introduced) 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)
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[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (7)
docs/misc/updating-dependencies.md (1)
28-39: Promote “Option” labels to proper headings.
Markdownlint (MD036) flags the bold “Option 1/2” lines because they read like section titles. Converting them to headings (e.g.,#### Option 1: ...) keeps lint clean and improves accessibility/navigation.Also applies to: 47-55
docs/planning/docs-improvement/GITHUB_ISSUE_DRAFT.md (2)
71-79: Add a language hint to fenced code blocks.markdownlint is flagging these fences because they don’t declare a language. Append something like
text(ormarkdownif you want syntax highlighting) to keep our lint checks green.Apply this:
-``` +```text 1. 🚀 Getting Started → Onboarding, first component (6-8 docs) 2. 📚 Core Concepts → SSR, bundling, how it works (8-10 docs) 3. 🔧 Building Features → Common patterns, integrations (10-12 docs) 4. 📖 API Reference → View helpers, config, JS API (5-7 docs) 5. 🚢 Deployment → Production, troubleshooting (8-10 docs) 6. 🔄 Migration → Upgrading, migrating from others (5-7 docs) 7. 💎 React on Rails Pro → Pro features (2-3 docs)
126-139: Second code fence also needs a language.Same lint warning applies to this file-tree block—add a language marker (e.g.
text) so markdownlint passes.-``` +```text docs/ ├── introduction.md # NEW HOMEPAGE ├── getting-started/ │ ├── quick-start.md │ ├── installation.md │ └── tutorial.md ├── core-concepts/ ├── building/ ├── api-reference/ ├── deployment/ ├── migration/ └── pro/docs/planning/docs-improvement/04-ia-redesign-plan.md (1)
28-41: Specify code-fence languages to satisfy markdownlint.Several fences in this doc (this one and others at lines ~98, 152, 184, etc.) are missing language hints, which our lint job will flag. Add
text,bash, or whichever fits each block so we stay compliant.Here’s the pattern to apply:
-``` +```text 1. [Root] ← Misc files at root 2. Guides ← 21 files, everything from installation to advanced SSR ...docs/planning/docs-improvement/01-problem-analysis.md (1)
17-33: Add language tags to the fenced blocks.markdownlint is unhappy with these unlabeled fences (and others later in the file). Tag them with the appropriate language (
javascript,markdown,text, etc.) to keep linting clean.Example:
-``` +```javascript const reactOnRailsDocsFoldersOrder = [ firstCategory, // Root-level files 'Guides', // 18+ diverse topics ...docs/planning/docs-improvement/ia-redesign-live.md (1)
324-400: Add a language hint to the closing folder-structure fence.Same markdownlint issue as the other docs—tag this fence (
textworks well) so linting passes.-``` +```text docs/ ├── introduction.md # TODO: Create in next phase ├── getting-started/ (4 files) ...docs/planning/docs-improvement/02-pr-1813-comparison.md (1)
197-211: Label the fenced blocks for markdownlint.This code fence (and others later at ~242, 522, 548) need language annotations. Add
javascript,text, etc., so automated linting doesn’t fail.For instance:
-``` +```javascript const reactOnRailsDocsFoldersOrder = [ firstCategory, 'Guides', ...
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (8)
docs/additional-details/updating-dependencies.md(0 hunks)docs/javascript/node-dependencies-and-npm.md(0 hunks)docs/misc/updating-dependencies.md(1 hunks)docs/planning/docs-improvement/01-problem-analysis.md(1 hunks)docs/planning/docs-improvement/02-pr-1813-comparison.md(1 hunks)docs/planning/docs-improvement/04-ia-redesign-plan.md(1 hunks)docs/planning/docs-improvement/GITHUB_ISSUE_DRAFT.md(1 hunks)docs/planning/docs-improvement/ia-redesign-live.md(1 hunks)
💤 Files with no reviewable changes (2)
- docs/additional-details/updating-dependencies.md
- docs/javascript/node-dependencies-and-npm.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/planning/docs-improvement/ia-redesign-live.mddocs/planning/docs-improvement/02-pr-1813-comparison.mddocs/planning/docs-improvement/01-problem-analysis.mddocs/misc/updating-dependencies.mddocs/planning/docs-improvement/GITHUB_ISSUE_DRAFT.mddocs/planning/docs-improvement/04-ia-redesign-plan.md
🪛 markdownlint-cli2 (0.18.1)
docs/planning/docs-improvement/ia-redesign-live.md
150-150: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
294-294: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
324-324: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/planning/docs-improvement/02-pr-1813-comparison.md
231-231: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
242-242: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
277-277: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
388-388: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
404-404: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
418-418: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
434-434: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
522-522: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
548-548: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/misc/updating-dependencies.md
28-28: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
47-47: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
docs/planning/docs-improvement/GITHUB_ISSUE_DRAFT.md
3-3: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
31-31: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
46-46: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
57-57: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
71-71: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
126-126: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/planning/docs-improvement/04-ia-redesign-plan.md
28-28: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
98-98: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
152-152: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
184-184: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
230-230: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
278-278: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
321-321: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
350-350: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
375-375: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
394-394: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
403-403: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
405-405: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
414-414: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
416-416: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
422-422: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
424-424: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
428-428: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
430-430: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
437-437: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
439-439: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
677-677: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
702-702: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
919-919: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
926-926: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
936-936: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
1109-1109: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
1116-1116: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
1123-1123: 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). (9)
- GitHub Check: dummy-app-integration-tests (3.4, 22)
- GitHub Check: rspec-package-tests (3.4, minimum)
- GitHub Check: rspec-package-tests (3.4, latest)
- GitHub Check: rspec-package-tests (3.2, minimum)
- GitHub Check: build
- GitHub Check: rspec-package-tests (3.2, latest)
- GitHub Check: markdown-link-check
- GitHub Check: claude-review
- GitHub Check: build-and-test
Documentation IA Redesign Review ✅Excellent work on this comprehensive documentation reorganization! This PR successfully transforms a confusing 11-category structure into a clear, user-journey-based 10-category system. Here's my detailed review: 🎯 Overall Assessment: APPROVEDThis is a well-executed Phase 2 implementation that significantly improves documentation discoverability. The reorganization follows solid IA principles and industry best practices. ✅ Strengths1. Clear User Journey StructureThe new 10-category organization is intuitive and follows natural user progression:
2. Excellent Decision-Making ProcessThe
3. Git History PreservationAll files moved using 4. Content ConsolidationMerged 5. Planning DocumentationThe planning docs in
|
Updated 133+ broken internal documentation links across 28 files to reflect the new directory structure: - guides/ → getting-started/, core-concepts/, building-features/, deployment/, upgrading/ - api/ → api-reference/ - javascript/ → building-features/, deployment/, outdated/ - rails/ → building-features/, migrating/ - additional-details/ → getting-started/, advanced-topics/, misc/ - troubleshooting/ → deployment/ - quick-start/ → getting-started/ - release-notes/ → upgrading/release-notes/ - react-on-rails-pro/ → pro/ All links now point to correct locations in the reorganized structure. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Pull Request Review: Documentation Reorganization (PR #1845)Overall Assessment ✅This is an excellent documentation reorganization that significantly improves the user experience. The migration from 11 confusing categories to 10 user-journey-based categories is well-thought-out and properly executed. Recommendation: Approve with minor suggestions Strengths 💪1. Well-Executed File Migrations
2. User-Centric StructureThe new 10-category structure follows a logical user journey:
3. Thorough Documentation
4. Code Quality
Issues & Recommendations 🔍Critical Issues
|
There was a problem hiding this comment.
Actionable comments posted: 2
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (28)
docs/README.md(3 hunks)docs/advanced-topics/manual-installation-overview.md(1 hunks)docs/api-reference/README.md(1 hunks)docs/api-reference/generator-details.md(1 hunks)docs/api-reference/view-helpers-api.md(3 hunks)docs/building-features/code-splitting.md(1 hunks)docs/building-features/how-to-conditionally-server-render-based-on-device-type.md(1 hunks)docs/building-features/rspec-configuration.md(2 hunks)docs/core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md(2 hunks)docs/core-concepts/client-vs-server-rendering.md(1 hunks)docs/core-concepts/how-react-on-rails-works.md(1 hunks)docs/core-concepts/react-on-rails-overview.md(1 hunks)docs/core-concepts/react-server-rendering.md(2 hunks)docs/core-concepts/render-functions-and-railscontext.md(1 hunks)docs/core-concepts/render-functions.md(1 hunks)docs/core-concepts/webpack-configuration.md(1 hunks)docs/deployment/troubleshooting-build-errors.md(1 hunks)docs/deployment/troubleshooting.md(1 hunks)docs/getting-started.md(6 hunks)docs/getting-started/installation-into-an-existing-rails-app.md(2 hunks)docs/getting-started/quick-start.md(1 hunks)docs/getting-started/tutorial.md(1 hunks)docs/home.md(1 hunks)docs/migrating/convert-rails-5-api-only-app.md(1 hunks)docs/misc/articles.md(1 hunks)docs/misc/doctrine.md(1 hunks)docs/upgrading/release-notes/16.0.0.md(1 hunks)docs/upgrading/upgrading-react-on-rails.md(2 hunks)
✅ Files skipped from review due to trivial changes (13)
- docs/migrating/convert-rails-5-api-only-app.md
- docs/api-reference/README.md
- docs/building-features/how-to-conditionally-server-render-based-on-device-type.md
- docs/misc/doctrine.md
- docs/core-concepts/react-on-rails-overview.md
- docs/upgrading/upgrading-react-on-rails.md
- docs/core-concepts/render-functions.md
- docs/deployment/troubleshooting.md
- docs/getting-started/tutorial.md
- docs/core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md
- docs/misc/articles.md
- docs/core-concepts/client-vs-server-rendering.md
- docs/core-concepts/how-react-on-rails-works.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/api-reference/generator-details.mddocs/getting-started/installation-into-an-existing-rails-app.mddocs/deployment/troubleshooting-build-errors.mddocs/core-concepts/render-functions-and-railscontext.mddocs/core-concepts/react-server-rendering.mddocs/getting-started.mddocs/README.mddocs/getting-started/quick-start.mddocs/core-concepts/webpack-configuration.mddocs/home.mddocs/upgrading/release-notes/16.0.0.mddocs/api-reference/view-helpers-api.mddocs/building-features/code-splitting.mddocs/building-features/rspec-configuration.mddocs/advanced-topics/manual-installation-overview.md
🧠 Learnings (4)
📚 Learning: 2025-09-16T08:01:11.146Z
Learnt from: justin808
PR: shakacode/react_on_rails#1770
File: lib/generators/react_on_rails/templates/base/base/app/javascript/src/HelloWorld/ror_components/HelloWorld.client.jsx:2-2
Timestamp: 2025-09-16T08:01:11.146Z
Learning: React on Rails uses webpack CSS Modules configuration with namedExports: true, which requires the import syntax `import * as style from './file.module.css'` rather than the default export pattern. This configuration enables better tree shaking and bundle size optimization for CSS modules.
Applied to files:
docs/getting-started.mddocs/advanced-topics/manual-installation-overview.md
📚 Learning: 2025-02-12T16:38:06.537Z
Learnt from: Romex91
PR: shakacode/react_on_rails#1697
File: package-scripts.yml:28-28
Timestamp: 2025-02-12T16:38:06.537Z
Learning: The file `node_package/lib/ReactOnRails.full.js` is autogenerated during the build process and should not be present in the repository.
Applied to files:
docs/getting-started.md
📚 Learning: 2025-02-13T16:50:26.861Z
Learnt from: AbanoubGhadban
PR: shakacode/react_on_rails#1644
File: node_package/src/turbolinksUtils.ts:34-36
Timestamp: 2025-02-13T16:50:26.861Z
Learning: In React on Rails, when checking for Turbolinks version 5 using `turbolinksVersion5()`, always ensure `Turbolinks` exists first by checking `turbolinksInstalled()` to prevent TypeError when accessing properties.
Applied to files:
docs/upgrading/release-notes/16.0.0.md
📚 Learning: 2025-09-15T21:24:48.207Z
Learnt from: AbanoubGhadban
PR: shakacode/react_on_rails#1781
File: node_package/src/ClientSideRenderer.ts:82-95
Timestamp: 2025-09-15T21:24:48.207Z
Learning: In React on Rails, the force_load feature includes both explicit `data-force-load="true"` usage and the ability to hydrate components during the page loading state (`document.readyState === 'loading'`). Both capabilities require a Pro license, so the condition `!railsContext.rorPro && (isComponentForceLoaded || document.readyState === 'loading')` correctly gates both scenarios.
Applied to files:
docs/upgrading/release-notes/16.0.0.md
🪛 markdownlint-cli2 (0.18.1)
docs/getting-started.md
14-14: Link fragments should be valid
(MD051, link-fragments)
⏰ 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.2, 20)
- GitHub Check: dummy-app-integration-tests (3.4, 22)
- GitHub Check: markdown-link-check
- GitHub Check: build
- GitHub Check: rspec-package-tests (3.2, latest)
- GitHub Check: rspec-package-tests (3.4, latest)
- GitHub Check: rspec-package-tests (3.2, minimum)
- GitHub Check: rspec-package-tests (3.4, minimum)
- GitHub Check: claude-review
- GitHub Check: build-and-test
🔇 Additional comments (1)
docs/core-concepts/react-server-rendering.md (1)
3-3: Links updated correctly
Both references resolve cleanly after the IA reorg. Nicely aligned with the new structure.Also applies to: 17-17
Comment on lines
+81
to
82
| - Configure `config/initializers/react_on_rails.rb`. You can adjust some necessary settings and defaults. See file [docs/basics/configuration.md](./api-reference/configuration.md) for documentation of all configuration options. | ||
| - Configure `config/shakapacker.yml`. If you used the generator and the default Shakapacker setup, you don't need to touch this file. If you are customizing your setup, then consult the [spec/dummy/config/shakapacker.yml](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/config/shakapacker.yml) example or the official default [shakapacker.yml](https://github.com/shakacode/shakapacker/blob/master/lib/install/config/shakapacker.yml). |
There was a problem hiding this comment.
Update the configuration link label
The visible link text still says docs/basics/configuration.md, but that file was removed in the reorg. Please update the label so it matches the new target under api-reference.
Apply this diff:
-- Configure `config/initializers/react_on_rails.rb`. You can adjust some necessary settings and defaults. See file [docs/basics/configuration.md](./api-reference/configuration.md) for documentation of all configuration options.
+- Configure `config/initializers/react_on_rails.rb`. You can adjust some necessary settings and defaults. See the [Configuration reference](./api-reference/configuration.md) for documentation of all configuration options.📝 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.
Suggested change
| - Configure `config/initializers/react_on_rails.rb`. You can adjust some necessary settings and defaults. See file [docs/basics/configuration.md](./api-reference/configuration.md) for documentation of all configuration options. | |
| - Configure `config/shakapacker.yml`. If you used the generator and the default Shakapacker setup, you don't need to touch this file. If you are customizing your setup, then consult the [spec/dummy/config/shakapacker.yml](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/config/shakapacker.yml) example or the official default [shakapacker.yml](https://github.com/shakacode/shakapacker/blob/master/lib/install/config/shakapacker.yml). | |
| - Configure `config/initializers/react_on_rails.rb`. You can adjust some necessary settings and defaults. See the [Configuration reference](./api-reference/configuration.md) for documentation of all configuration options. | |
| - Configure `config/shakapacker.yml`. If you used the generator and the default Shakapacker setup, you don't need to touch this file. If you are customizing your setup, then consult the [spec/dummy/config/shakapacker.yml](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/config/shakapacker.yml) example or the official default [shakapacker.yml](https://github.com/shakacode/shakapacker/blob/master/lib/install/config/shakapacker.yml). |
🤖 Prompt for AI Agents
In docs/getting-started.md around lines 81 to 82, the link label still reads
"docs/basics/configuration.md" but the target file moved to api-reference;
update the visible link text to match the new location (e.g.,
"api-reference/configuration.md" or simply "Configuration") so the label
accurately reflects the target path and remove the outdated docs/basics
reference; keep the href as ./api-reference/configuration.md and ensure the
label text is updated accordingly.
- Fix links in docs/guides/advanced/README.md to point to core-concepts/ - Fix asset link in docs/upgrading/release-notes/16.0.0.md - Fix turbolinks link in docs/upgrading/release-notes/16.0.0.md All broken links reported by markdown-link-check CI have been fixed.
Applied Prettier autofix to resolve CI formatting check failure. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
PR Review: Documentation ReorganizationThank you for this comprehensive documentation reorganization effort! This is a significant improvement that will make the docs much more navigable and user-friendly. Here's my detailed review: ✅ StrengthsExcellent Structure
Implementation Quality
Documentation Excellence
🔍 Issues & Recommendations1. Empty/Incomplete Directory CleanupThe PR description mentions "What's Next: Delete empty folders" but:
Recommendation:
2. File Endings (CRITICAL for CI)Per
Action Required: Verify all moved/modified files end with newlines before merging. CI will fail otherwise. 3. Linting Requirements (CRITICAL for CI)Per
Action Required: Run 4. Missing README FilesSome new directories lack README.md files for navigation:
Recommendation: Add brief README.md files to major categories to provide context and file listings, similar to 5. Outdated Directory HandlingThe
Recommendation: Add a standardized warning banner to all files in 6. Planning Files in Production DocsThe
Recommendation: Consider moving planning docs to a separate location ( 📋 Pre-Merge ChecklistBefore merging, please verify:
🎯 Overall AssessmentScore: 8.5/10 This is excellent work that significantly improves documentation usability. The reorganization is well-thought-out, execution is clean, and git history is preserved. The main items are:
The structure itself is ready - just needs the final polish to meet CI requirements and complete the cleanup phase. 💡 Suggestions for Phase 3Since you mentioned website config updates are next:
Great work on this reorganization! 🎉 Generated with Claude Code 🤖 |
Fixed broken external GitHub links: - Updated shakapacker environment config links from .js to .ts files - Removed outdated react-webpack-rails-tutorial RouterApp file references - Fixed README.md advanced-topics link to point to guides/advanced/ All external links now point to valid resources. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
4 tasks
ihabadham
added a commit
that referenced
this pull request
Oct 19, 2025
Updated two broken links in react-router.md that were pointing to the old location ../rails/turbolinks.md which no longer exists. The turbolinks.md file was moved from docs/rails/ to docs/building-features/ during the PR #1845 documentation reorganization, but these links were not updated at that time. Changes: - ../rails/turbolinks.md → ./turbolinks.md (same directory) This fixes the markdown-link-check CI failure: ERROR: 1 dead link found in docs/building-features/react-router.md ! [✖] ../rails/turbolinks.md → Status: 400 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
ihabadham
added a commit
that referenced
this pull request
Oct 19, 2025
This category index file was an orphaned remnant from PR #1813 that used a different navigation approach with category landing pages. During the IA redesign (PR #1845), similar category index files like guides/advanced/README.md were deleted as "redundant" because docs/README.md now serves as the single navigation hub. The api-reference/README.md survived by accident and is now the only category with such an index file, creating inconsistency. Changes: - Deleted docs/api-reference/README.md (7-line TOC) - Updated docs/README.md reference to point directly to view-helpers-api.md (the main API reference file) - Preserves existing folder-level link on line 50 that points to api-reference/ Rationale: Category folders don't need README indexes when the main docs hub already provides navigation. This matches the pattern established when we deleted guides/advanced/README.md.
ihabadham
added a commit
that referenced
this pull request
Oct 21, 2025
Updated two broken links in react-router.md that were pointing to the old location ../rails/turbolinks.md which no longer exists. The turbolinks.md file was moved from docs/rails/ to docs/building-features/ during the PR #1845 documentation reorganization, but these links were not updated at that time. Changes: - ../rails/turbolinks.md → ./turbolinks.md (same directory) This fixes the markdown-link-check CI failure: ERROR: 1 dead link found in docs/building-features/react-router.md ! [✖] ../rails/turbolinks.md → Status: 400 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
ihabadham
added a commit
that referenced
this pull request
Oct 21, 2025
This category index file was an orphaned remnant from PR #1813 that used a different navigation approach with category landing pages. During the IA redesign (PR #1845), similar category index files like guides/advanced/README.md were deleted as "redundant" because docs/README.md now serves as the single navigation hub. The api-reference/README.md survived by accident and is now the only category with such an index file, creating inconsistency. Changes: - Deleted docs/api-reference/README.md (7-line TOC) - Updated docs/README.md reference to point directly to view-helpers-api.md (the main API reference file) - Preserves existing folder-level link on line 50 that points to api-reference/ Rationale: Category folders don't need README indexes when the main docs hub already provides navigation. This matches the pattern established when we deleted guides/advanced/README.md.
ihabadham
added a commit
that referenced
this pull request
Oct 23, 2025
Updated two broken links in react-router.md that were pointing to the old location ../rails/turbolinks.md which no longer exists. The turbolinks.md file was moved from docs/rails/ to docs/building-features/ during the PR #1845 documentation reorganization, but these links were not updated at that time. Changes: - ../rails/turbolinks.md → ./turbolinks.md (same directory) This fixes the markdown-link-check CI failure: ERROR: 1 dead link found in docs/building-features/react-router.md ! [✖] ../rails/turbolinks.md → Status: 400 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
ihabadham
added a commit
that referenced
this pull request
Oct 23, 2025
This category index file was an orphaned remnant from PR #1813 that used a different navigation approach with category landing pages. During the IA redesign (PR #1845), similar category index files like guides/advanced/README.md were deleted as "redundant" because docs/README.md now serves as the single navigation hub. The api-reference/README.md survived by accident and is now the only category with such an index file, creating inconsistency. Changes: - Deleted docs/api-reference/README.md (7-line TOC) - Updated docs/README.md reference to point directly to view-helpers-api.md (the main API reference file) - Preserves existing folder-level link on line 50 that points to api-reference/ Rationale: Category folders don't need README indexes when the main docs hub already provides navigation. This matches the pattern established when we deleted guides/advanced/README.md.
ihabadham
added a commit
that referenced
this pull request
Oct 27, 2025
Updated two broken links in react-router.md that were pointing to the old location ../rails/turbolinks.md which no longer exists. The turbolinks.md file was moved from docs/rails/ to docs/building-features/ during the PR #1845 documentation reorganization, but these links were not updated at that time. Changes: - ../rails/turbolinks.md → ./turbolinks.md (same directory) This fixes the markdown-link-check CI failure: ERROR: 1 dead link found in docs/building-features/react-router.md ! [✖] ../rails/turbolinks.md → Status: 400 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
ihabadham
added a commit
that referenced
this pull request
Oct 27, 2025
This category index file was an orphaned remnant from PR #1813 that used a different navigation approach with category landing pages. During the IA redesign (PR #1845), similar category index files like guides/advanced/README.md were deleted as "redundant" because docs/README.md now serves as the single navigation hub. The api-reference/README.md survived by accident and is now the only category with such an index file, creating inconsistency. Changes: - Deleted docs/api-reference/README.md (7-line TOC) - Updated docs/README.md reference to point directly to view-helpers-api.md (the main API reference file) - Preserves existing folder-level link on line 50 that points to api-reference/ Rationale: Category folders don't need README indexes when the main docs hub already provides navigation. This matches the pattern established when we deleted guides/advanced/README.md.
Judahmeek
pushed a commit
that referenced
this pull request
Oct 28, 2025
* Remove orphaned docs/guides/advanced/README.md This navigation index file was left behind after the reorganization in #1845. The links it contained point to files now in core-concepts/, making this index redundant. Cleanup after PR #1845. * Create introduction.md and remove redundant overview - 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 and enhance introduction.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. * Update ia-redesign-live.md with Phase 3 progress 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 * Delete docs/home.md - replaced by introduction.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 getting-started.md into understanding-react-on-rails.md 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) * Rename understanding-react-on-rails.md to using-react-on-rails.md 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 <noreply@anthropic.com> * Improve tutorial: extract Heroku deployment, fix versions, reorganize 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 <noreply@anthropic.com> * Delete outdated manual-installation-overview.md 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 <noreply@anthropic.com> * Update IA redesign plan to reflect Phase 3 completion 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. * linting * Fix MDX parsing error in quick-start.md 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" * Fix documentation H1 headings for improved search indexing Add missing H1 headings and improve H1 quality across 10 documentation files to enable proper Algolia search indexing and improve accessibility. Critical fixes (missing H1): - configuration.md: Add "React on Rails Configuration Options" - react-on-rails-pro.md: Change H2 to H1 - rails-engine-integration.md: Add "Integrating React on Rails with Rails Engines" - troubleshooting-when-using-webpacker.md: Add H1 and fix structure - troubleshooting-when-using-shakapacker.md: Add H1 and fix heading hierarchy - credits.md: Add "React on Rails Credits and Authors" Quality improvements (better searchability): - images.md: "Images" → "Configuring Images and Assets with Webpack" - foreman-issues.md: "Foreman Issues" → "Troubleshooting Foreman with React on Rails" - updating-dependencies.md: "Updating Dependencies" → "Updating Ruby and JavaScript Dependencies" - api-reference/README.md: "API Reference" → "React on Rails API Reference Guide" Why: Algolia indexes H1 as primary title. Files without H1 show as "Untitled" in search results. Generic H1s reduce searchability. Reference: docs/planning/docs-improvement/h1-headings-audit-report.md (local file, not tracked) * Fix multiple H1 headings in documentation for improved search indexing Continue fixing H1 heading issues by addressing files with multiple H1s. Demoted duplicate H1s to H2 throughout documentation while maintaining proper heading hierarchy (H1→H2→H3→H4). Files changed: - tutorial.md: Demoted 6 H1s (Table of Contents, Installation, HMR, Deployment, Going Further, Conclusion) - rails-engine-integration.md: Changed "Github Issues" H1 to H2 - hmr-and-hot-reloading-with-the-webpack-dev-server.md: Fixed 2 H1s with proper hierarchy - i18n.md: "Notes" H1 to H2 - react-and-redux.md: "Redux Reducers" H1 to H2 - react-router.md: "Server Rendering Using React Router V4" H1 to H2 - rspec-configuration.md: 2 H1s to H2s - generator-details.md: "Understanding the Organization..." H1 to H2 - redux-store-api.md: "More Details" H1 to H2 - view-helpers-api.md: "More details" H1 to H2 - style.md: "Git Usage" H1 to H2 Rationale: Multiple H1s per document confuse Algolia search ranking, screen readers, and violate accessibility standards. Each document should have exactly one H1 as the main title. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Restructure turbolinks.md to clarify Turbo vs legacy Turbolinks Reorganize turbolinks.md content to clearly separate modern Turbo (recommended) from legacy Turbolinks support. All Turbolinks v2 and v5 content is now properly nested under "Legacy Turbolinks Support" section. Key structural changes: - "Using Turbo" section remains at H2 level (modern, recommended approach) - Created "Legacy Turbolinks Support" H2 section with clear deprecation notice - Nested all Turbolinks content as H3-H5 subsections: - Why Turbolinks? (H3) - Requirements and "Why Not" sections (H3) - Installation details with checklists (H3→H4→H5) - Turbolinks 5 Specific Information (H3) - Technical Details and Troubleshooting (H3→H4) Content improvements: - Added explicit support status for Turbolinks 5.x and 2.x - Clarified auto-detection behavior for legacy versions - Moved CSRF/MIME type technical details under proper troubleshooting section - Updated messaging from "may be outdated" to "still supported, migrate when possible" Rationale: Based on codebase investigation (pageLifecycle.ts, turbolinksUtils.ts), Turbo is the recommended navigation system since 2021. All Turbolinks versions are legacy but still supported. Original flat structure mixed modern and legacy content without clear distinction, potentially confusing users about which system to use. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Modernize generator and project structure documentation This commit updates documentation that was 9.5 years outdated, removing references to directory structures and patterns that haven't existed since 2016 and replacing them with accurate modern (2025) guidance. ## Changes to docs/api-reference/generator-details.md - Replace outdated structure description with accurate modern organization - Document both non-Redux and Redux generator structures separately - Add visual directory trees showing actual generated code locations - Document previously undocumented --typescript option - Remove references to non-existent app/lib folder (removed Apr 2016) - Remove incorrect path app/javascript/app/bundles (never existed - was docs typo) - Add auto-bundling explanation with cross-reference - Show real component structure: src/ComponentName/ror_components/ ## Changes to docs/building-features/react-router.md - Update path reference from legacy client/app/bundles to modern src/ structure - Clarify this example applies to --redux generator option - Make path reference generic rather than specific to outdated structure ## Changes to docs/getting-started/project-structure.md Complete rewrite to reflect modern React on Rails: ### Removed outdated content: - Old bundles/ structure presented as current (was 2015-2016 pattern) - "Moving node_modules to /client" section (tested and proven broken with Shakapacker) - References to /client/app/assets directory (generator stopped creating in Apr 2016) - Outdated CSS/assets management discussion ### Added modern content: - Modern auto-bundling structure as recommended approach - Traditional manual structure as legacy option with clear use cases - Decision guide for choosing between approaches - CSS Modules documentation (default in generator since modern versions) - Real code examples from actual generator templates - Rails Asset Pipeline as alternative approach - Advanced global styles pattern ## Historical Context Research revealed: - Oct 2015: Generator created client/app/lib/middlewares/ and client/app/bundles/ - Apr 5, 2016: Docs added describing app/lib folder - Apr 23, 2016: Generator removed these directories (18 days later!) - Apr 2016 - Oct 2025: Docs never updated - outdated for 9.5 years ## Testing Performed Created test app at /home/ihab/ihab/work/shakacode/test/default-structure-test/: - Verified default generator creates src/ structure, not bundles/ - Verified CSS modules co-located with components - Tested /client conversion: works perfectly (just move + config change) - Tested moving node_modules to /client: FAILS with Shakapacker - Confirmed SHAKAPACKER_CONFIG env var doesn't solve the issue 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Update React Router documentation and spec/dummy to v6 This major update modernizes React Router integration from outdated v4/v5 to current v6 API, fixing critical gaps discovered through testing. Documentation Changes (docs/building-features/react-router.md): - Remove 5-year-old "needs updating" warning - Pin React Router to v6 (^6.0.0) with explanation about v7 incompatibility - Add critical "Rails Routes Configuration" section with wildcard routing - Update all code examples to React Router v6 API: * Switch → Routes * component prop → element prop * StaticRouter import from 'react-router-dom/server' - Add path matching guidance (React Router paths must match Rails routes) - Update Turbolinks → Turbo/Turbolinks with Rails version context - Improve clarity: generator doesn't create React Router code - Add installation instructions and compatibility notes spec/dummy Updates (v5→v6 migration): - client/app/routes/routes.jsx: Add Routes wrapper, wildcard path support - client/app/components/RouterLayout.jsx: Switch→Routes, use relative paths - client/app/startup/RouterApp.server.jsx: Update StaticRouter import location - package.json: Upgrade react-router-dom from ^5.2.0 to ^6.0.0 - yarn.lock: Update dependencies (@remix-run/router@1.23.0) Key Discoveries from Testing: 1. React Router v7 merged with Remix, incompatible with our SSR approach 2. Rails wildcard routing is CRITICAL but was never documented 3. Documentation examples were 9+ years misleading about generator output 4. StaticRouter import location changed in v6 (breaks without this update) Testing: - Created fresh test app following documentation step-by-step - Validated client-side routing, SSR, direct URL visits, browser navigation - Confirmed spec/dummy React Router demo works with v6 API 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Modernize process manager documentation Replace outdated foreman-issues.md with comprehensive process-managers.md guide. Changes: - Create docs/building-features/process-managers.md with modern guidance - Documents both Overmind (recommended) and Foreman - Explains why React on Rails needs multiple processes - Includes authoritative explanation from Foreman's wiki about not bundling - Shows how bin/dev works under the hood - Move docs/building-features/foreman-issues.md to docs/outdated/ - Preserves 2017-era bug reports for historical reference - Removes clutter from main docs (outdated/ filtered from navigation) - Update lib/react_on_rails/dev/process_manager.rb - Change link from our old doc to official Foreman wiki - Users get explanation directly from authoritative source Addresses feedback that foreman-issues.md was outdated and didn't mention modern alternatives like Overmind (which bin/dev actually prefers). * Move outdated code-splitting.md to outdated/ and update references The code-splitting.md file was explicitly marked as "(Outdated)" and directed users to contact justin@shakacode.com instead of following it. The modern solution is React on Rails Pro's loadable-components guide. Changes: - Moved docs/building-features/code-splitting.md → docs/outdated/code-splitting.md - Updated API reference to point to Pro loadable-components (appropriate for reference docs) - Removed outdated code-splitting links from beginner guides (quick-start, using-react-on-rails) - Updated planning doc to track the move Rationale: - File content from 2017 for React Router v3/v4 with ExecJS - Uses deprecated patterns (manual renderer functions, webpack v1) - Example uses abandoned react-s3-uploader package - Pro's loadable-components doc (updated Sept 2022) provides modern approach - Uses @loadable/component (React team's official recommendation) - Both docs solve the same problem: code splitting WITH SSR - Outdated doc itself says to contact Justin about loadable-components Decision: Keep Pro feature out of beginner docs to avoid confusion about whether Pro is required. Only mention in API reference where advanced users look for specific features. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Fix broken links to outdated/webpack.md Two user-facing docs were linking to docs/outdated/webpack.md which is excluded from the website, causing 404 errors. Changes: - docs/core-concepts/webpack-configuration.md: Updated to link to Shakapacker's webpack customization docs (most relevant for users customizing webpack) - docs/deployment/troubleshooting-build-errors.md: Updated to link to our own webpack-configuration.md (keeps users in our documentation) Context: webpack.md was moved to outdated/ in commit e08f91d (Oct 3, 2025) because it contained "outdated Webpack v2 content". The file references Webpack v2 patterns and links to a 2017 forum post. These two links were not updated when the file was moved, causing broken references. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Remove outdated documentation folder The docs/outdated/ folder contained deprecated content that was excluded from the website build. This content is preserved in git history and can be accessed through previous commits if needed. Deleted files: - docs/outdated/code-splitting.md - docs/outdated/converting-from-custom-webpack-config-to-rails-webpacker-config.md - docs/outdated/deferred-rendering.md - docs/outdated/foreman-issues.md - docs/outdated/rails-assets-relative-paths.md - docs/outdated/rails-assets.md - docs/outdated/rails3.md - docs/outdated/tips-for-usage-with-sp6.md - docs/outdated/upgrade-webpacker-v3-to-v4.md - docs/outdated/webpack-v1-notes.md - docs/outdated/webpack.md This cleanup follows the recommendation to rely on git history rather than maintaining hidden documentation in the main branch. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Fix failing RSpec test after process manager docs update Updated test expectation to match the new Foreman documentation link. In commit 6cc93c7, we updated lib/react_on_rails/dev/process_manager.rb to link to Foreman's official wiki instead of our outdated foreman-issues.md. The test was still expecting the old link pattern. Change: - Old expectation: /foreman-issues\.md/ - New expectation: /Don't-Bundle-Foreman/ This matches the new error message which now points to: https://github.com/ddollar/foreman/wiki/Don't-Bundle-Foreman Fixes the failing spec: ReactOnRails::Dev::ProcessManager.show_process_manager_installation_help displays helpful error message with installation instructions 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Fix broken markdown links to turbolinks.md Updated two broken links in react-router.md that were pointing to the old location ../rails/turbolinks.md which no longer exists. The turbolinks.md file was moved from docs/rails/ to docs/building-features/ during the PR #1845 documentation reorganization, but these links were not updated at that time. Changes: - ../rails/turbolinks.md → ./turbolinks.md (same directory) This fixes the markdown-link-check CI failure: ERROR: 1 dead link found in docs/building-features/react-router.md ! [✖] ../rails/turbolinks.md → Status: 400 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Enable React Router v7 future flags to silence warnings in tests Added future flags to BrowserRouter in the dummy app to enable v7-compatible behavior and eliminate console warnings that were causing test failures. Changes: - spec/dummy/client/app/startup/RouterApp.client.jsx: Added future prop with v7_startTransition and v7_relativeSplatPath flags Why this fixes the issue: The dummy app integration tests were failing because selenium_logger.rb treats JavaScript console warnings as errors. React Router v6 emits warnings about upcoming v7 changes:⚠️ React Router Future Flag Warning: React Router will begin wrapping state updates in React.startTransition in v7. You can use the v7_startTransition future flag to opt-in early.⚠️ React Router Future Flag Warning: Relative route resolution within Splat routes is changing in v7. You can use the v7_relativeSplatPath future flag to opt-in early. By enabling these flags, we: 1. Silence the warnings 2. Adopt v7-compatible behavior early 3. Demonstrate best practices for React Router v6 users 4. Align with React Router's official migration guide Reference: https://reactrouter.com/upgrading/future Fixes test failures: - React Router when rendering /react_router is expected to have text "Woohoo..." - React Router when rendering /react_router clicking links correctly renders... 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Fix documentation issues identified in PR review Addresses valid issues from Claude's PR review: 1. Fixed JavaScript syntax error in using-react-on-rails.md:192 - Changed semicolon to comma in object destructuring example - Was accidentally introduced during linting commit 2. Clarified Rails version requirements in tutorial.md - Changed "We support Rails 6 and later" to "This tutorial targets Rails 7.0+" - Explicitly noted Rails 6 is supported but tutorial uses Rails 7 - Removed version confusion between prerequisites and tutorial steps 3. Fixed markdownlint issues - Added language hint to code fence in using-react-on-rails.md (text) - Added language hint to Procfile code fence in heroku-deployment.md (procfile) These changes ensure code examples are syntactically correct and version requirements are clear for users following the tutorial. * typo * Remove redundant api-reference/README.md This category index file was an orphaned remnant from PR #1813 that used a different navigation approach with category landing pages. During the IA redesign (PR #1845), similar category index files like guides/advanced/README.md were deleted as "redundant" because docs/README.md now serves as the single navigation hub. The api-reference/README.md survived by accident and is now the only category with such an index file, creating inconsistency. Changes: - Deleted docs/api-reference/README.md (7-line TOC) - Updated docs/README.md reference to point directly to view-helpers-api.md (the main API reference file) - Preserves existing folder-level link on line 50 that points to api-reference/ Rationale: Category folders don't need README indexes when the main docs hub already provides navigation. This matches the pattern established when we deleted guides/advanced/README.md. * fix dead link * another dead link * Update Node.js requirement from 18+/16 to 20+ across documentation Fixes Node version inconsistencies identified by CodeRabbit in PR #1860. Changes: - docs/introduction.md: 18+ → 20+ - docs/getting-started/quick-start.md: 18+ → 20+ - docs/deployment/heroku-deployment.md: 16.19.0 → 20.0.0 Rationale: - React on Rails v16 requires Node 20+ for ESM module support - Node 16 reached EOL in September 2023 - Node 18 reaches EOL in April 2025 - CI currently tests only Node 20 and 22 - Release notes specify Node 20.19.0+ or 22.12.0+ required The tutorial.md (line 7) says "Updated for React on Rails v16" and users following it would use Node 20+, so deployment guide should match to avoid confusion. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Fix broken React Router v6 migration guide link The link was returning 404. Updated from the incorrect path: - /en/main/upgrading/v5 (broken) to the working path: - /docs/en/v6/upgrading/v5 (verified working) This link was added in commit 391281a when updating React Router documentation to v6. The URL structure changed on reactrouter.com. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Fix inconsistent link text in how-to-conditionally-server-render doc Update link display text from 'here in docs/basics/configuration.md' to 'available here' to match the actual URL path (docs/api-reference/configuration/) Co-authored-by: Ihab Adham <ihabadham@users.noreply.github.com> * Document Turbo integration and immediate_hydration feature (resolve TODO) Replace TODO from PR #1620 with comprehensive Turbo documentation covering both free (Turbo Frames) and Pro (Turbo Streams) features. Changes: 1. **New "Using Turbo" Section** - Installation steps (turbo-rails gem + @hotwired/turbo-rails package) - Basic configuration (ReactOnRails.setOptions({ turbo: true })) - Turbo Frames usage (free, works out of the box) - Turbo Streams usage (requires immediate_hydration: true - Pro feature) - Complete working example with turbo_frame_tag and turbo_stream.update - Links to v16.0 release notes, streaming docs, and spec/dummy example 2. **Migration Context** - Note about force_load → immediate_hydration rename in v16.0 - Clear distinction between free vs Pro features - Explanation of WHY Turbo Streams need immediate_hydration (they don't dispatch turbo:render events, directly manipulate DOM) 3. **Improved Async Scripts Warning** - Replaced confusing "Do not use immediate_hydration: false" warning - New clear warning: "Async Scripts with Turbolinks Require Pro Feature" - Explains the race condition problem - Provides three alternatives with behavioral descriptions: * defer (waits for full page load before hydration) * Upgrade to Turbo (recommended) * Use Pro for immediate_hydration: true Technical Context: - PR #1620 (Aug 2024) added force_load for Turbo Streams - PR #1781 (Sep 2025) renamed to immediate_hydration + made Pro-only - Feature still actively used (spec/dummy has working example) - Default immediate_hydration: false causes race conditions with async scripts Resolves TODO on line 16 left by Justin in PR #1620 comments. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Remove confusing "(Free)" label from Turbo Basic Setup heading The "(Free)" label in "### Basic Setup (Free)" was confusing because: - Appears before any mention of Pro features - Not used elsewhere in the codebase - Readers don't know what it's contrasting with yet - The Pro callout box later provides sufficient contrast Changed to simply "### Basic Setup" to match patterns used in other docs like streaming-server-rendering.md. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Fix multiple H1 headings in client-vs-server-rendering.md Changed second H1 to H2 for proper document structure: - Line 21: "# Different Server-Side Rendering Code" → "## Different..." Having multiple H1s in a document is problematic for: - SEO (search engines expect one H1 per page) - Accessibility (screen readers use heading hierarchy) - Documentation systems (assume H1 is the page title) - Navigation/table of contents generation The second heading is a subtopic about techniques for having different client/server code, so it should be H2 under the main page topic. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com> Co-authored-by: Ihab Adham <ihabadham@users.noreply.github.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What Changed
Reorganized ~50 documentation files from 11 confusing categories into 10 clear user-journey-based categories.
New Structure (10 categories)
Key Decisions
git mvfor all movesFiles Changed
Why
Current 11-category structure is confusing:
New structure follows user journey from getting started → building → deploying.
Status (vs Original Plan)
Original Plan: 7 categories in
GITHUB_ISSUE_DRAFT.mdActual Implementation: 10 categories
Phase 2 Complete (File Reorganization)
What's Next
These changes only affect file locations in the repo. To make them visible on the website:
Review Focus
docs/planning/docs-improvement/ia-redesign-live.mdfor full mapping)This change is
Summary by CodeRabbit