boltdocs 2.1.1 → 2.3.0

package/dist/{types-Cp21DHI6.d.ts → types-j7jvWsJj.d.ts}

@@ -22,10 +22,10 @@ interface BoltdocsFooterConfig {
  * Theme-specific configuration options governing the appearance and navigation of the site.
  */
 interface BoltdocsThemeConfig {
-    /** The global title of the documentation site */
-    title?: string;
-    /** The global description of the site (used for SEO) */
-    description?: string;
+    /** The global title of the documentation site (can be translated) */
+    title?: string | Record<string, string>;
+    /** The global description of the site (can be translated) */
+    description?: string | Record<string, string>;
     /** URL path to the site logo or an object for light/dark versions */
     logo?: string | {
         dark: string;
@@ -36,13 +36,15 @@ interface BoltdocsThemeConfig {
     };
     /** Items to display in the top navigation bar */
     navbar?: Array<{
-        /** Text to display */
-        label: string;
+        /** Text to display (can be a string or a map of translations) */
+        label: string | Record<string, string>;
         /** URL path or external link */
         href: string;
         /** Nested items for NavigationMenu */
         items?: Array<{
-            label: string;
+            /** Text to display (can be a string or a map of translations) */
+            label: string | Record<string, string>;
+            /** URL path or external link */
             href: string;
         }>;
     }>;
@@ -82,7 +84,8 @@ interface BoltdocsThemeConfig {
      */
     tabs?: Array<{
         id: string;
-        text: string;
+        /** Text to display (can be a string or a map of translations) */
+        text: string | Record<string, string>;
         icon?: string;
     }>;
     /**
@@ -120,23 +123,52 @@ type BoltdocsRobotsConfig = string | {
     /** Sitemaps to include in the robots.txt */
     sitemaps?: string[];
 };
+/**
+ * Configuration for a specific locale.
+ */
+interface BoltdocsLocaleConfig {
+    /** The display name of the locale */
+    label?: string;
+    /** The text direction (ltr or rtl) */
+    direction?: 'ltr' | 'rtl';
+    /** The HTML lang attribute value (e.g., 'en-US') */
+    htmlLang?: string;
+    /** The calendar system to use (e.g., 'gregory') */
+    calendar?: string;
+}
 /**
  * Configuration for internationalization (i18n).
  */
 interface BoltdocsI18nConfig {
     /** The default locale (e.g., 'en') */
     defaultLocale: string;
-    /** Available locales and their display names (e.g., { en: 'English', es: 'Español' }) */
+    /** Available locales and their basic display names (e.g., { en: 'English', es: 'Español' }) */
     locales: Record<string, string>;
+    /** Detailed configuration for each locale */
+    localeConfigs?: Record<string, BoltdocsLocaleConfig>;
+}
+/**
+ * Configuration for a specific documentation version.
+ */
+interface BoltdocsVersionConfig {
+    /** The display name of the version (e.g., 'v2.0') */
+    label: string;
+    /** The URL path prefix for the version (e.g., '2.0') */
+    path: string;
 }
 /**
  * Configuration for documentation versioning.
  */
 interface BoltdocsVersionsConfig {
-    /** The default version (e.g., 'v2') */
+    /** The default version path (e.g., 'v2') */
     defaultVersion: string;
-    /** Available versions and their display names (e.g., { v1: 'Version 1.x', v2: 'Version 2.x' }) */
-    versions: Record<string, string>;
+    /**
+     * Optional prefix for all version paths (e.g., 'v').
+     * If set to 'v', version '1.1' will be available at '/docs/v1.1'.
+     */
+    prefix?: string;
+    /** Available versions configurations */
+    versions: BoltdocsVersionConfig[];
 }
 /**
  * Defines a Boltdocs plugin that can extend the build process and client-side functionality.
@@ -193,8 +225,6 @@ interface BoltdocsConfig {
     robots?: BoltdocsRobotsConfig;
     /** Low-level Vite configuration overrides */
     vite?: vite.InlineConfig;
-    /** @deprecated Use theme instead */
-    themeConfig?: BoltdocsThemeConfig;
 }
 
 /**
@@ -317,9 +347,17 @@ interface SandboxEmbedOptions {
  */
 interface BoltdocsTab {
     id: string;
-    text: string;
+    /** Text to display (can be a string or a map of translations) */
+    text: string | Record<string, string>;
     icon?: string;
 }
+/**
+ * Props for the Sidebar component.
+ */
+interface SidebarProps {
+    routes: ComponentRoute[];
+    config: BoltdocsConfig;
+}
 /**
  * Props for the OnThisPage (TOC) component.
  */
@@ -333,6 +371,13 @@ interface OnThisPageProps {
     communityHelp?: string;
     filePath?: string;
 }
+/**
+ * Props for the Tabs component.
+ */
+interface TabsProps {
+    tabs: BoltdocsTab[];
+    routes: ComponentRoute[];
+}
 /**
  * Props for user-defined layout components (layout.tsx).
  */
@@ -343,7 +388,8 @@ interface LayoutProps {
  * Unified type for navbar links.
  */
 interface NavbarLink {
-    label: string;
+    /** Label to display (can be a string or a map of translations) */
+    label: string | Record<string, string>;
     href: string;
     active: boolean;
     /** Optional icon or string for external link indication */
@@ -352,4 +398,4 @@ interface NavbarLink {
     items?: NavbarLink[];
 }
 
-export type { BoltdocsConfig as B, ComponentRoute as C, LayoutProps as L, NavbarLink as N, OnThisPageProps as O, SandboxOptions as S, BoltdocsSocialLink as a, BoltdocsTab as b, CreateBoltdocsAppOptions as c, BoltdocsThemeConfig as d, SandboxEmbedOptions as e, SandboxFile as f, SandboxFiles as g };
+export type { BoltdocsConfig as B, ComponentRoute as C, LayoutProps as L, NavbarLink as N, OnThisPageProps as O, SandboxEmbedOptions as S, TabsProps as T, BoltdocsTab as a, CreateBoltdocsAppOptions as b, BoltdocsThemeConfig as c, SandboxFile as d, SandboxFiles as e, SandboxOptions as f, BoltdocsSocialLink as g, SidebarProps as h, SiteConfig as i };

package/dist/{use-routes-xLhumjbV.d.ts → use-routes-Cd806kGw.d.ts}

@@ -1,4 +1,4 @@
-import { C as ComponentRoute, B as BoltdocsConfig } from './types-Cp21DHI6.js';
+import { C as ComponentRoute, B as BoltdocsConfig } from './types-j7jvWsJj.js';
 
 /**
  * Hook to access the framework's routing state.

package/dist/{use-routes-8Iei6jTp.d.mts → use-routes-DDL0_jkQ.d.mts}

@@ -1,4 +1,4 @@
-import { C as ComponentRoute, B as BoltdocsConfig } from './types-Cp21DHI6.mjs';
+import { C as ComponentRoute, B as BoltdocsConfig } from './types-j7jvWsJj.mjs';
 
 /**
  * Hook to access the framework's routing state.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "boltdocs",
-  "version": "2.1.1",
+  "version": "2.3.0",
   "description": "A lightweight documentation generator for React projects.",
   "main": "dist/node/index.js",
   "module": "dist/node/index.mjs",
@@ -22,15 +22,40 @@
       "import": "./dist/client/index.mjs",
       "require": "./dist/client/index.js"
     },
+    "./hooks": {
+      "types": "./dist/hooks/index.d.ts",
+      "import": "./dist/hooks/index.mjs",
+      "require": "./dist/hooks/index.js"
+    },
+    "./primitives": {
+      "types": "./dist/primitives/index.d.ts",
+      "import": "./dist/primitives/index.mjs",
+      "require": "./dist/primitives/index.js"
+    },
+    "./base-ui": {
+      "types": "./dist/base-ui/index.d.ts",
+      "import": "./dist/base-ui/index.mjs",
+      "require": "./dist/base-ui/index.js"
+    },
+    "./mdx": {
+      "types": "./dist/mdx/index.d.ts",
+      "import": "./dist/mdx/index.mjs",
+      "require": "./dist/mdx/index.js"
+    },
+    "./integrations": {
+      "types": "./dist/integrations/index.d.ts",
+      "import": "./dist/integrations/index.mjs",
+      "require": "./dist/integrations/index.js"
+    },
     "./client/hooks": {
-      "types": "./dist/client/hooks/index.d.ts",
-      "import": "./dist/client/hooks/index.mjs",
-      "require": "./dist/client/hooks/index.js"
+      "types": "./dist/hooks/index.d.ts",
+      "import": "./dist/hooks/index.mjs",
+      "require": "./dist/hooks/index.js"
     },
     "./client/primitives": {
-      "types": "./dist/client/components/primitives/index.d.ts",
-      "import": "./dist/client/components/primitives/index.mjs",
-      "require": "./dist/client/components/primitives/index.js"
+      "types": "./dist/primitives/index.d.ts",
+      "import": "./dist/primitives/index.mjs",
+      "require": "./dist/primitives/index.js"
     },
     "./client/types": {
       "types": "./dist/client/types.d.ts",
@@ -63,6 +88,7 @@
     "clsx": "^2.1.1",
     "codesandbox": "^2.2.3",
     "fast-glob": "^3.3.3",
+    "flexsearch": "^0.8.212",
     "github-slugger": "^2.0.0",
     "gray-matter": "^4.0.3",
     "isomorphic-dompurify": "^3.7.1",
@@ -79,7 +105,8 @@
     "tailwind-merge": "^3.5.0",
     "unist-util-visit": "^5.1.0",
     "vite": "^7.3.1",
-    "vite-plugin-image-optimizer": "^2.0.3"
+    "vite-plugin-image-optimizer": "^2.0.3",
+    "zustand": "^5.0.12"
   },
   "peerDependencies": {
     "react": "^19.1.0",

package/src/client/app/index.tsx

@@ -2,7 +2,6 @@ import React, { useEffect, useState, useMemo } from 'react'
 import ReactDOM from 'react-dom/client'
 import { BrowserRouter, Routes, Route } from 'react-router-dom'
 import { NotFound } from '@components/ui-base/not-found'
-import { Loading } from '@components/ui-base/loading'
 import { ThemeProvider } from './theme-context'
 import type { ComponentRoute, CreateBoltdocsAppOptions } from '../types'
 import type { BoltdocsConfig } from '@node/config'
@@ -17,6 +16,84 @@ import { DocsLayout } from './docs-layout'
 import { MdxPage } from './mdx-page'
 import { MdxComponentsProvider } from './mdx-components-context'
 import { mdxComponentsDefault } from './mdx-component'
+import { useRoutes } from '../hooks/use-routes'
+import { useLocation } from 'react-router-dom'
+import { useBoltdocsStore } from '../store/use-boltdocs-store'
+
+/**
+ * Updates the HTML lang and dir attributes based on the current locale configuration.
+ */
+function I18nUpdater() {
+  const { currentLocale, config } = useRoutes()
+
+  useEffect(() => {
+    if (!config.i18n) return
+    const localeConfig = config.i18n.localeConfigs?.[currentLocale as string]
+    document.documentElement.lang =
+      localeConfig?.htmlLang || currentLocale || 'en'
+    document.documentElement.dir = localeConfig?.direction || 'ltr'
+  }, [currentLocale, config.i18n])
+
+  return null
+}
+
+/**
+ * Synchronizes the Zustand store with the current URL pathname.
+ */
+function StoreSync() {
+  const location = useLocation()
+  const { config } = useRoutes()
+  const setLocale = useBoltdocsStore((s) => s.setLocale)
+  const setVersion = useBoltdocsStore((s) => s.setVersion)
+  const currentLocaleStore = useBoltdocsStore((s) => s.currentLocale)
+  const currentVersionStore = useBoltdocsStore((s) => s.currentVersion)
+
+  useEffect(() => {
+    const parts = location.pathname.split('/').filter(Boolean)
+    let cIdx = 0
+    let detectedVersion = config.versions?.defaultVersion
+    let detectedLocale = config.i18n?.defaultLocale
+
+    // 0. Skip docs prefix if present
+    if (parts[cIdx] === 'docs') cIdx++
+
+    // 1. Version detection
+    if (config.versions && parts.length > cIdx) {
+      const versionMatch = config.versions.versions.find(
+        (v) => v.path === parts[cIdx],
+      )
+      if (versionMatch) {
+        detectedVersion = versionMatch.path
+        cIdx++
+      }
+    }
+
+    // 2. Locale detection
+    if (
+      config.i18n &&
+      parts.length > cIdx &&
+      config.i18n.locales[parts[cIdx]]
+    ) {
+      detectedLocale = parts[cIdx]
+    } else if (config.i18n && parts.length === 0) {
+      // On root, use the stored preference if it exists, otherwise default
+      detectedLocale = currentLocaleStore || config.i18n.defaultLocale
+    }
+
+    // Only update if changed to avoid loops
+    if (detectedLocale !== currentLocaleStore) setLocale(detectedLocale)
+    if (detectedVersion !== currentVersionStore) setVersion(detectedVersion)
+  }, [
+    location.pathname,
+    config,
+    setLocale,
+    setVersion,
+    currentLocaleStore,
+    currentVersionStore,
+  ])
+
+  return null
+}
 
 export function AppShell({
   initialRoutes,
@@ -31,14 +108,17 @@ export function AppShell({
   initialRoutes: ComponentRoute[]
   initialConfig: BoltdocsConfig
   docsDirName: string
-  modules: Record<string, () => Promise<{ default: React.ComponentType<any> }>>
+  modules: Record<
+    string,
+    () => Promise<{ default: React.ComponentType<unknown> }>
+  >
   hot?: CreateBoltdocsAppOptions['hot']
   homePage?: React.ComponentType
   externalPages?: Record<string, React.ComponentType>
   components?: Record<string, React.ComponentType>
 }) {
   const [routesInfo, setRoutesInfo] = useState<ComponentRoute[]>(initialRoutes)
-  const [config] = useState(initialConfig)
+  const [config, setConfig] = useState(initialConfig)
   const computedExternalPages = externalPages || {}
 
   const resolvedRoutes = useMemo(() => {
@@ -53,16 +133,19 @@ export function AppShell({
           (k) =>
             k === `/${docsDirName}/${route.filePath}` || // Vite dev/build relative path
             k.endsWith(`/${docsDirName}/${route.filePath}`) || // SSG absolute path fallback
-            k.endsWith(`/${docsDirName}\\${route.filePath.replace(/\\/g, '/')}`), // Windows fallback
+            k.endsWith(
+              `/${docsDirName}\\${route.filePath.replace(/\\/g, '/')}`,
+            ), // Windows fallback
         )
         const loader = loaderKey ? modules[loaderKey] : null
 
         return {
           ...route,
-          Component: React.lazy<React.ComponentType<any>>(async () => {
-            if (!loader) return { default: NotFound as React.ComponentType<any> }
+          Component: React.lazy<React.ComponentType<unknown>>(async () => {
+            if (!loader)
+              return { default: NotFound as React.ComponentType<unknown> }
             const mod = await loader()
-            return mod
+            return mod as { default: React.ComponentType<unknown> }
           }),
         }
       })
@@ -74,6 +157,9 @@ export function AppShell({
       hot.on('boltdocs:routes-update', (newRoutes: ComponentRoute[]) => {
         setRoutesInfo(newRoutes)
       })
+      hot.on('boltdocs:config-update', (newConfig: BoltdocsConfig) => {
+        setConfig(newConfig)
+      })
     }
   }, [hot])
 
@@ -82,6 +168,8 @@ export function AppShell({
     [customComponents],
   )
 
+  const LoadingFallback = allComponents.Loading as React.ComponentType
+
   return (
     <ThemeProvider>
       <MdxComponentsProvider components={allComponents}>
@@ -89,41 +177,16 @@ export function AppShell({
           <BoltdocsRouterProvider>
             <PreloadProvider routes={routesInfo} modules={modules}>
               <ScrollHandler />
+              <StoreSync />
+              <I18nUpdater />
               <Routes>
-                {/* Custom home page with user layout */}
-                {HomePage && (
-                  <Route
-                    path="/"
-                    element={
-                      <UserLayout>
-                        <HomePage />
-                      </UserLayout>
-                    }
-                  />
-                )}
-
-                {/* Custom External Pages with user layout */}
-                {Object.entries(computedExternalPages).map(
-                  ([extPath, ExtComponent]) => (
-                    <Route
-                      key={extPath}
-                      path={extPath}
-                      element={
-                        <UserLayout>
-                          <ExtComponent />
-                        </UserLayout>
-                      }
-                    />
-                  ),
-                )}
-
                 <Route key="docs-layout" element={<DocsLayout />}>
                   {resolvedRoutes.map((route) => (
                     <Route
                       key={route.path}
                       path={route.path === '' ? '/' : route.path}
                       element={
-                        <React.Suspense fallback={<Loading />}>
+                        <React.Suspense fallback={<LoadingFallback />}>
                           <MdxPage Component={route.Component} />
                         </React.Suspense>
                       }
@@ -131,6 +194,63 @@ export function AppShell({
                   ))}
                 </Route>
 
+                {/* Custom home page with user layout */}
+                {HomePage && (
+                  <>
+                    <Route
+                      path="/"
+                      element={
+                        <UserLayout>
+                          <HomePage />
+                        </UserLayout>
+                      }
+                    />
+                    {config.i18n &&
+                      Object.keys(config.i18n.locales).map((locale) => (
+                        <Route
+                          key={`home-${locale}`}
+                          path={`/${locale}`}
+                          element={
+                            <UserLayout>
+                              <HomePage />
+                            </UserLayout>
+                          }
+                        />
+                      ))}
+                  </>
+                )}
+
+                {/* Custom External Pages with user layout */}
+                {Object.entries(computedExternalPages).map(
+                  ([extPath, ExtComponent]) => {
+                    const cleanPath = extPath === '/' ? '' : extPath
+                    return (
+                      <React.Fragment key={extPath}>
+                        <Route
+                          path={extPath}
+                          element={
+                            <UserLayout>
+                              <ExtComponent />
+                            </UserLayout>
+                          }
+                        />
+                        {config.i18n &&
+                          Object.keys(config.i18n.locales).map((locale) => (
+                            <Route
+                              key={`${extPath}-${locale}`}
+                              path={`/${locale}${cleanPath}`}
+                              element={
+                                <UserLayout>
+                                  <ExtComponent />
+                                </UserLayout>
+                              }
+                            />
+                          ))}
+                      </React.Fragment>
+                    )
+                  },
+                )}
+
                 <Route
                   path="*"
                   element={

package/src/client/app/mdx-component.tsx

@@ -6,14 +6,15 @@ const Heading = ({
   level,
   id,
   children,
+  ...props
 }: {
   level: number
   id?: string
   children?: React.ReactNode
-}) => {
-  const Tag = `h${level}` as keyof JSX.IntrinsicElements
+} & React.HTMLAttributes<HTMLHeadingElement>) => {
+  const Tag = `h${level}` as any
   return (
-    <Tag id={id} className="boltdocs-heading">
+    <Tag id={id} {...props} className="boltdocs-heading">
       {children}
       {id && (
         <a href={`#${id}`} className="header-anchor" aria-label="Anchor">
@@ -24,8 +25,11 @@ const Heading = ({
   )
 }
 
+import { Loading } from '@components/ui-base/loading'
+
 export const mdxComponentsDefault = {
   ...MdxComponents,
+  Loading,
   h1: (props: React.HTMLAttributes<HTMLHeadingElement>) => (
     <Heading level={1} {...props} />
   ),

package/src/client/app/theme-context.tsx

@@ -1,45 +1,75 @@
 import { createContext, use, useEffect, useState } from 'react'
 
-type Theme = 'light' | 'dark'
+type Theme = 'light' | 'dark' | 'system'
 
 interface ThemeContextType {
   theme: Theme
-  toggleTheme: () => void
+  resolvedTheme: 'light' | 'dark'
   setTheme: (theme: Theme) => void
 }
 
 const ThemeContext = createContext<ThemeContextType | undefined>(undefined)
 
 export function ThemeProvider({ children }: { children: React.ReactNode }) {
-  const [theme, setThemeState] = useState<Theme>('dark')
+  const [theme, setThemeState] = useState<Theme>('system')
+  const [resolvedTheme, setResolvedTheme] = useState<'light' | 'dark'>('dark')
   const [mounted, setMounted] = useState(false)
 
+  // Initialize theme from localStorage and set internal resolved theme
   useEffect(() => {
     setMounted(true)
-    const stored = localStorage.getItem('boltdocs-theme')
-    if (stored === 'light' || stored === 'dark') {
-      setThemeState(stored as Theme)
-    } else {
-      const prefersDark = window.matchMedia(
-        '(prefers-color-scheme: dark)',
-      ).matches
-      setThemeState(prefersDark ? 'dark' : 'light')
-    }
+    const stored = localStorage.getItem('boltdocs-theme') as Theme | null
+    const initialTheme =
+      stored === 'light' || stored === 'dark' || stored === 'system'
+        ? stored
+        : 'system'
+
+    setThemeState(initialTheme)
 
     const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
-    const handleChange = (e: MediaQueryListEvent) => {
-      if (!localStorage.getItem('boltdocs-theme')) {
-        setThemeState(e.matches ? 'dark' : 'light')
+
+    const updateResolved = (currentTheme: Theme, isDark: boolean) => {
+      if (currentTheme === 'system') {
+        setResolvedTheme(isDark ? 'dark' : 'light')
+      } else {
+        setResolvedTheme(currentTheme as 'light' | 'dark')
       }
     }
+
+    updateResolved(initialTheme, mediaQuery.matches)
+
+    const handleChange = (e: MediaQueryListEvent) => {
+      // Re-read current theme state from some stable ref would be better, but we can capture it
+      // actually, the second useEffect will handle the source of truth,
+      // but this listener ensures 'system' updates instantly.
+      setResolvedTheme((prevResolved) => {
+        const currentTheme =
+          (localStorage.getItem('boltdocs-theme') as Theme) || 'system'
+        if (currentTheme === 'system') {
+          return e.matches ? 'dark' : 'light'
+        }
+        return prevResolved
+      })
+    }
+
     mediaQuery.addEventListener('change', handleChange)
     return () => mediaQuery.removeEventListener('change', handleChange)
   }, [])
 
+  // Sync with DOM and resolved theme when theme preference changes
   useEffect(() => {
     if (!mounted) return
+
+    const isSystemDark = window.matchMedia(
+      '(prefers-color-scheme: dark)',
+    ).matches
+    const nextResolved =
+      theme === 'system' ? (isSystemDark ? 'dark' : 'light') : theme
+
+    setResolvedTheme(nextResolved as 'light' | 'dark')
+
     const root = document.documentElement
-    if (theme === 'light') {
+    if (nextResolved === 'light') {
       root.classList.add('theme-light')
       root.dataset.theme = 'light'
     } else {
@@ -48,19 +78,13 @@ export function ThemeProvider({ children }: { children: React.ReactNode }) {
     }
   }, [theme, mounted])
 
-  const toggleTheme = () => {
-    const newTheme = theme === 'dark' ? 'light' : 'dark'
-    setThemeState(newTheme)
-    localStorage.setItem('boltdocs-theme', newTheme)
-  }
-
   const setTheme = (newTheme: Theme) => {
     setThemeState(newTheme)
     localStorage.setItem('boltdocs-theme', newTheme)
   }
 
   return (
-    <ThemeContext.Provider value={{ theme, toggleTheme, setTheme }}>
+    <ThemeContext.Provider value={{ theme, resolvedTheme, setTheme }}>
       {children}
     </ThemeContext.Provider>
   )