docs: Reorganize documentation into 10 user-journey-based categories #1845
Conversation
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 <[email protected]>
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 <[email protected]>
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 <[email protected]>
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 <[email protected]>
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 <[email protected]>
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 <[email protected]>
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 <[email protected]>
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 <[email protected]>
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 <[email protected]>
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 <[email protected]>
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 <[email protected]>
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 <[email protected]>
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
| - 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.
| - 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 <[email protected]>
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 <[email protected]>
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 <[email protected]>
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.
2 participants
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