feat(site): remove style from urls (#378)

Author: decepulis

site/CLAUDE.md

@@ -145,13 +145,15 @@ Documentation is generated for **multiple framework and style combinations** fro
 
 **URL pattern:**
 ```
-/docs/framework/{framework}/style/{style}/{...slug}/
+/docs/framework/{framework}/{...slug}/
 ```
 
+**Style handling:** Style is a **client-side preference** stored in localStorage per-framework (`vjs_docs_style_html`, `vjs_docs_style_react`). The `StyleInit.astro` component reads localStorage before paint and sets `html[data-style]`. CSS rules control content visibility via `[data-for-style]` attributes on `<StyleCase>` wrapped content.
+
 **Example:**
 - `src/content/docs/how-to/installation.mdx` generates:
-  - `/docs/framework/html/style/css/how-to/installation/`
-  - `/docs/framework/react/style/css/how-to/installation/`
+  - `/docs/framework/html/how-to/installation/`
+  - `/docs/framework/react/how-to/installation/`
 
 ### Content Restriction Mechanisms
 
@@ -171,21 +173,25 @@ Use `<FrameworkCase>` or `<StyleCase>` components to show framework/style-specif
 
 **2. In sidebar config (`src/docs.config.ts`):**
 
+Restrict entire guides to specific frameworks:
+
 ```ts
 const sidebar: Sidebar = [
   {
     sidebarLabel: 'Getting started',
     contents: [
-      { slug: 'how-to/installation' }, // Available to all
+      { slug: 'how-to/installation' }, // Available to all frameworks
       {
         slug: 'how-to/react-hooks',
-        frameworks: ['react'] // Only for React
+        frameworks: ['react'] // Only visible when viewing React docs
       },
     ],
   },
 ];
 ```
 
+**Note:** Style restrictions on sidebar items are no longer supported. All docs are visible to all styles; use `<StyleCase>` within docs to show style-specific content.
+
 ### Sidebar Configuration
 
 **Structure** (`src/docs.config.ts`):
@@ -195,7 +201,6 @@ const sidebar: Sidebar = [
   - `slug`: Path relative to `src/content/docs/` (without `.mdx`)
   - `sidebarLabel` (optional): Override display name
   - `frameworks` (optional): Restrict to specific frameworks
-  - `styles` (optional): Restrict to specific styles
   - `devOnly` (optional): Show only in development mode
 
 **Example:**
@@ -216,11 +221,10 @@ export const sidebar: Sidebar = [
 ### Key Utility Functions (`src/utils/docs/`)
 
 **`sidebar.ts`** — Sidebar filtering and navigation:
-- `filterSidebar()`: Filter sidebar by framework/style, remove empty sections
-- `findFirstGuide()`: Get first available guide for framework/style combo
+- `filterSidebar()`: Filter sidebar by framework, remove empty sections
+- `findFirstGuide()`: Get first available guide for framework
 - `findGuideBySlug()`: Search sidebar recursively for a guide
 - `getAdjacentGuides()`: Get prev/next guides for navigation
-- `getValidStylesForGuide()`: Determine valid styles for a guide
 - `getSectionsForGuide()`: Get breadcrumb trail to a guide
 
 **`routing.ts`** — URL building and redirect logic:
@@ -234,19 +238,19 @@ export const sidebar: Sidebar = [
 
 **Nested index pages** handle redirects at each level:
 ```
-/docs/                                              → redirect to first guide
-/docs/framework/                                    → redirect to first guide
-/docs/framework/{framework}/                        → redirect to first guide
-/docs/framework/{framework}/style/                  → redirect to first guide
-/docs/framework/{framework}/style/{style}/          → redirect to first guide
-/docs/framework/{framework}/style/{style}/{...slug} → render guide
+/docs/                             → redirect to first guide
+/docs/framework/                   → redirect to first guide
+/docs/framework/{framework}/       → redirect to first guide
+/docs/framework/{framework}/{slug} → render guide
 ```
 
 Each index page uses `resolveIndexRedirect()` to determine where to redirect based on:
-1. URL params (framework, style)
-2. User preferences (from localStorage via Nanostores)
+1. URL params (framework)
+2. User preferences (framework from cookies)
 3. Defaults (when invalid or missing)
 
+**Style is not part of the URL.** Style preference is stored per-framework in localStorage and applied client-side via CSS.
+
 ## Content Collections
 
 Defined in `src/content.config.ts` using Astro's Content Collections API.
@@ -453,18 +457,13 @@ Sidebar filtering is recursive because sections can contain guides or nested sec
 
 ```ts
 export function filterSidebar(
-  sidebar: Sidebar,
   framework: SupportedFramework,
-  style: AnySupportedStyle,
+  sidebarToFilter?: Sidebar,
 ): Sidebar {
-  return sidebar
-    .map((section) => ({
-      ...section,
-      contents: section.contents.filter((item) =>
-        isItemVisible(item, framework, style)
-      ),
-    }))
-    .filter((section) => section.contents.length > 0);
+  const root = sidebarToFilter ?? sidebar;
+  return root
+    .map((item) => filterItem(item, framework))
+    .filter(isNotFalsy);
 }
 ```
 

site/astro.config.mjs

@@ -74,9 +74,10 @@ export default defineConfig({
   vite: {
     plugins: [tailwindcss()],
     optimizeDeps: {
-      exclude: ['@vjs/react'],
+      exclude: ['@videojs/react-preview'],
     },
     resolve: {
+      dedupe: ['react', 'react-dom'],
       alias: {
         '@': new URL('./src', import.meta.url).pathname,
       },

site/src/components/docs/DocsLink.astro

@@ -1,7 +1,6 @@
 ---
-
 import type { HTMLAttributes } from 'astro/types';
-import { isValidFramework, isValidStyleForFramework } from '@/types/docs';
+import { isValidFramework } from '@/types/docs';
 import { resolveDocsLinkUrl } from '@/utils/docs/routing';
 import A from '../typography/A.astro';
 
@@ -10,18 +9,14 @@ interface Props extends Omit<HTMLAttributes<'a'>, 'href'> {
 }
 const { slug } = Astro.props;
 
-const { framework: paramFramework, style: paramStyle } = Astro.params;
+const { framework: paramFramework } = Astro.params;
 if (!paramFramework || !isValidFramework(paramFramework)) {
   throw new Error(`Invalid or missing framework param "${paramFramework ?? 'undefined'}".`);
 }
-if (!paramStyle || !isValidStyleForFramework(paramFramework, paramStyle)) {
-  throw new Error(`Invalid style param "${paramStyle}" for framework "${paramFramework}".`);
-}
 
 const { url: href } = resolveDocsLinkUrl({
   targetSlug: slug,
   contextFramework: paramFramework,
-  contextStyle: paramStyle,
 });
 ---
 

site/src/components/docs/DocsNavigation.astro

@@ -1,28 +1,26 @@
 ---
-
 import { ChevronDown } from 'lucide-react';
-import type { Guide, SupportedFramework, SupportedStyle } from '@/types/docs';
+import type { Guide, SupportedFramework } from '@/types/docs';
 
-type Props<F extends SupportedFramework = SupportedFramework> = {
+type Props = {
   prev: Guide | null;
   next: Guide | null;
-  framework: F;
-  style: SupportedStyle<F>;
+  framework: SupportedFramework;
   docTitles: Map<string, string>;
 };
 
-const { prev, next, framework, style, docTitles } = Astro.props;
+const { prev, next, framework, docTitles } = Astro.props;
 
-function getGuideUrl<F extends SupportedFramework>(framework: F, style: SupportedStyle<F>, slug: string): string {
-  return `/docs/framework/${framework}/style/${style}/${slug}`;
+function getGuideUrl(framework: SupportedFramework, slug: string): string {
+  return `/docs/framework/${framework}/${slug}`;
 }
 ---
 
 <nav class="w-full max-w-3xl mx-auto grid grid-cols-1 md:grid-cols-2 gap-5">
   {
     prev ? (
       <a
-        href={getGuideUrl(framework, style, prev.slug)}
+        href={getGuideUrl(framework, prev.slug)}
         class="grid items-center gap-x-2 p-4 border border-light-40 dark:border-dark-80 rounded-lg intent:border-dark-40 dark:intent:border-dark-40"
         style="grid-template-areas: 'empty direction' 'icon title'; grid-template-columns: auto minmax(0,1fr); grid-template-rows: auto minmax(0,1fr);"
       >
@@ -43,7 +41,7 @@ function getGuideUrl<F extends SupportedFramework>(framework: F, style: Supporte
   {
     next ? (
       <a
-        href={getGuideUrl(framework, style, next.slug)}
+        href={getGuideUrl(framework, next.slug)}
         class="grid items-center gap-x-2 p-4 border border-light-40 dark:border-dark-80 rounded-lg intent:border-dark-40 text-right dark:intent:border-dark-40"
         style="grid-template-areas: 'direction empty' 'title icon';grid-template-columns: minmax(0,1fr) auto; grid-template-rows: auto minmax(0,1fr);"
       >

site/src/components/docs/DocsSidebar.astro

@@ -1,31 +1,25 @@
 ---
-
 import clsx from 'clsx';
 
 import { PreferenceUpdater } from '@/components/docs/PreferenceUpdater';
 import SidebarItem from '@/components/docs/SidebarItem.astro';
-import type { SupportedFramework, SupportedStyle } from '@/types/docs';
+import type { SupportedFramework } from '@/types/docs';
 import { filterSidebar } from '@/utils/docs/sidebar';
 
-type Props<F extends SupportedFramework = SupportedFramework> = {
-  framework: F;
-  style: SupportedStyle<F>;
+type Props = {
+  framework: SupportedFramework;
   docTitles: Map<string, string>;
   class?: string;
 };
 
-const { framework, style, docTitles, class: className } = Astro.props;
-const filteredSidebar = filterSidebar(framework, style);
+const { framework, docTitles, class: className } = Astro.props;
+const filteredSidebar = filterSidebar(framework);
 ---
 
 <div class={clsx('bg-light-80 dark:bg-dark-100', className)}>
   <slot />
-  <PreferenceUpdater client:idle currentFramework={framework} currentStyle={style} />
+  <PreferenceUpdater client:idle currentFramework={framework} />
   <nav class="p-6">
-    {
-      filteredSidebar.map((item) => (
-        <SidebarItem item={item} framework={framework} style={style} docTitles={docTitles} />
-      ))
-    }
+    {filteredSidebar.map((item) => <SidebarItem item={item} framework={framework} docTitles={docTitles} />)}
   </nav>
 </div>

site/src/components/docs/PreferenceSync.tsx

@@ -1,39 +1,37 @@
 import { useStore } from '@nanostores/react';
 import { useEffect } from 'react';
-import { currentFramework, currentStyle } from '@/stores/preferences';
-import type { SupportedFramework, SupportedStyle } from '@/types/docs';
-import { getPreferenceClient, setPreferenceClient } from '@/utils/docs/preferences';
+import { currentFramework } from '@/stores/preferences';
+import type { SupportedFramework } from '@/types/docs';
+import { getFrameworkPreferenceClient, setFrameworkPreferenceClient } from '@/utils/docs/preferences';
 
 /**
- * PreferenceSync keeps the nanostore in sync with cookies.
+ * PreferenceSync keeps the framework nanostore in sync with cookies.
  *
  * On mount: Reads cookies → initializes store
  * On store change: Writes to cookies
  *
- * This component should be loaded with client:load in the base layout
+ * Style preferences are handled via localStorage by StyleInit and PreferenceUpdater.
+ *
+ * This component should be loaded with client:idle in the base layout
  * to ensure preferences are available immediately.
  */
 export function PreferenceSync() {
   const framework = useStore(currentFramework);
-  const style = useStore(currentStyle);
 
   // Initialize store from cookies on mount
   useEffect(() => {
-    const prefs = getPreferenceClient();
-    if (prefs.framework) {
-      currentFramework.set(prefs.framework);
-    }
-    if (prefs.style) {
-      currentStyle.set(prefs.style);
+    const prefs = getFrameworkPreferenceClient();
+    if (prefs) {
+      currentFramework.set(prefs);
     }
   }, []);
 
   // Sync store changes to cookies
   useEffect(() => {
-    if (framework && style) {
-      setPreferenceClient(framework as SupportedFramework, style as SupportedStyle<typeof framework>);
+    if (framework) {
+      setFrameworkPreferenceClient(framework as SupportedFramework);
     }
-  }, [framework, style]);
+  }, [framework]);
 
   return null;
 }

site/src/components/docs/PreferenceUpdater.tsx

@@ -1,26 +1,28 @@
 import { useEffect } from 'react';
 import { currentFramework as frameworkStore, currentStyle as styleStore } from '@/stores/preferences';
-import type { SupportedFramework, SupportedStyle } from '@/types/docs';
+import { getDefaultStyle, type SupportedFramework } from '@/types/docs';
+import { getStylePreferenceClient } from '@/utils/docs/preferences';
 
-interface PreferenceUpdaterProps<F extends SupportedFramework = SupportedFramework> {
-  currentFramework: F;
-  currentStyle: SupportedStyle<F>;
+interface PreferenceUpdaterProps {
+  currentFramework: SupportedFramework;
 }
 
 /**
- * PreferenceUpdater component updates the preference nanostore based on URL params.
+ * PreferenceUpdater component updates the preference nanostore based on URL params and localStorage.
  * This component is loaded with client:idle directive on docs pages, making it non-blocking.
- * It updates the nanostore whenever framework or style from URL changes.
- * PreferenceSync handles persisting to cookies.
+ * It updates the framework store from URL params and style store from localStorage.
+ * PreferenceSync handles persisting framework to cookies.
  */
-export function PreferenceUpdater<F extends SupportedFramework = SupportedFramework>({
-  currentFramework,
-  currentStyle,
-}: PreferenceUpdaterProps<F>) {
+export function PreferenceUpdater({ currentFramework }: PreferenceUpdaterProps) {
   useEffect(() => {
+    // Update framework store from URL
     frameworkStore.set(currentFramework);
-    styleStore.set(currentStyle);
-  }, [currentFramework, currentStyle]);
+
+    // Read style from localStorage (StyleInit guarantees a valid value exists)
+    // Fallback to default if React hydrates before StyleInit completes
+    const style = getStylePreferenceClient(currentFramework) ?? getDefaultStyle(currentFramework);
+    styleStore.set(style);
+  }, [currentFramework]);
 
   return null;
 }