boltdocs 2.1.0 → 2.2.0

package/src/client/hooks/use-localized-to.ts

@@ -1,95 +1,72 @@
-import { useLocation } from 'react-router-dom'
 import { useConfig } from '@client/app/config-context'
 import type { LinkProps as RouterLinkProps } from 'react-router-dom'
+import { useRoutes } from './use-routes'
 
 /**
  * Hook to automatically localize a path based on the current version and locale context.
- * It ensures that navigation within the /docs path preserves the active version and language.
+ * It ensures that navigation preserves the active version and language across the entire site.
  */
 export function useLocalizedTo(to: RouterLinkProps['to']) {
-  const location = useLocation()
   const config = useConfig()
+  const { currentLocale: activeLocale, currentVersion: activeVersion } = useRoutes()
 
   if (!config || typeof to !== 'string') return to
-  if (!config.i18n && !config.versions) return to
+  
+  // External or absolute links don't need localization
+  if (to.startsWith('http') || to.startsWith('//')) return to
 
-  const basePath = '/docs'
-  if (!to.startsWith(basePath)) return to
+  const i18n = config.i18n
+  const versions = config.versions
 
-  // 1. Detect current context from location
-  const curSub = location.pathname.substring(basePath.length)
-  const curParts = curSub.split('/').filter(Boolean)
+  if (!i18n && !versions) return to
 
-  let currentVersion = config.versions?.defaultVersion
-  let currentLocale = config.i18n?.defaultLocale
+  // 1. Identify the input intent
+  const isDocLink = to.startsWith('/docs')
+  
+  // 3. Clean the 'to' path of ANY existing prefixes to avoid stacking
+  const parts = to.split('/').filter(Boolean)
+  let pIdx = 0
 
-  let cIdx = 0
-  if (
-    config.versions &&
-    curParts.length > cIdx &&
-    config.versions.versions[curParts[cIdx]]
-  ) {
-    currentVersion = curParts[cIdx]
-    cIdx++
-  }
-  if (
-    config.i18n &&
-    curParts.length > cIdx &&
-    config.i18n.locales[curParts[cIdx]]
-  ) {
-    currentLocale = curParts[cIdx]
+  // Strip '/docs' if present at start
+  if (parts[pIdx] === 'docs') pIdx++
+
+  // Strip versions if present
+  if (versions && parts.length > pIdx) {
+    const vMatch = versions.versions.find(v => v.path === parts[pIdx])
+    if (vMatch) pIdx++
   }
 
-  // 2. Parse the target `to` path
-  const toSub = to.substring(basePath.length)
-  const toParts = toSub.split('/').filter(Boolean)
+  // Strip locales if present
+  if (i18n && parts.length > pIdx && i18n.locales[parts[pIdx]]) pIdx++
 
-  let tIdx = 0
-  let hasVersion = false
-  let hasLocale = false
+  // The actual relative route remaining
+  const routeContent = parts.slice(pIdx)
 
-  if (
-    config.versions &&
-    toParts.length > tIdx &&
-    config.versions.versions[toParts[tIdx]]
-  ) {
-    hasVersion = true
-    tIdx++
-  }
-  if (
-    config.i18n &&
-    toParts.length > tIdx &&
-    config.i18n.locales[toParts[tIdx]]
-  ) {
-    hasLocale = true
-    tIdx++
-  }
+  // 4. Reconstruct strictly from base
+  const resultParts: string[] = []
 
-  // Extract just the actual route parts
-  const routeParts = toParts.slice(tIdx)
-
-  // Reconstruct path
-  const finalParts = []
-  if (config.versions) {
-    if (hasVersion) {
-      finalParts.push(toParts[0])
-    } else if (currentVersion) {
-      finalParts.push(currentVersion)
+  if (isDocLink) {
+    resultParts.push('docs')
+    if (versions && activeVersion) {
+      resultParts.push(activeVersion)
     }
   }
-  if (config.i18n) {
-    if (hasLocale) {
-      finalParts.push(toParts[hasVersion ? 1 : 0])
-    } else if (currentLocale) {
-      finalParts.push(currentLocale)
+
+  if (i18n && activeLocale) {
+    // Only prefix if it's NOT the default locale (cleaner URLs)
+    if (activeLocale !== i18n.defaultLocale) {
+      resultParts.push(activeLocale)
     }
   }
 
-  finalParts.push(...routeParts)
+  resultParts.push(...routeContent)
 
-  let finalPath = `${basePath}/${finalParts.join('/')}`
-  if (finalPath.endsWith('/')) {
-    finalPath = finalPath.slice(0, -1)
+  const finalPath = `/${resultParts.join('/')}`
+  
+  // Cleanup trailing slashes unless it's just root
+  if (finalPath.length > 1 && finalPath.endsWith('/')) {
+    return finalPath.slice(0, -1)
   }
-  return finalPath === basePath ? basePath : finalPath
+
+  return finalPath || '/'
 }

package/src/client/hooks/use-navbar.ts

@@ -2,14 +2,17 @@ import { useLocation } from 'react-router-dom'
 import { useConfig } from '@client/app/config-context'
 import { useTheme } from '@client/app/theme-context'
 import type { NavbarLink } from '@client/types'
+import { getTranslated } from '@client/utils/i18n'
+import { useRoutes } from './use-routes'
 
 export function useNavbar() {
   const config = useConfig()
   const { theme } = useTheme()
   const location = useLocation()
+  const { currentLocale } = useRoutes()
 
-  const themeConfig = config.theme || config.themeConfig || {}
-  const title = themeConfig.title || 'Boltdocs'
+  const themeConfig = config.theme || {}
+  const title = getTranslated(themeConfig.title, currentLocale) || 'Boltdocs'
   const rawLinks = themeConfig.navbar || []
   const socialLinks = themeConfig.socialLinks || []
   const githubRepo = themeConfig.githubRepo
@@ -18,13 +21,17 @@ export function useNavbar() {
   const links: NavbarLink[] = rawLinks.map((item: any) => {
     const href = item.href || item.to || item.link || ''
     return {
-      label: item.label || item.text || '',
+      label: getTranslated(item.label || item.text, currentLocale),
       href,
       active: location.pathname === href,
       to:
         href.startsWith('http') || href.startsWith('//')
           ? 'external'
           : undefined,
+      items: item.items?.map((sub: any) => ({
+        label: getTranslated(sub.label || sub.text, currentLocale),
+        href: sub.href || sub.link || sub.to || '',
+      })),
     }
   })
 

package/src/client/hooks/use-routes.ts

@@ -1,6 +1,7 @@
 import { useLocation } from 'react-router-dom'
 import { useConfig } from '@client/app/config-context'
 import { usePreload } from '@client/app/preload'
+import { useBoltdocsStore } from '../store/use-boltdocs-store'
 
 /**
  * Hook to access the framework's routing state.
@@ -12,16 +13,26 @@ export function useRoutes() {
   const config = useConfig()
   const location = useLocation()
 
-  // Find the current route exactly matching the pathname
+  // Use Zustand store for active state
+  const currentLocaleStore = useBoltdocsStore((s) => s.currentLocale)
+  const currentVersionStore = useBoltdocsStore((s) => s.currentVersion)
+  const hasHydrated = useBoltdocsStore((s) => s.hasHydrated)
+
+  // Find the current route matching the pathname
   const currentRoute = allRoutes.find((r) => r.path === location.pathname)
 
-  // Derive current locale and version from the route or defaults
+  // Derive current locale and version
+  // Priority: URL (currentRoute) > Zustand Store (Persistence) > Config Default
   const currentLocale = config.i18n
-    ? currentRoute?.locale || config.i18n.defaultLocale
+    ? currentRoute?.locale ||
+      (hasHydrated ? currentLocaleStore : undefined) ||
+      config.i18n.defaultLocale
     : undefined
 
   const currentVersion = config.versions
-    ? currentRoute?.version || config.versions.defaultVersion
+    ? currentRoute?.version ||
+      (hasHydrated ? currentVersionStore : undefined) ||
+      config.versions.defaultVersion
     : undefined
 
   // Filter routes to those matching the current version and locale
@@ -32,28 +43,61 @@ export function useRoutes() {
     const versionMatch = config.versions
       ? (r.version || config.versions.defaultVersion) === currentVersion
       : true
-    return localeMatch && versionMatch
+
+    if (!(localeMatch && versionMatch)) return false
+
+    // Resolve duplicate paths (aliases) like /docs vs /docs/en
+    // We prefer the version that matches the current route's prefix style
+    const i18n = config.i18n
+    if (i18n) {
+      const isCurrentRoutePrefixed = !!currentRoute?.locale
+      const isRoutePrefixed = !!r.locale
+
+      const hasAlternate = allRoutes.some(
+        (alt) =>
+          alt !== r &&
+          alt.filePath === r.filePath &&
+          alt.version === r.version &&
+          (alt.locale || i18n.defaultLocale) ===
+            (r.locale || i18n.defaultLocale),
+      )
+
+      if (hasAlternate && isCurrentRoutePrefixed !== isRoutePrefixed) {
+        return false
+      }
+    }
+
+    return true
   })
 
   // Labels and lists for UI convenience
+  const currentLocaleConfig = config.i18n?.localeConfigs?.[currentLocale as string]
   const currentLocaleLabel =
-    config.i18n?.locales[currentLocale as string] || currentLocale
-  const currentVersionLabel =
-    config.versions?.versions[currentVersion as string] || currentVersion
+    currentLocaleConfig?.label ||
+    config.i18n?.locales[currentLocale as string] ||
+    currentLocale
+
+  const currentVersionConfig = config.versions?.versions.find(
+    (v) => v.path === currentVersion,
+  )
+  const currentVersionLabel = currentVersionConfig?.label || currentVersion
 
   const availableLocales = config.i18n
-    ? Object.entries(config.i18n.locales).map(([key, label]) => ({
-        key,
-        label,
-        isCurrent: key === currentLocale,
-      }))
+    ? Object.entries(config.i18n.locales).map(([key, defaultLabel]) => {
+        const localeConfig = config.i18n?.localeConfigs?.[key]
+        return {
+          key,
+          label: localeConfig?.label || defaultLabel,
+          isCurrent: key === currentLocale,
+        }
+      })
     : []
 
   const availableVersions = config.versions
-    ? Object.entries(config.versions.versions).map(([key, label]) => ({
-        key,
-        label,
-        isCurrent: key === currentVersion,
+    ? config.versions.versions.map((v) => ({
+        key: v.path,
+        label: v.label,
+        isCurrent: v.path === currentVersion,
       }))
     : []
 

package/src/client/hooks/use-search.ts

@@ -1,13 +1,22 @@
 import { useState, useMemo } from 'react'
+import { useRoutes } from './use-routes'
 import type { ComponentRoute } from '@client/types'
 
 export function useSearch(routes: ComponentRoute[]) {
+  const { currentLocale, currentVersion } = useRoutes()
   const [isOpen, setIsOpen] = useState(false)
   const [query, setQuery] = useState('')
 
   const list = useMemo(() => {
+    // 0. Filter routes by active context
+    const activeRoutes = routes.filter((r) => {
+      const localeMatch = !currentLocale || r.locale === currentLocale
+      const versionMatch = !currentVersion || r.version === currentVersion
+      return localeMatch && versionMatch
+    })
+
     if (!query) {
-      return routes.slice(0, 10).map((r) => ({
+      return activeRoutes.slice(0, 10).map((r) => ({
         id: r.path,
         title: r.title,
         path: r.path,
@@ -16,10 +25,17 @@ export function useSearch(routes: ComponentRoute[]) {
       }))
     }
 
-    const results: any[] = []
+    const results: {
+      id: string
+      title: string | undefined
+      path: string
+      bio: string
+      groupTitle: string | undefined
+      isHeading?: boolean
+    }[] = []
     const lowerQuery = query.toLowerCase()
 
-    for (const route of routes) {
+    for (const route of activeRoutes) {
       if (route.title?.toLowerCase().includes(lowerQuery)) {
         results.push({
           id: route.path,
@@ -55,7 +71,7 @@ export function useSearch(routes: ComponentRoute[]) {
         return true
       })
       .slice(0, 10)
-  }, [routes, query])
+  }, [routes, query, currentLocale, currentVersion])
 
   return {
     isOpen,
@@ -65,7 +81,7 @@ export function useSearch(routes: ComponentRoute[]) {
     list,
     input: {
       value: query,
-      onChange: (e: any) => setQuery(e.target.value),
+      onChange: (e: React.ChangeEvent<HTMLInputElement>) => setQuery(e.target.value),
     },
   }
 }

package/src/client/hooks/use-sidebar.ts

@@ -7,7 +7,10 @@ export function useSidebar(routes: ComponentRoute[]) {
   const location = useLocation()
 
   // Find active route and tab
-  const activeRoute = routes.find((r) => r.path === location.pathname)
+  const normalize = (p: string) => (p.endsWith('/') && p.length > 1 ? p.slice(0, -1) : p)
+  const currentPath = normalize(location.pathname)
+
+  const activeRoute = routes.find((r) => normalize(r.path) === currentPath)
   const activeTabId = activeRoute?.tab?.toLowerCase()
 
   // Filter routes by active tab if any
@@ -43,7 +46,7 @@ export function useSidebar(routes: ComponentRoute[]) {
     groups,
     ungrouped,
     activeRoute,
-    activePath: location.pathname,
+    activePath: currentPath,
     config,
   }
 }

package/src/client/hooks/use-version.ts

@@ -1,6 +1,7 @@
 import { useNavigate } from 'react-router-dom'
 import { getBaseFilePath } from '@client/utils/get-base-file-path'
 import { useRoutes } from './use-routes'
+import { useBoltdocsStore } from '../store/use-boltdocs-store'
 
 export interface VersionOption {
   key: string
@@ -25,10 +26,14 @@ export function useVersion(): UseVersionReturn {
   const { allRoutes, currentRoute, currentVersion, currentLocale, config } =
     routeContext
   const versions = config.versions
+  const setVersion = useBoltdocsStore((s) => s.setVersion)
 
   const handleVersionChange = (version: string) => {
     if (!versions || version === currentVersion) return
 
+    // Update store
+    setVersion(version)
+
     let targetPath = `/docs/${version}`
 
     if (currentRoute) {

package/src/client/integrations/index.ts

@@ -0,0 +1 @@
+export * from './codesandbox'

package/src/client/store/use-boltdocs-store.ts

@@ -0,0 +1,43 @@
+import { create } from 'zustand'
+import { persist, createJSONStorage } from 'zustand/middleware'
+
+interface BoltdocsState {
+  currentLocale: string | undefined
+  currentVersion: string | undefined
+  hasHydrated: boolean
+  
+  // Actions
+  setLocale: (locale: string | undefined) => void
+  setVersion: (version: string | undefined) => void
+  setHasHydrated: (val: boolean) => void
+}
+
+/**
+ * Global store for Boltdocs documentation state.
+ * Uses localStorage persistence to remember user preferences across sessions.
+ */
+export const useBoltdocsStore = create<BoltdocsState>()(
+  persist(
+    (set) => ({
+      currentLocale: undefined,
+      currentVersion: undefined,
+      hasHydrated: false,
+      
+      setLocale: (locale: string | undefined) => set({ currentLocale: locale }),
+      setVersion: (version: string | undefined) => set({ currentVersion: version }),
+      setHasHydrated: (val: boolean) => set({ hasHydrated: val }),
+    }),
+    {
+      name: 'boltdocs-storage',
+      storage: createJSONStorage(() => localStorage),
+      // Only persist identifying state
+      partialize: (state: BoltdocsState) => ({
+        currentLocale: state.currentLocale,
+        currentVersion: state.currentVersion,
+      }),
+      onRehydrateStorage: () => (state?: BoltdocsState) => {
+        state?.setHasHydrated(true)
+      },
+    }
+  )
+)

package/src/client/types.ts

@@ -119,7 +119,8 @@ export interface SandboxEmbedOptions {
  */
 export 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
 }
 
@@ -160,7 +161,8 @@ export interface LayoutProps {
  * Unified type for navbar links.
  */
 export 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 */

package/src/client/utils/i18n.ts

@@ -0,0 +1,23 @@
+/**
+ * Retrieves the correct translation from a value that can be either
+ * a simple string or a map of locale-specific strings.
+ *
+ * @param value - The text to translate
+ * @param locale - The current active locale (e.g., 'en', 'es')
+ * @returns The translated string
+ */
+export function getTranslated(
+  value: string | Record<string, string> | undefined,
+  locale?: string,
+): string {
+  if (!value) return ''
+  if (typeof value === 'string') return value
+
+  if (locale && value[locale]) {
+    return value[locale]
+  }
+
+  // Fallback: Use the first available translation or an empty string
+  const firstValue = Object.values(value)[0]
+  return firstValue || ''
+}

package/src/node/config.ts

@@ -24,10 +24,10 @@ export interface BoltdocsFooterConfig {
  * Theme-specific configuration options governing the appearance and navigation of the site.
  */
 export 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
@@ -40,12 +40,17 @@ export 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; href: string }>
+    items?: Array<{
+      /** Text to display (can be a string or a map of translations) */
+      label: string | Record<string, string>
+      /** URL path or external link */
+      href: string
+    }>
   }>
   /** Items to display in the sidebar, organized optionally by group URLs */
   sidebar?: Record<string, Array<{ text: string; link: string }>>
@@ -78,7 +83,12 @@ export interface BoltdocsThemeConfig {
    * Top-level tabs for organizing documentation groups.
    * Tab discovery uses the (tab-id) directory syntax.
    */
-  tabs?: Array<{ id: string; text: string; icon?: string }>
+  tabs?: Array<{
+    id: string
+    /** Text to display (can be a string or a map of translations) */
+    text: string | Record<string, string>
+    icon?: string
+  }>
   /**
    * The syntax highlighting theme for code blocks.
    * Supports any Shiki theme name (e.g., 'github-dark', 'one-dark-pro', 'aurora-x').
@@ -112,24 +122,55 @@ export type BoltdocsRobotsConfig =
       sitemaps?: string[]
     }
 
+/**
+ * Configuration for a specific locale.
+ */
+export 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).
  */
 export 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.
+ */
+export 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.
  */
 export 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[]
 }
 
 /**
@@ -189,8 +230,6 @@ export interface BoltdocsConfig {
   robots?: BoltdocsRobotsConfig
   /** Low-level Vite configuration overrides */
   vite?: import('vite').InlineConfig
-  /** @deprecated Use theme instead */
-  themeConfig?: BoltdocsThemeConfig
 }
 
 export function defineConfig(config: BoltdocsConfig): BoltdocsConfig {
@@ -286,13 +325,12 @@ export async function resolveConfig(
     poweredBy: userConfig.poweredBy,
     communityHelp: userConfig.communityHelp,
     version: userConfig.version,
-    editLink: userConfig.editLink
+    editLink: userConfig.editLink,
   }
 
   // User can define properties at top level or inside themeConfig/theme
   const userThemeConfig: BoltdocsThemeConfig = {
     ...themeConfigFromTop,
-    ...(userConfig.themeConfig || {}),
     ...(userConfig.theme || {}),
   }
 
@@ -330,4 +368,3 @@ export async function resolveConfig(
     vite: userConfig.vite,
   }
 }
-

package/src/node/index.ts

@@ -2,7 +2,7 @@ import type { Plugin, InlineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
 import tailwindcss from '@tailwindcss/vite'
 import { boltdocsPlugin } from './plugin/index'
-import { boltdocsMdxPlugin } from './mdx'
+import { boltdocsMdxPlugin } from './mdx/index'
 import type { BoltdocsPluginOptions } from './plugin/index'
 
 import { resolveConfig, type BoltdocsConfig } from './config'

package/src/node/mdx/cache.ts

@@ -0,0 +1,12 @@
+import { TransformCache } from '../cache'
+
+/**
+ * Version identifier for the MDX plugin to invalidate cache if logic changes.
+ */
+export const MDX_PLUGIN_VERSION = 'v3'
+
+/**
+ * Persistent cache for MDX transformations.
+ * Saves results to `.boltdocs/transform-mdx.json.gz`.
+ */
+export const mdxCache = new TransformCache('mdx')