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>

Author: ihabadham

docs/building-features/turbolinks.md

@@ -6,7 +6,7 @@
 - See [PR 1374](https://github.com/shakacode/react_on_rails/pull/1374).
 - Ability to use with [Turbo (`@hotwired/turbo`)](https://turbo.hotwired.dev/), as Turbolinks becomes obsolete.
 
-# Using Turbo
+## Using Turbo
 
 To configure Turbo the following option can be set:
 `ReactOnRails.setOptions({ turbo: true })`
@@ -15,36 +15,36 @@ Turbo is not auto-detected like older Turbolinks.
 
 _TODO: Walk through code changes in PR 1620._
 
-# Legacy Turbolinks
+## Legacy Turbolinks Support
 
-_The following docs may be outdated. We recommend updating to the latest Turbo or removing old Turbolinks._
+_The following documentation covers older Turbolinks versions (2.x and 5.x). While still supported by React on Rails, we recommend migrating to Turbo when possible._
 
+React on Rails currently supports:
+
+- **Turbolinks 5.x** (e.g., 5.0.0+) - Auto-detected
+- **Turbolinks 2.x** (Classic) - Auto-detected
 - See [Turbolinks on Github](https://github.com/rails/turbolinks)
-- React on Rails currently supports 2.5.x of Turbolinks and 5.0.0 of Turbolinks 5.
-- You may include Turbolinks either via yarn (recommended) or via the gem.
 
-## Why Turbolinks?
+You may include Turbolinks either via yarn (recommended) or via the gem.
+
+### Why Turbolinks?
 
 As you switch between Rails HTML controller requests, you will only load the HTML and you will not reload JavaScript and stylesheets.
 This definitely can make an app perform better, even if the JavaScript and stylesheets are cached by the browser, as they will still require parsing.
 
-## Requirements for Using Turbolinks
+### Requirements for Using Turbolinks
 
 1. Either **avoid using [React Router](https://reactrouter.com/)** or be prepared to deal with any conflicts between it and Turbolinks.
 2. **Use one JS and one CSS file** throughout your app. Otherwise, you will have to figure out how best to handle multiple JS and CSS files throughout the app given Turbolinks.
 
-## Why Not Turbolinks
+### Why Not Turbolinks
 
 1. [React Router](https://reactrouter.com/) handles the back and forward buttons, as does Turbolinks. You _might_ be able to make this work. _Please share your findings._
 1. You want to do code splitting to minimize the JavaScript loaded.
 
-## More Information
+### Installation
 
-- CSRF tokens need thorough checking with Turbolinks5. Turbolinks5 changes the head element by JavaScript (not only body) on page changes with the correct csrf meta tag. But if the JS code parsed this from head when several windows were opened, then our specs didn't all pass. I didn't examine the details, it may be caused by app code, not library code. Anyway, it may need additional checking because there is a CSRF helper in ReactOnRails and it needs to work with Turbolinks5.
-- Turbolinks5 sends requests without the `Accept: */*` in the header, only exactly like `Accept: text/html` which makes Rails behave a bit specifically compared to normal and mime-parsing, which is skipped when Rails sees `*/*`. For more details on the special handling of `*/*` you can read [Mime Type Resolution in Rails](http://blog.bigbinary.com/2010/11/23/mime-type-resolution-in-rails.html).
-- If you're using multiple Webpack bundles, make sure that there are no name conflicts between JS objects or Redux store paths.
-
-### Install Checklist
+#### Install Checklist
 
 1. Include turbolinks via yarn as shown in the [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial/blob/8a6c8aa2e3b7ae5b08b0a9744fb3a63a2fe0f002/client/webpack.client.base.config.js#L22) or include the gem "turbolinks".
 1. Included the proper "track" tags when you include the javascript and stylesheet:
@@ -61,13 +61,7 @@ NOTE: for Turbolinks 2.x, use `'data-turbolinks-track' => true`
    //= require turbolinks
    ```
 
-## Turbolinks 5
-
-Turbolinks 5 is now supported. React on Rails will automatically detect which version of Turbolinks you are using and use the correct event handlers.
-
-For more information on Turbolinks 5: [https://github.com/turbolinks/turbolinks](https://github.com/turbolinks/turbolinks)
-
-## Turbolinks from NPM
+#### Turbolinks from NPM
 
 See the [instructions on installing from NPM](https://github.com/turbolinks/turbolinks#installation-using-npm).
 
@@ -76,7 +70,7 @@ import Turbolinks from 'turbolinks';
 Turbolinks.start();
 ```
 
-### Async script loading
+##### Async script loading
 
 Async script loading can be done like this (starting with Shakapacker 8.2):
 
@@ -105,7 +99,21 @@ React on Rails 15 fixes both issues, so if you still have the listener it can be
 > [!WARNING]
 > Do not use `immediate_hydration: false` (React on Rails Pro licensed feature) with Turbolinks if you have async scripts.
 
-## Troubleshooting
+### Turbolinks 5 Specific Information
+
+React on Rails will automatically detect which version of Turbolinks you are using (2.x or 5.x) and use the correct event handlers.
+
+For more information on Turbolinks 5: [https://github.com/turbolinks/turbolinks](https://github.com/turbolinks/turbolinks)
+
+### Technical Details and Troubleshooting
+
+#### CSRF and MIME Type Handling
+
+- **CSRF tokens**: Turbolinks 5 changes the head element by JavaScript (not only body) on page changes with the correct csrf meta tag. Be thorough checking CSRF tokens, especially when multiple windows are opened, as the CSRF helper in ReactOnRails needs to work with Turbolinks5.
+- **MIME type handling**: Turbolinks 5 sends requests with `Accept: text/html` only (not `Accept: */*`), which makes Rails behave differently compared to normal requests. For more details on the special handling of `*/*` you can read [Mime Type Resolution in Rails](http://blog.bigbinary.com/2010/11/23/mime-type-resolution-in-rails.html).
+- **Multiple Webpack bundles**: If you're using multiple Webpack bundles, make sure that there are no name conflicts between JS objects or Redux store paths.
+
+#### Debugging Turbolinks Events
 
 To turn on tracing of Turbolinks events, put this in your registration file, where you register your components.