Skip to content

Commit 2b09b6a

Browse files
justin808claude
justin808
and
claude
authored
Add docs/sidebars.ts for source-owned TOC navigation (#2886)
## Summary - Adds `docs/sidebars.ts` — the Docusaurus sidebar definition — so docs authors own both content and navigation in one repo - Includes all 12 docs that were missing from the site's sidebar navigation: - `building-features/debugging` - `building-features/node-renderer/container-deployment` - `core-concepts/execjs-limitations` - `core-concepts/performance-benchmarks` - `getting-started/comparing-react-on-rails-to-alternatives` - `getting-started/nextjs-with-separate-rails-backend` - `migrating/rsc-flight-payload` - `pro/fragment-caching` - `pro/node-renderer` - `pro/streaming-ssr` - `pro/react-server-components/index` - `pro/react-server-components/upgrading-existing-pro-app` - The Historical Reference/Archive section is excluded — the site repo injects it during build Companion PR: shakacode/reactonrails.com#68 ## How it works 1. Site repo's `sync-docs.mjs` copies `docs/sidebars.ts` alongside the docs content 2. Site repo's `prepare-docs.mjs` reads it, injects the archive section, writes final `sidebars.ts` 3. When docs authors add a new file, they also add it to this sidebar in the same PR ## Test plan - [ ] Merge companion PR (reactonrails.com#68) first or in parallel - [ ] Run `npm run prepare && npm run build:full` on site repo to verify sidebar generates correctly - [ ] Verify all 12 newly-added docs appear in navigation 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Low risk documentation-only change; main risk is broken/incorrect doc navigation if sidebar ids/paths don’t match generated docs. > > **Overview** > Adds a first-class Docusaurus sidebar definition (`docs/sidebars.ts`) so this repo owns docs navigation/TOC structure, including explicit category organization and a documented exclusion list for legacy archive stubs. > > Updates the two “compare alternatives” docs to include Docusaurus frontmatter (`sidebar_label`/`description`) so they render with clearer titles in the new sidebar navigation. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 90c74d1. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY --> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Redesigned site sidebar with a clear top-level overview and organized sections (Getting Started, Core Concepts, Building Features, Configuration, API, RSC, Deployment, Upgrading/Migrating, Pro topics, Contributor Guide, Resources). * Added generated-index pages and nested categories for advanced topics (including Pro sections and migration guidance). * Updated sidebar labels for comparison pages to "Decision Guide" and "Feature Matrix & Benchmarks". <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent b19b5cd commit 2b09b6a

3 files changed

Lines changed: 261 additions & 0 deletions

File tree

‎docs/oss/getting-started/comparing-react-on-rails-to-alternatives.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
sidebar_label: 'Decision Guide'
3+
description: Narrative decision guide for choosing React on Rails vs Hotwire, Inertia, Next.js, Vite, and react-rails.
4+
---
5+
16
# Comparing React on Rails to Alternatives
27

38
If you are evaluating frontend approaches for a Rails application, the right choice depends on how much of your UI should live in React, how much Rails should keep rendering, and whether server rendering is a requirement from day one.

‎docs/oss/getting-started/comparison-with-alternatives.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
sidebar_label: 'Feature Matrix & Benchmarks'
3+
description: Side-by-side feature matrix and performance-oriented comparison of Rails + React integration options.
4+
---
5+
16
# Comparison with Alternatives
27

38
Choosing a React integration strategy for Rails? This guide compares React on Rails (OSS and Pro) with the main alternatives so you can make an informed decision.

‎docs/sidebars.ts‎

Lines changed: 251 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,251 @@
1+
import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
2+
3+
// Intentionally excluded from sidebar (legacy stubs that redirect to archive):
4+
// - building-features/hmr-and-hot-reloading-with-the-webpack-dev-server
5+
// - building-features/rails-webpacker-react-integration-options
6+
// - deployment/troubleshooting-when-using-webpacker
7+
// - misc/asset-pipeline
8+
9+
const sidebars: SidebarsConfig = {
10+
docsSidebar: [
11+
'introduction',
12+
{
13+
type: 'link',
14+
label: 'Documentation Guide',
15+
href: 'https://github.com/shakacode/react_on_rails/blob/main/docs/README.md',
16+
},
17+
{
18+
type: 'category',
19+
label: 'Choose a Path',
20+
collapsed: false,
21+
items: [
22+
{ type: 'ref', id: 'getting-started/create-react-on-rails-app' },
23+
{ type: 'ref', id: 'getting-started/installation-into-an-existing-rails-app' },
24+
{ type: 'ref', id: 'getting-started/oss-vs-pro' },
25+
{ type: 'ref', id: 'pro/upgrading-to-pro' },
26+
{ type: 'ref', id: 'migrating/migrating-from-react-rails' },
27+
],
28+
},
29+
{
30+
type: 'category',
31+
label: 'Getting Started',
32+
link: { type: 'generated-index', title: 'Getting Started' },
33+
collapsed: false,
34+
items: [
35+
'getting-started/quick-start',
36+
'getting-started/create-react-on-rails-app',
37+
'getting-started/tutorial',
38+
'getting-started/installation-into-an-existing-rails-app',
39+
'getting-started/project-structure',
40+
'getting-started/using-react-on-rails',
41+
'getting-started/oss-vs-pro',
42+
'getting-started/pro-quick-start',
43+
{
44+
type: 'category',
45+
label: 'Compare Alternatives',
46+
items: [
47+
'getting-started/comparison-with-alternatives',
48+
'getting-started/comparing-react-on-rails-to-alternatives',
49+
],
50+
},
51+
'getting-started/nextjs-with-separate-rails-backend',
52+
'getting-started/common-issues',
53+
],
54+
},
55+
{
56+
type: 'category',
57+
label: 'Core Concepts',
58+
link: { type: 'generated-index', title: 'Core Concepts' },
59+
items: [
60+
'core-concepts/how-react-on-rails-works',
61+
'core-concepts/client-vs-server-rendering',
62+
'core-concepts/react-server-rendering',
63+
'core-concepts/render-functions-and-railscontext',
64+
'core-concepts/render-functions',
65+
'core-concepts/auto-bundling-file-system-based-automated-bundle-generation',
66+
'core-concepts/webpack-configuration',
67+
'core-concepts/execjs-limitations',
68+
'core-concepts/performance-benchmarks',
69+
{ type: 'ref', id: 'pro/react-on-rails-pro' },
70+
],
71+
},
72+
{
73+
type: 'category',
74+
label: 'Building Features',
75+
link: { type: 'generated-index', title: 'Building Features' },
76+
items: [
77+
'building-features/react-and-redux',
78+
'building-features/react-router',
79+
'building-features/tanstack-router',
80+
'building-features/code-splitting',
81+
'building-features/i18n',
82+
'building-features/images',
83+
'building-features/react-helmet',
84+
'building-features/react-19-native-metadata',
85+
'building-features/streaming-server-rendering',
86+
'building-features/how-to-conditionally-server-render-based-on-device-type',
87+
'building-features/how-to-use-different-files-for-client-and-server-rendering',
88+
'building-features/caching',
89+
'building-features/bundle-caching',
90+
'building-features/process-managers',
91+
'building-features/dev-server-and-testing',
92+
'building-features/testing-configuration',
93+
'building-features/extensible-precompile-pattern',
94+
'building-features/rails-engine-integration',
95+
'building-features/debugging',
96+
'building-features/turbolinks',
97+
{
98+
type: 'category',
99+
label: 'Node Renderer (Pro)',
100+
items: [
101+
'building-features/node-renderer/basics',
102+
'building-features/node-renderer/js-configuration',
103+
'building-features/node-renderer/container-deployment',
104+
'building-features/node-renderer/debugging',
105+
'building-features/node-renderer/error-reporting-and-tracing',
106+
'building-features/node-renderer/heroku',
107+
'building-features/node-renderer/troubleshooting',
108+
],
109+
},
110+
],
111+
},
112+
{
113+
type: 'category',
114+
label: 'Configuration',
115+
items: [
116+
'configuration/README',
117+
'configuration/configuration-pro',
118+
'configuration/configuration-deprecated',
119+
],
120+
},
121+
{
122+
type: 'category',
123+
label: 'API Reference',
124+
items: [
125+
'api-reference/view-helpers-api',
126+
'api-reference/javascript-api',
127+
'api-reference/redux-store-api',
128+
'api-reference/ruby-api-pro',
129+
'api-reference/generator-details',
130+
'api-reference/rails-view-rendering-from-inline-javascript',
131+
],
132+
},
133+
{
134+
type: 'category',
135+
label: 'React Server Components',
136+
link: { type: 'doc', id: 'pro/react-server-components/index' },
137+
items: [
138+
'pro/react-server-components/purpose-and-benefits',
139+
'pro/react-server-components/how-react-server-components-work',
140+
'pro/react-server-components/rendering-flow',
141+
'pro/react-server-components/tutorial',
142+
'pro/react-server-components/server-side-rendering',
143+
'pro/react-server-components/add-streaming-and-interactivity',
144+
'pro/react-server-components/create-without-ssr',
145+
'pro/react-server-components/inside-client-components',
146+
'pro/react-server-components/selective-hydration-in-streamed-components',
147+
'pro/react-server-components/flight-protocol-syntax',
148+
'pro/react-server-components/upgrading-existing-pro-app',
149+
'pro/react-server-components/glossary',
150+
{
151+
type: 'category',
152+
label: 'Migrating to RSC',
153+
items: [
154+
'migrating/migrating-to-rsc',
155+
'migrating/rsc-preparing-app',
156+
'migrating/rsc-component-patterns',
157+
'migrating/rsc-context-and-state',
158+
'migrating/rsc-data-fetching',
159+
'migrating/rsc-third-party-libs',
160+
'migrating/rsc-troubleshooting',
161+
'migrating/rsc-flight-payload',
162+
],
163+
},
164+
],
165+
},
166+
{
167+
type: 'category',
168+
label: 'Deployment',
169+
items: [
170+
'deployment/README',
171+
'deployment/docker-deployment',
172+
'deployment/heroku-deployment',
173+
'deployment/server-rendering-tips',
174+
'deployment/troubleshooting',
175+
'deployment/troubleshooting-build-errors',
176+
'deployment/troubleshooting-when-using-shakapacker',
177+
],
178+
},
179+
{
180+
type: 'category',
181+
label: 'Upgrading',
182+
items: [
183+
'upgrading/upgrading-react-on-rails',
184+
{
185+
type: 'link',
186+
label: 'Full Changelog',
187+
href: 'https://github.com/shakacode/react_on_rails/blob/main/CHANGELOG.md',
188+
},
189+
{
190+
type: 'category',
191+
label: 'Release Notes',
192+
items: [
193+
'upgrading/release-notes/16.4.0',
194+
'upgrading/release-notes/16.3.0',
195+
'upgrading/release-notes/16.2.0',
196+
'upgrading/release-notes/16.1.0',
197+
'upgrading/release-notes/16.0.0',
198+
'upgrading/release-notes/15.0.0',
199+
],
200+
},
201+
'pro/updating',
202+
'pro/major-performance-breakthroughs-upgrade-guide',
203+
{
204+
type: 'category',
205+
label: 'Pro Release Notes',
206+
items: ['pro/release-notes/v4-react-server-components', 'pro/release-notes/4.0'],
207+
},
208+
],
209+
},
210+
{
211+
type: 'category',
212+
label: 'Migrating',
213+
items: [
214+
'migrating/migrating-from-react-rails',
215+
'migrating/migrating-from-vite-rails',
216+
'migrating/migrating-from-webpack-to-rspack',
217+
'migrating/babel-to-swc-migration',
218+
'migrating/convert-rails-5-api-only-app',
219+
'migrating/angular-js-integration-migration',
220+
],
221+
},
222+
{
223+
type: 'category',
224+
label: 'React on Rails Pro',
225+
link: { type: 'doc', id: 'pro/react-on-rails-pro' },
226+
items: [
227+
'pro/home-pro',
228+
'pro/installation',
229+
'pro/upgrading-to-pro',
230+
'pro/streaming-ssr',
231+
'pro/node-renderer',
232+
'pro/fragment-caching',
233+
'pro/js-memory-leaks',
234+
'pro/profiling-server-side-rendering-code',
235+
'pro/troubleshooting',
236+
],
237+
},
238+
{
239+
type: 'category',
240+
label: 'Contributor Guide',
241+
items: ['misc/doctrine', 'misc/style', 'misc/credits', 'misc/updating-dependencies'],
242+
},
243+
{
244+
type: 'category',
245+
label: 'Resources',
246+
items: ['misc/articles', 'misc/tips'],
247+
},
248+
],
249+
};
250+
251+
export default sidebars;

0 commit comments

Comments
 (0)