boltdocs 2.1.1 → 2.3.0

package/src/node/plugin/index.ts

@@ -9,9 +9,9 @@ import type { BoltdocsPluginOptions } from './types'
 import { generateEntryCode } from './entry'
 import { injectHtmlMeta, getHtmlTemplate } from './html'
 import { generateRobotsTxt } from '../ssg/robots'
+import { generateSearchData } from '../search'
 import fs from 'fs'
 
-
 export * from './types'
 
 /**
@@ -55,7 +55,20 @@ export function boltdocsPlugin(
         }
 
         return {
-          optimizeDeps: { include: ['react', 'react-dom'] },
+          optimizeDeps: {
+            include: ['react', 'react-dom'],
+            exclude: [
+              'boltdocs',
+              'boltdocs/client',
+              'boltdocs/hooks',
+              'boltdocs/primitives',
+              'boltdocs/base-ui',
+              'boltdocs/mdx',
+              'boltdocs/integrations',
+              'boltdocs/client/hooks',
+              'boltdocs/client/primitives',
+            ],
+          },
         }
       },
 
@@ -76,25 +89,39 @@ export function boltdocsPlugin(
           next()
         })
 
-        // Serve default HTML if index.html is missing
+        // Serve default HTML for documentation routes or if index.html is missing
         server.middlewares.use(async (req, res, next) => {
           const url = req.url?.split('?')[0] || '/'
           const accept = req.headers.accept || ''
 
-          if (
-            accept.includes('text/html') &&
-            !url.includes('.') // Simple check for assets
-          ) {
-            const indexPath = path.resolve(process.cwd(), 'index.html')
-            if (!fs.existsSync(indexPath)) {
-              let html = getHtmlTemplate(config)
-              html = injectHtmlMeta(html, config)
-              html = await server.transformIndexHtml(req.url || '/', html)
-              res.statusCode = 200
-              res.setHeader('Content-Type', 'text/html')
-              res.end(html)
-              return
-            }
+          const isDocRoute =
+            url === '/' ||
+            url.startsWith('/docs') ||
+            (config.i18n &&
+              Object.keys(config.i18n.locales).some(
+                (locale) =>
+                  url.startsWith(`/${locale}/docs`) || url === `/${locale}`,
+              )) ||
+            (config.external &&
+              Object.keys(config.external).some((extPath) =>
+                url.startsWith(extPath),
+              ))
+
+          // Improved check: If it's a doc route, serve HTML even if it has a dot (e.g. version 1.1)
+          // We only skip if it has a known asset extension to prevent serving HTML for images/js/etc.
+          const isAsset =
+            /\.(js|css|png|jpe?g|gif|svg|ico|webp|woff2?|ttf|otf|mp4|webm|ogg|mp3|wav|flac|aac|pdf|zip|gz|map|json)$/i.test(
+              url,
+            )
+
+          if (accept.includes('text/html') && !isAsset && isDocRoute) {
+            let html = getHtmlTemplate(config)
+            html = injectHtmlMeta(html, config)
+            html = await server.transformIndexHtml(req.url || '/', html)
+            res.statusCode = 200
+            res.setHeader('Content-Type', 'text/html')
+            res.end(html)
+            return
           }
 
           next()
@@ -124,66 +151,96 @@ export function boltdocsPlugin(
           file: string,
           type: 'add' | 'unlink' | 'change',
         ) => {
-          const normalized = normalizePath(file)
-
-          // Restart the Vite server if the Boltdocs config changes
-          if (CONFIG_FILES.some((c) => normalized.endsWith(c))) {
-            server.restart()
-            return
-          }
+          try {
+            const normalized = normalizePath(file)
 
-          // If mdx-components file changes, invalidate the virtual module
-          if (
-            mdxCompExtensions.some((ext) =>
-              normalized.endsWith(`mdx-components.${ext}`),
-            )
-          ) {
-            const mod = server.moduleGraph.getModuleById(
-              '\0virtual:boltdocs-mdx-components',
-            )
-            if (mod) server.moduleGraph.invalidateModule(mod)
-            server.ws.send({ type: 'full-reload' })
-            return
-          }
+            // Restart the Vite server if the Boltdocs config changes
+            if (CONFIG_FILES.some((c) => normalized.endsWith(c))) {
+              server.restart()
+              return
+            }
 
-          // If layout.tsx/jsx file changes, invalidate the virtual module
-          if (
-            compExtensions.some((ext) => normalized.endsWith(`layout.${ext}`))
-          ) {
-            const mod = server.moduleGraph.getModuleById(
-              '\0virtual:boltdocs-layout',
-            )
-            if (mod) server.moduleGraph.invalidateModule(mod)
-            server.ws.send({ type: 'full-reload' })
-            return
-          }
+            // If mdx-components file changes, invalidate the virtual module
+            if (
+              mdxCompExtensions.some((ext) =>
+                normalized.endsWith(`mdx-components.${ext}`),
+              )
+            ) {
+              const mod = server.moduleGraph.getModuleById(
+                '\0virtual:boltdocs-mdx-components',
+              )
+              if (mod) server.moduleGraph.invalidateModule(mod)
+              server.ws.send({ type: 'full-reload' })
+              return
+            }
 
-          if (
-            !normalized.startsWith(normalizedDocsDir) ||
-            !isDocFile(normalized)
-          )
-            return
+            // If layout.tsx/jsx file changes, invalidate the virtual module
+            if (
+              compExtensions.some((ext) => normalized.endsWith(`layout.${ext}`))
+            ) {
+              const mod = server.moduleGraph.getModuleById(
+                '\0virtual:boltdocs-layout',
+              )
+              if (mod) server.moduleGraph.invalidateModule(mod)
+              server.ws.send({ type: 'full-reload' })
+              return
+            }
 
-          // Invalidate appropriately
-          if (type === 'add' || type === 'unlink') {
-            invalidateRouteCache()
-          } else {
-            invalidateFile(file)
-          }
+            if (
+              !normalized.startsWith(normalizedDocsDir) ||
+              !isDocFile(normalized)
+            )
+              return
 
-          // Regenerate and push to client
-          const newRoutes = await generateRoutes(docsDir, config)
+            // Invalidate appropriately
+            if (type === 'add' || type === 'unlink') {
+              invalidateRouteCache()
+              // Re-resolve config as it might affect versions/routes
+              config = await resolveConfig(docsDir)
+
+              const configMod = server.moduleGraph.getModuleById(
+                '\0virtual:boltdocs-config',
+              )
+              if (configMod) server.moduleGraph.invalidateModule(configMod)
+
+              server.ws.send({
+                type: 'custom',
+                event: 'boltdocs:config-update',
+                data: {
+                  theme: config?.theme,
+                  integrations: config?.integrations,
+                  i18n: config?.i18n,
+                  versions: config?.versions,
+                  siteUrl: config?.siteUrl,
+                },
+              })
+            } else {
+              invalidateFile(file)
+            }
 
-          const routesMod = server.moduleGraph.getModuleById(
-            '\0virtual:boltdocs-routes',
-          )
-          if (routesMod) server.moduleGraph.invalidateModule(routesMod)
+            // Regenerate and push to client
+            // Optimization: generateRoutes is mostly incremental thanks to docCache
+            // We only force a full disk scan on add/unlink events
+            const newRoutes = await generateRoutes(
+              docsDir,
+              config,
+              '/docs',
+              type !== 'change',
+            )
 
-          server.ws.send({
-            type: 'custom',
-            event: 'boltdocs:routes-update',
-            data: newRoutes,
-          })
+            const routesMod = server.moduleGraph.getModuleById(
+              '\0virtual:boltdocs-routes',
+            )
+            if (routesMod) server.moduleGraph.invalidateModule(routesMod)
+
+            server.ws.send({
+              type: 'custom',
+              event: 'boltdocs:routes-update',
+              data: newRoutes,
+            })
+          } catch (e) {
+            console.error(`[boltdocs] HMR error during ${type} event:`, e)
+          }
         }
 
         server.watcher.on('add', (f) => handleFileEvent(f, 'add'))
@@ -197,7 +254,8 @@ export function boltdocsPlugin(
           id === 'virtual:boltdocs-config' ||
           id === 'virtual:boltdocs-entry' ||
           id === 'virtual:boltdocs-mdx-components' ||
-          id === 'virtual:boltdocs-layout'
+          id === 'virtual:boltdocs-layout' ||
+          id === 'virtual:boltdocs-search'
         ) {
           return '\0' + id
         }
@@ -211,7 +269,6 @@ export function boltdocsPlugin(
         if (id === '\0virtual:boltdocs-config') {
           const clientConfig = {
             theme: config?.theme,
-            themeConfig: config?.themeConfig,
             integrations: config?.integrations,
             i18n: config?.i18n,
             versions: config?.versions,
@@ -267,6 +324,12 @@ export default UserLayout;`
           return `import { DefaultLayout } from 'boltdocs/client';
 export default DefaultLayout;`
         }
+
+        if (id === '\0virtual:boltdocs-search') {
+          const routes = await generateRoutes(docsDir, config)
+          const searchData = generateSearchData(routes)
+          return `export default ${JSON.stringify(searchData, null, 2)};`
+        }
       },
 
       transformIndexHtml: {

package/src/node/routes/index.ts

@@ -11,7 +11,8 @@ import { sortRoutes } from './sorter'
 export type { RouteMeta }
 export { invalidateRouteCache, invalidateFile }
 
-// Cache for localized path computations
+// Cache for file list and localized path computations
+let cachedFileList: string[] | null = null
 const localizedPathCache = new Map<string, string>()
 
 /**
@@ -30,6 +31,7 @@ export async function generateRoutes(
   docsDir: string,
   config?: BoltdocsConfig,
   basePath: string = '/docs',
+  forceScan: boolean = true,
 ): Promise<RouteMeta[]> {
   const start = performance.now()
 
@@ -44,13 +46,19 @@ export async function generateRoutes(
     docCache.invalidateAll()
   }
 
-  // 1. FAST SCAN
-  const files = await fastGlob(['**/*.md', '**/*.mdx'], {
-    cwd: docsDir,
-    absolute: true,
-    suppressErrors: true,
-    followSymbolicLinks: false,
-  })
+  // 1. FAST SCAN (Skip if incremental and we have a cache)
+  let files: string[]
+  if (!forceScan && cachedFileList) {
+    files = cachedFileList
+  } else {
+    files = await fastGlob(['**/*.md', '**/*.mdx'], {
+      cwd: docsDir,
+      absolute: true,
+      suppressErrors: true,
+      followSymbolicLinks: false,
+    })
+    cachedFileList = files
+  }
 
   // Prune cache entries for deleted files
   docCache.pruneStale(new Set(files))
@@ -197,8 +205,6 @@ function generateI18nFallbacks(
   }
 
   for (const locale of allLocales) {
-    if (locale === defaultLocale) continue
-
     const localePaths = routesByLocale.get(locale) || new Set<string>()
 
     for (const defRoute of defaultRoutes) {
@@ -207,8 +213,12 @@ function generateI18nFallbacks(
         defaultLocale,
         locale,
         basePath,
+        config,
       )
 
+      // Skip if the path is already the same (e.g. for default locale unprefixed)
+      if (targetPath === defRoute.path) continue
+
       if (!localePaths.has(targetPath)) {
         fallbackRoutes.push({
           ...defRoute,
@@ -231,15 +241,26 @@ function computeLocalizedPath(
   defaultLocale: string,
   targetLocale: string,
   basePath: string,
+  config?: BoltdocsConfig,
 ): string {
   const cacheKey = `${path}:${targetLocale}`
   const cached = localizedPathCache.get(cacheKey)
   if (cached) return cached
 
   let prefix = basePath
-  const versionMatch = path.match(new RegExp(`^${basePath}/(v[0-9]+)`))
-  if (versionMatch) {
-    prefix += '/' + versionMatch[1]
+  if (config?.versions) {
+    const vPrefix = config.versions.prefix || ''
+    for (const vConfig of config.versions.versions) {
+      const fullVPath = vPrefix + vConfig.path
+      if (path.startsWith(`${basePath}/${fullVPath}`)) {
+        prefix += '/' + fullVPath
+        break
+      }
+      if (path.startsWith(`${basePath}/${vConfig.path}`)) {
+        prefix += '/' + vConfig.path
+        break
+      }
+    }
   }
 
   let pathAfterVersion = path.substring(prefix.length)

package/src/node/routes/parser.ts

@@ -59,8 +59,15 @@ export function parseDocFile(
   // Level 1: Check for version
   if (config?.versions && parts.length > 0) {
     const potentialVersion = parts[0]
-    if (config.versions.versions[potentialVersion]) {
-      version = potentialVersion
+    const prefix = config.versions.prefix || ''
+
+    const versionMatch = config.versions.versions.find((v) => {
+      const fullPath = prefix + v.path
+      return potentialVersion === fullPath || potentialVersion === v.path
+    })
+
+    if (versionMatch) {
+      version = versionMatch.path
       parts = parts.slice(1)
     }
   }
@@ -124,8 +131,7 @@ export function parseDocFile(
   const headings: { level: number; text: string; id: string }[] = []
   const headingsRegex = /^(#{2,4})\s+(.+)$/gm
 
-  let match
-  while ((match = headingsRegex.exec(content)) !== null) {
+  for (const match of content.matchAll(headingsRegex)) {
     const level = match[1].length
     const rawText = match[2]
       .replace(/\[([^\]]+)\]\([^\)]+\)/g, '$1') // Strip markdown links
@@ -160,7 +166,9 @@ export function parseDocFile(
     sanitizedDescription = plainExcerpt
   }
 
-  const sanitizedBadge = data.badge ? sanitizeHtml(String(data.badge)) : undefined
+  const sanitizedBadge = data.badge
+    ? sanitizeHtml(String(data.badge))
+    : undefined
   const icon = data.icon ? String(data.icon) : undefined
 
   // Extract full content as plain text for search indexing

package/src/node/search/index.ts

@@ -0,0 +1,55 @@
+import type { RouteMeta } from '../routes/types'
+
+export interface SearchDocument {
+  id: string
+  title: string
+  content: string
+  url: string
+  display: string
+  locale?: string
+  version?: string
+}
+
+/**
+ * Generates a flat list of searchable documents from the route metadata.
+ * Each page is indexed as a primary document, and its sections (headings)
+ * are indexed as secondary documents to provide granular search results.
+ */
+export function generateSearchData(routes: RouteMeta[]): SearchDocument[] {
+  const documents: SearchDocument[] = []
+
+  for (const route of routes) {
+    // 1. Index the main page
+    documents.push({
+      id: route.path,
+      title: route.title,
+      content: route._content || '',
+      url: route.path,
+      display: route.groupTitle
+        ? `${route.groupTitle} > ${route.title}`
+        : route.title,
+      locale: route.locale,
+      version: route.version,
+    })
+
+    // 2. Index headings as sub-documents for deep linking
+    if (route.headings) {
+      for (const heading of route.headings) {
+        // We find the content belonging to this heading?
+        // For now, indexing just the heading text and a bit of context is standard.
+        // Deep full-text mapping to specific headings is more complex.
+        documents.push({
+          id: `${route.path}#${heading.id}`,
+          title: heading.text,
+          content: `${heading.text} in ${route.title}`,
+          url: `${route.path}#${heading.id}`,
+          display: `${route.title} > ${heading.text}`,
+          locale: route.locale,
+          version: route.version,
+        })
+      }
+    }
+  }
+
+  return documents
+}

package/src/node/ssg/index.ts

@@ -1,7 +1,7 @@
 import fs from 'fs'
 import path from 'path'
 import { generateRoutes } from '../routes'
-import { escapeHtml } from '../utils'
+import { escapeHtml, getTranslated } from '../utils'
 import { fileURLToPath } from 'url'
 import { createRequire } from 'module'
 
@@ -27,8 +27,6 @@ const _require = createRequire(import.meta.url)
 export async function generateStaticPages(options: SSGOptions): Promise<void> {
   const { docsDir, docsDirName, outDir, config } = options
   const routes = await generateRoutes(docsDir, config)
-  const siteTitle = config?.themeConfig?.title || 'Boltdocs'
-  const siteDescription = config?.themeConfig?.description || ''
 
   // Resolve the SSR module (compiled by tsup)
   const ssrModulePath = path.resolve(_dirname, '../client/ssr.js')
@@ -50,14 +48,17 @@ export async function generateStaticPages(options: SSGOptions): Promise<void> {
         __esModule: true,
         default: function SSG_Virtual_Layout(props: any) {
           try {
-            const client = originalRequire.apply(this, [path.resolve(_dirname, '../client/index.js')])
-            const Comp = client.DefaultLayout || (({ children }: any) => children)
+            const client = originalRequire.apply(this, [
+              path.resolve(_dirname, '../client/index.js'),
+            ])
+            const Comp =
+              client.DefaultLayout || (({ children }: any) => children)
             const React = originalRequire.apply(this, ['react'])
             return React.createElement(Comp, props)
           } catch (e) {
             return props.children
           }
-        }
+        },
       }
     }
     return originalRequire.apply(this, [id, ...args])
@@ -79,6 +80,10 @@ export async function generateStaticPages(options: SSGOptions): Promise<void> {
   // Generate an HTML file for each route concurrently
   await Promise.all(
     routes.map(async (route) => {
+      const siteTitle =
+        getTranslated(config?.theme?.title, route.locale) || 'Boltdocs'
+      const siteDescription =
+        getTranslated(config?.theme?.description, route.locale) || ''
       const pageTitle = `${route.title} | ${siteTitle}`
       const pageDescription = route.description || siteDescription
 
@@ -111,7 +116,10 @@ export async function generateStaticPages(options: SSGOptions): Promise<void> {
           'utf-8',
         )
       } catch (e: any) {
-        console.error(`[boltdocs] Error SSR rendering route ${route.path}:`, e ? e.stack || e : e)
+        console.error(
+          `[boltdocs] Error SSR rendering route ${route.path}:`,
+          e ? e.stack || e : e,
+        )
       }
     }),
   )

package/src/node/ssg/robots.ts

@@ -19,20 +19,23 @@ export function generateRobotsTxt(config: BoltdocsConfig): string {
       allow: '/',
     },
   ]
-  const sitemaps = (robots as any).sitemaps || (siteUrl ? [`${siteUrl}/sitemap.xml`] : [])
+  const sitemaps =
+    (robots as any).sitemaps || (siteUrl ? [`${siteUrl}/sitemap.xml`] : [])
 
   let content = ''
 
   for (const rule of rules) {
     content += `User-agent: ${rule.userAgent}\n`
-    
+
     if (rule.disallow) {
-      const disallows = Array.isArray(rule.disallow) ? rule.disallow : [rule.disallow]
+      const disallows = Array.isArray(rule.disallow)
+        ? rule.disallow
+        : [rule.disallow]
       for (const d of disallows) {
         content += `Disallow: ${d}\n`
       }
     }
-    
+
     if (rule.allow) {
       const allows = Array.isArray(rule.allow) ? rule.allow : [rule.allow]
       for (const a of allows) {

package/src/node/utils.ts

@@ -72,8 +72,13 @@ export function parseFrontmatter(filePath: string): {
   content: string
 } {
   const raw = fs.readFileSync(filePath, 'utf-8')
-  const { data, content } = matter(raw)
-  return { data, content }
+  try {
+    const { data, content } = matter(raw)
+    return { data, content }
+  } catch (e) {
+    // If frontmatter is malformed (e.g. while editing), return empty data and raw content
+    return { data: {}, content: raw }
+  }
 }
 
 /**
@@ -169,3 +174,28 @@ export function stripHtmlTags(html: string): string {
 export function capitalize(str: string): string {
   return str.charAt(0).toUpperCase() + str.slice(1)
 }
+
+/**
+ * Retrieves the correct translation from a value that can be either
+ * a simple string or a map of locale-specific strings.
+ * Node-side version for SSG and config resolution.
+ *
+ * @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/tsup.config.ts

@@ -20,6 +20,7 @@ const commonConfig: Options = {
     'virtual:boltdocs-layout',
     'virtual:boltdocs-mdx-components',
     'virtual:boltdocs-entry',
+    /^virtual:boltdocs-/, // Broad catch-all for any virtual modules
   ],
 }
 
@@ -41,8 +42,12 @@ export default defineConfig([
     platform: 'browser',
     entry: {
       'client/index': 'src/client/index.ts',
-      'client/hooks/index': 'src/client/hooks/index.ts',
-      'client/components/mdx/index': 'src/client/components/mdx/index.ts',
+      'client/types': 'src/client/types.ts',
+      'hooks/index': 'src/client/hooks/index.ts',
+      'primitives/index': 'src/client/components/primitives/index.ts',
+      'base-ui/index': 'src/client/components/ui-base/index.ts',
+      'mdx/index': 'src/client/components/mdx/index.ts',
+      'integrations/index': 'src/client/integrations/index.ts',
     },
   },
   // SSR Build (Needs Node platform for Server-Side Rendering)

package/dist/chunk-52MVMZWS.mjs

@@ -1 +0,0 @@
-var v=Object.defineProperty;var S=(t,i)=>{for(var e in i)v(t,e,{get:i[e],enumerable:!0})};import{createContext as x,use as b}from"react";var y=x(null);function P(){let t=b(y);if(!t)throw new Error("useConfig must be used within a ConfigProvider");return t}import{useLocation as R}from"react-router-dom";function z(t){let i=R(),e=P();if(!e||typeof t!="string"||!e.i18n&&!e.versions)return t;let n="/docs";if(!t.startsWith(n))return t;let r=i.pathname.substring(n.length).split("/").filter(Boolean),u=e.versions?.defaultVersion,c=e.i18n?.defaultLocale,o=0;e.versions&&r.length>o&&e.versions.versions[r[o]]&&(u=r[o],o++),e.i18n&&r.length>o&&e.i18n.locales[r[o]]&&(c=r[o]);let s=t.substring(n.length).split("/").filter(Boolean),l=0,d=!1,m=!1;e.versions&&s.length>l&&e.versions.versions[s[l]]&&(d=!0,l++),e.i18n&&s.length>l&&e.i18n.locales[s[l]]&&(m=!0,l++);let C=s.slice(l),a=[];e.versions&&(d?a.push(s[0]):u&&a.push(u)),e.i18n&&(m?a.push(s[d?1:0]):c&&a.push(c)),a.push(...C);let f=`${n}/${a.join("/")}`;return f.endsWith("/")&&(f=f.slice(0,-1)),f===n?n:f}import{createContext as L,use as T,useCallback as k,useRef as w}from"react";import{jsx as B}from"react/jsx-runtime";var g=L({preload:()=>{},routes:[]});function K(){return T(g)}function N({routes:t,modules:i,children:e}){let n=w(null),h=k(r=>{n.current&&clearTimeout(n.current),n.current=setTimeout(()=>{let u=r.split("#")[0].split("?")[0],c=t.find(o=>o.path===u||u==="/"&&o.path==="");if(c?.filePath){let o=Object.keys(i).find(p=>p.endsWith("/"+c.filePath));o&&i[o]().catch(p=>{console.error(`[boltdocs] Failed to preload route ${r}:`,p)})}},100)},[t,i]);return B(g.Provider,{value:{preload:h,routes:t},children:e})}export{S as a,y as b,P as c,z as d,K as e,N as f};