docs: Reorganize documentation into 10 user-journey-based categories

docs/README.md

@@ -6,9 +6,9 @@
 
 New to React on Rails? Start here for the fastest path to success:
 
-**→ [15-Minute Quick Start Guide](./quick-start/README.md)**
+**→ [15-Minute Quick Start Guide](./getting-started/quick-start.md)**
 
-Already have Rails + Shakapacker? **→ [Add to existing app guide](./guides/installation-into-an-existing-rails-app.md)**
+Already have Rails + Shakapacker? **→ [Add to existing app guide](./getting-started/installation-into-an-existing-rails-app.md)**
 
 ## 📚 Learning Paths
 
@@ -18,72 +18,72 @@ Choose your journey based on your experience level:
 
 Perfect if you're new to React on Rails
 
-1. **[Quick Start](./quick-start/README.md)** - Get your first component running
+1. **[Quick Start](./getting-started/quick-start.md)** - Get your first component running
 2. **[Core Concepts](./getting-started.md)** - Understand the basics
-3. **[Tutorial](./guides/tutorial.md)** - Build something useful
+3. **[Tutorial](./getting-started/tutorial.md)** - Build something useful
 
 ### ⚡ **Experienced Developer Path**
 
 Jump to what you need
 
-- **[Installation Guide](./guides/installation-into-an-existing-rails-app.md)** - Detailed setup
-- **[API Reference](./api/README.md)** - Quick lookup
+- **[Installation Guide](./getting-started/installation-into-an-existing-rails-app.md)** - Detailed setup
+- **[API Reference](./api-reference/README.md)** - Quick lookup
 - **[Advanced Features](./guides/advanced/README.md)** - SSR, Redux, Router
 
 ### 🏗️ **Migrating from Other Solutions**
 
-- **[From react-rails](./additional-details/migrating-from-react-rails.md)** - Switch from the react-rails gem
-- **[Upgrading React on Rails](./guides/upgrading-react-on-rails.md)** - Version upgrade guide
+- **[From react-rails](./migrating/migrating-from-react-rails.md)** - Switch from the react-rails gem
+- **[Upgrading React on Rails](./upgrading/upgrading-react-on-rails.md)** - Version upgrade guide
 
 ## 🎯 Popular Use Cases
 
 Find guidance for your specific scenario:
 
-| I want to...                        | Go here                                                                    |
-| ----------------------------------- | -------------------------------------------------------------------------- |
-| **Add React to existing Rails app** | [Installation Guide](./guides/installation-into-an-existing-rails-app.md)  |
-| **Enable server-side rendering**    | [SSR Guide](./guides/react-server-rendering.md)                            |
-| **Set up hot reloading**            | [HMR Setup](./guides/hmr-and-hot-reloading-with-the-webpack-dev-server.md) |
-| **Use Redux with Rails**            | [Redux Integration](./javascript/react-and-redux.md)                       |
-| **Deploy to production**            | [Deployment Guide](./guides/deployment.md)                                 |
-| **Troubleshoot issues**             | [Troubleshooting](./troubleshooting/README.md)                             |
+| I want to...                        | Go here                                                                               |
+| ----------------------------------- | ------------------------------------------------------------------------------------- |
+| **Add React to existing Rails app** | [Installation Guide](./getting-started/installation-into-an-existing-rails-app.md)    |
+| **Enable server-side rendering**    | [SSR Guide](./core-concepts/react-server-rendering.md)                                |
+| **Set up hot reloading**            | [HMR Setup](./building-features/hmr-and-hot-reloading-with-the-webpack-dev-server.md) |
+| **Use Redux with Rails**            | [Redux Integration](./building-features/react-and-redux.md)                           |
+| **Deploy to production**            | [Deployment Guide](./deployment/deployment.md)                                        |
+| **Troubleshoot issues**             | [Troubleshooting](./deployment/troubleshooting.md)                                    |
 
 ## 📖 Complete Documentation
 
 ### Core Guides
 
 - **[Getting Started](./getting-started.md)** - Installation and basic setup
-- **[Tutorial](./guides/tutorial.md)** - Complete walkthrough with examples
-- **[Configuration](./guides/configuration.md)** - All configuration options
-- **[View Helpers](./api/view-helpers-api.md)** - Using `react_component` method
+- **[Tutorial](./getting-started/tutorial.md)** - Complete walkthrough with examples
+- **[Configuration](./api-reference/configuration.md)** - All configuration options
+- **[View Helpers](./api-reference/view-helpers-api.md)** - Using `react_component` method
 
 ### Features
 
-- **[Server-Side Rendering](./guides/react-server-rendering.md)** - SSR setup and optimization
-- **[Auto-Bundling](./guides/auto-bundling-file-system-based-automated-bundle-generation.md)** - Automatic bundle generation
-- **[Redux Integration](./javascript/react-and-redux.md)** - State management with Redux
-- **[React Router](./javascript/react-router.md)** - Client-side routing
-- **[Internationalization](./guides/i18n.md)** - I18n support
+- **[Server-Side Rendering](./core-concepts/react-server-rendering.md)** - SSR setup and optimization
+- **[Auto-Bundling](./core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md)** - Automatic bundle generation
+- **[Redux Integration](./building-features/react-and-redux.md)** - State management with Redux
+- **[React Router](./building-features/react-router.md)** - Client-side routing
+- **[Internationalization](./building-features/i18n.md)** - I18n support
 
 ### Development
 
-- **[Hot Module Replacement](./guides/hmr-and-hot-reloading-with-the-webpack-dev-server.md)** - Fast development workflow
-- **[Testing](./guides/rspec-configuration.md)** - Testing React components
-- **[Debugging](./javascript/troubleshooting-build-errors.md)** - Common debugging techniques
+- **[Hot Module Replacement](./building-features/hmr-and-hot-reloading-with-the-webpack-dev-server.md)** - Fast development workflow
+- **[Testing](./building-features/rspec-configuration.md)** - Testing React components
+- **[Debugging](./deployment/troubleshooting-build-errors.md)** - Common debugging techniques
 
 ### Deployment & Performance
 
-- **[Deployment](./guides/deployment.md)** - Production deployment guide
-- **[Performance](./guides/webpack-configuration.md)** - Optimization techniques
-- **[Bundle Optimization](./guides/webpack-configuration.md)** - Reduce bundle size
+- **[Deployment](./deployment/deployment.md)** - Production deployment guide
+- **[Performance](./core-concepts/webpack-configuration.md)** - Optimization techniques
+- **[Bundle Optimization](./core-concepts/webpack-configuration.md)** - Reduce bundle size
 
 ## 🆘 Need Help?
 
 ### Quick Solutions
 
-- **[Troubleshooting Guide](./troubleshooting/README.md)** - Common issues and solutions
-- **[FAQ](./troubleshooting/README.md)** - Frequently asked questions
-- **[Error Messages](./javascript/troubleshooting-build-errors.md)** - Decode error messages
+- **[Troubleshooting Guide](./deployment/troubleshooting.md)** - Common issues and solutions
+- **[FAQ](./deployment/troubleshooting.md)** - Frequently asked questions
+- **[Error Messages](./deployment/troubleshooting-build-errors.md)** - Decode error messages
 
 ### Community Support
 
@@ -108,62 +108,62 @@ Find guidance for your specific scenario:
 
 ### API Reference
 
-- [View Helpers API](./api/view-helpers-api.md)
-- [Redux Store API](./api/redux-store-api.md)
-- [JavaScript API](./api/javascript-api.md)
+- [View Helpers API](./api-reference/view-helpers-api.md)
+- [Redux Store API](./api-reference/redux-store-api.md)
+- [JavaScript API](./api-reference/javascript-api.md)
 
 ### Guides
 
 #### Getting Started
 
 - [Installation](./getting-started.md)
-- [Tutorial](./guides/tutorial.md)
-- [Basic Configuration](./guides/configuration.md)
+- [Tutorial](./getting-started/tutorial.md)
+- [Basic Configuration](./api-reference/configuration.md)
 
 #### Core Features
 
-- [Server-Side Rendering](./guides/react-server-rendering.md)
-- [Component Registration](./guides/render-functions-and-railscontext.md)
-- [Props and RailsContext](./guides/render-functions-and-railscontext.md)
+- [Server-Side Rendering](./core-concepts/react-server-rendering.md)
+- [Component Registration](./core-concepts/render-functions-and-railscontext.md)
+- [Props and RailsContext](./core-concepts/render-functions-and-railscontext.md)
 
 #### State Management
 
-- [Redux Integration](./javascript/react-and-redux.md)
-- [Context API](./guides/render-functions-and-railscontext.md)
+- [Redux Integration](./building-features/react-and-redux.md)
+- [Context API](./core-concepts/render-functions-and-railscontext.md)
 
 #### Routing
 
-- [React Router Setup](./javascript/react-router.md)
-- [Server-Side Routing](./guides/react-server-rendering.md)
+- [React Router Setup](./building-features/react-router.md)
+- [Server-Side Routing](./core-concepts/react-server-rendering.md)
 
 #### Advanced Topics
 
-- [Webpack Configuration](./guides/webpack-configuration.md)
-- [Code Splitting](./javascript/code-splitting.md)
-- [Performance Optimization](./guides/webpack-configuration.md)
+- [Webpack Configuration](./core-concepts/webpack-configuration.md)
+- [Code Splitting](./building-features/code-splitting.md)
+- [Performance Optimization](./core-concepts/webpack-configuration.md)
 
 #### Development
 
-- [Hot Module Replacement](./guides/hmr-and-hot-reloading-with-the-webpack-dev-server.md)
-- [Testing Components](./guides/rspec-configuration.md)
-- [Debugging](./javascript/troubleshooting-build-errors.md)
+- [Hot Module Replacement](./building-features/hmr-and-hot-reloading-with-the-webpack-dev-server.md)
+- [Testing Components](./building-features/rspec-configuration.md)
+- [Debugging](./deployment/troubleshooting-build-errors.md)
 
 #### Deployment
 
-- [Production Setup](./guides/deployment.md)
-- [Heroku Deployment](./guides/deployment.md)
-- [Docker Setup](./guides/deployment.md)
+- [Production Setup](./deployment/deployment.md)
+- [Heroku Deployment](./deployment/deployment.md)
+- [Docker Setup](./deployment/deployment.md)
 
 ### Migration Guides
 
-- [Upgrading React on Rails](./guides/upgrading-react-on-rails.md)
-- [From react-rails gem](./additional-details/migrating-from-react-rails.md)
+- [Upgrading React on Rails](./upgrading/upgrading-react-on-rails.md)
+- [From react-rails gem](./migrating/migrating-from-react-rails.md)
 
 ### Troubleshooting
 
-- [Common Issues](./troubleshooting/README.md)
-- [Error Messages](./javascript/troubleshooting-build-errors.md)
-- [Performance Issues](./javascript/troubleshooting-build-errors.md)
+- [Common Issues](./deployment/troubleshooting.md)
+- [Error Messages](./deployment/troubleshooting-build-errors.md)
+- [Performance Issues](./deployment/troubleshooting-build-errors.md)
 
 ### Contributing
 

docs/additional-details/manual-installation-overview.md → docs/advanced-topics/manual-installation-overview.md

@@ -13,7 +13,7 @@ The only requirements within this directory for basic React on Rails integration
 1. Your Webpack configuration files:
    1. Create outputs in a directory like `/public/webpack`, which is customizable in your `config/initializers/react_on_rails.rb`.
    1. Provide server rendering if you wish to use that feature.
-1. Your JavaScript code "registers" any components and stores per the ReactOnRails APIs of ReactOnRails.register(components) and ReactOnRails.registerStore(stores). See [our JavaScript API docs](../api/javascript-api.md) and the [React on Rails source](https://github.com/shakacode/react_on_rails/tree/master/packages/react-on-rails/src/ReactOnRails.client.ts).
+1. Your JavaScript code "registers" any components and stores per the ReactOnRails APIs of ReactOnRails.register(components) and ReactOnRails.registerStore(stores). See [our JavaScript API docs](../api-reference/javascript-api.md) and the [React on Rails source](https://github.com/shakacode/react_on_rails/tree/master/packages/react-on-rails/src/ReactOnRails.client.ts).
 1. Set your registration file as an "entry" point in your Webpack configs.
 1. Configure scripts in `client/package.json` as shown in the example apps. These are used for building your Webpack assets. Also do this for your top-level `package.json`.
 

docs/api-reference/README.md

@@ -0,0 +1,7 @@
+# API Reference
+
+Complete API documentation for React on Rails.
+
+- [View Helpers API](../api-reference/view-helpers-api.md)
+- [Redux Store API](../api-reference/redux-store-api.md)
+- [JavaScript API](../api-reference/javascript-api.md)

docs/additional-details/generator-details.md → docs/api-reference/generator-details.md

@@ -37,7 +37,7 @@ Then you may run
     `rails s`
 ```
 
-Another good option is to create a simple test app per the [Tutorial](../guides/tutorial.md).
+Another good option is to create a simple test app per the [Tutorial](../getting-started/tutorial.md).
 
 # Understanding the Organization of the Generated Client Code
 

docs/api/view-helpers-api.md → docs/api-reference/view-helpers-api.md

@@ -25,7 +25,7 @@ Uncommonly used options:
 ```
 
 - **component_name:** Can be a React component, created using a React Function Component, an ES6 class or a Render-Function that returns a React component (or, only on the server side, an object with shape `{ redirectLocation, error, renderedHtml }`), or a "renderer function" that manually renders a React component to the dom (client side only). Note, a "renderer function" is a special type of "Render-Function." A "renderer function" takes a 3rd param of a DOM ID.
-  All options except `props, id, html_options` will inherit from your `react_on_rails.rb` initializer, as described [here](../guides/configuration.md).
+  All options except `props, id, html_options` will inherit from your `react_on_rails.rb` initializer, as described [here](../api-reference/configuration.md).
 - **general options:**
   - **props:** Ruby Hash which contains the properties to pass to the React object, or a JSON string. If you pass a string, we'll escape it for you.
   - **prerender:** enable server-side rendering of a component. Set to false when debugging!
@@ -105,7 +105,7 @@ You can call `rails_context` or `rails_context(server_side: true|false)` from yo
 
 A "renderer function" is a Render-Function that accepts three arguments (rather than 2): `(props, railsContext, domNodeId) => { ... }`. Instead of returning a React component, a renderer is responsible for installing a callback that will call `ReactDOM.render` (in React 16+, `ReactDOM.hydrate`) to render a React component into the DOM. The "renderer function" is called at the same time the document ready event would instantiate the React components into the DOM.
 
-Why would you want to call `ReactDOM.hydrate` yourself? One possible use case is [code splitting](../javascript/code-splitting.md). In a nutshell, you don't want to load the React component on the DOM node yet. So you want to install some handler that will call `ReactDOM.hydrate` at a later time. In the case of code splitting with server rendering, the server rendered code has any async code loaded and used to server render. Thus, the client code must also fully load any asynch code before server rendering. Otherwise, the client code would first render partially, not matching the server rendering, and then a second later, the full code would render, resulting in an unpleasant flashing on the screen.
+Why would you want to call `ReactDOM.hydrate` yourself? One possible use case is [code splitting](../building-features/code-splitting.md). In a nutshell, you don't want to load the React component on the DOM node yet. So you want to install some handler that will call `ReactDOM.hydrate` at a later time. In the case of code splitting with server rendering, the server rendered code has any async code loaded and used to server render. Thus, the client code must also fully load any asynch code before server rendering. Otherwise, the client code would first render partially, not matching the server rendering, and then a second later, the full code would render, resulting in an unpleasant flashing on the screen.
 
 Renderer functions are not meant to be used on the server since there's no DOM on the server. Instead, use a Render-Function. Attempting to server render with a renderer function will throw an error.
 
@@ -115,9 +115,9 @@ Renderer functions are not meant to be used on the server since there's no DOM o
 
 [React Router](https://reactrouter.com/) is supported, including server-side rendering! See:
 
-1. [React on Rails docs for React Router](../javascript/react-router.md)
+1. [React on Rails docs for React Router](../building-features/react-router.md)
 2. Examples in [spec/dummy/app/views/react_router](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/app/views/react_router) and follow to the JavaScript code in the [spec/dummy/client/app/startup/RouterApp.server.jsx](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/client/app/startup/RouterApp.server.jsx).
-3. [Code Splitting docs](../javascript/code-splitting.md) for information about how to set up code splitting for server rendered routes.
+3. [Code Splitting docs](../building-features/code-splitting.md) for information about how to set up code splitting for server rendered routes.
 
 ---
 

docs/javascript/code-splitting.md → docs/building-features/code-splitting.md

@@ -71,7 +71,7 @@ ReactOnRails.register({
 });
 ```
 
-Note that you should not register a renderer on the server, since there won't be a domNodeId when we're server rendering. Note that the `RouterApp` imported by `serverRegistration.js` is from a different file. For an example of how to set up an app for server rendering, see the [react router docs](./react-router.md).
+Note that you should not register a renderer on the server, since there won't be a domNodeId when we're server rendering. Note that the `RouterApp` imported by `serverRegistration.js` is from a different file. For an example of how to set up an app for server rendering, see the [react router docs](../building-features/react-router.md).
 
 #### RouterAppRenderer.jsx
 

docs/guides/how-to-conditionally-server-render-based-on-device-type.md → docs/building-features/how-to-conditionally-server-render-based-on-device-type.md

@@ -37,4 +37,4 @@ end
 
 Note, full details of the React on Rails configuration are [here in docs/basics/configuration.md](https://shakacode.com/react-on-rails/docs/guides/configuration/).
 
-See the doc file [render-functions-and-railscontext.md](./render-functions-and-railscontext.md#rails-context) for how your client-side code uses the device information
+See the doc file [render-functions-and-railscontext.md](../core-concepts/render-functions-and-railscontext.md#rails-context) for how your client-side code uses the device information