boltdocs 2.1.1 → 2.2.0

package/src/node/mdx/highlighter.ts

@@ -0,0 +1,47 @@
+import { createHighlighter } from 'shiki'
+import type { Highlighter } from 'shiki'
+
+let shikiHighlighter: Highlighter | null = null
+
+/**
+ * Retrieves or initializes the Shiki highlighter instance.
+ * Supports dual-theme configurations (light/dark).
+ *
+ * @param codeTheme - Theme configuration (string for single, object for dual).
+ * @returns A promise resolving to the highlighter instance.
+ */
+export async function getShikiHighlighter(codeTheme: any) {
+  if (shikiHighlighter) return shikiHighlighter
+
+  const themes =
+    typeof codeTheme === 'object'
+      ? [codeTheme.light, codeTheme.dark]
+      : [codeTheme ?? 'github-dark']
+
+  // Fallbacks for standard themes
+  ;['github-light', 'github-dark'].forEach((t) => {
+    if (!themes.includes(t)) themes.push(t)
+  })
+
+  // Initialize with a core set of languages first to speed up boot
+  shikiHighlighter = await createHighlighter({
+    themes,
+    langs: [
+      'tsx',
+      'jsx',
+      'ts',
+      'js',
+      'json',
+      'md',
+      'mdx',
+      'css',
+      'html',
+      'bash',
+      'sh',
+      'yaml',
+      'yml',
+    ],
+  })
+
+  return shikiHighlighter
+}

package/src/node/mdx/index.ts

@@ -0,0 +1,114 @@
+import mdxPlugin from '@mdx-js/rollup'
+import remarkGfm from 'remark-gfm'
+import remarkFrontmatter from 'remark-frontmatter'
+import rehypeSlug from 'rehype-slug'
+import type { Plugin } from 'vite'
+import crypto from 'crypto'
+
+import type { BoltdocsConfig } from '../config'
+import { mdxCache, MDX_PLUGIN_VERSION } from './cache'
+import { remarkShiki } from './remark-shiki'
+import { rehypeShiki } from './rehype-shiki'
+
+let mdxCacheLoaded = false
+let hits = 0
+let total = 0
+
+/**
+ * Configures the MDX compiler for Vite using `@mdx-js/rollup`.
+ * Includes standard remark and rehype plugins for GitHub Flavored Markdown (GFM),
+ * frontmatter extraction, and auto-linking headers.
+ *
+ * Also wraps the plugin with a persistent cache to avoid re-compiling unchanged MDX files.
+ *
+ * @param config - The Boltdocs configuration containing custom plugins
+ * @param compiler - The MDX compiler plugin (for testing)
+ * @returns A Vite plugin configured for MDX parsing with caching
+ */
+export function boltdocsMdxPlugin(
+  config?: BoltdocsConfig,
+  compiler = mdxPlugin,
+): Plugin {
+  const extraRemarkPlugins =
+    config?.plugins?.flatMap((p) => p.remarkPlugins || []) || []
+  const extraRehypePlugins =
+    config?.plugins?.flatMap((p) => p.rehypePlugins || []) || []
+
+  const baseMdxPlugin = compiler({
+    remarkPlugins: [
+      remarkGfm,
+      remarkFrontmatter,
+      [remarkShiki, config],
+      ...(extraRemarkPlugins as any[]),
+    ],
+    rehypePlugins: [
+      rehypeSlug,
+      [rehypeShiki, config],
+      ...(extraRehypePlugins as any[]),
+    ],
+    jsxRuntime: 'automatic',
+    providerImportSource: '@mdx-js/react',
+  }) as Plugin
+
+  return {
+    ...baseMdxPlugin,
+    name: 'vite-plugin-boltdocs-mdx',
+
+    async buildStart() {
+      hits = 0
+      total = 0
+      if (!mdxCacheLoaded) {
+        mdxCache.load()
+        mdxCacheLoaded = true
+      }
+      // @ts-ignore
+      if (baseMdxPlugin.buildStart) {
+        // @ts-ignore
+        await baseMdxPlugin.buildStart.call(this)
+      }
+    },
+
+    async transform(code, id, options) {
+      if (!id.endsWith('.md') && !id.endsWith('.mdx')) {
+        // @ts-ignore
+        return baseMdxPlugin.transform?.call(this, code, id, options)
+      }
+
+      console.log(`[boltdocs] Transforming MDX: ${id}`)
+      total++
+      // Create a cache key based on path, content, and plugin version
+      const contentHash = crypto.createHash('md5').update(code).digest('hex')
+      const cacheKey = `${id}:${contentHash}:${MDX_PLUGIN_VERSION}`
+
+      const cached = mdxCache.get(cacheKey)
+      if (cached) {
+        hits++
+        return { code: cached, map: null }
+      }
+
+      // @ts-ignore
+      const result = await baseMdxPlugin.transform.call(this, code, id, options)
+
+      if (result && typeof result === 'object' && result.code) {
+        mdxCache.set(cacheKey, result.code)
+      }
+
+      return result
+    },
+
+    async buildEnd() {
+      if (total > 0) {
+        console.log(
+          `[boltdocs] MDX Cache Performance: ${hits}/${total} hits (${Math.round((hits / total) * 100) || 0}%)`,
+        )
+      }
+      mdxCache.save()
+      await mdxCache.flush()
+      // @ts-ignore
+      if (baseMdxPlugin.buildEnd) {
+        // @ts-ignore
+        await baseMdxPlugin.buildEnd.call(this)
+      }
+    },
+  }
+}

package/src/node/mdx/rehype-shiki.ts

@@ -0,0 +1,53 @@
+import { visit } from 'unist-util-visit'
+import type { BoltdocsConfig } from '../config'
+import { getShikiHighlighter } from './highlighter'
+
+/**
+ * Custom rehype plugin to perform syntax highlighting at build time for
+ * standard Markdown code blocks.
+ *
+ * Injects 'data-highlighted="true"' and 'highlightedHtml' into the 'pre' tag properties,
+ * which are then consumed by the client-side CodeBlock component.
+ *
+ * @param config - The Boltdocs configuration
+ * @returns A rehype plugin function
+ */
+export function rehypeShiki(config?: BoltdocsConfig) {
+  return async (tree: any) => {
+    const codeTheme = config?.theme?.codeTheme || {
+      light: 'github-light',
+      dark: 'github-dark',
+    }
+    const highlighter = await getShikiHighlighter(codeTheme)
+
+    visit(tree, 'element', (node: any) => {
+      // Handle standard Markdown code blocks
+      if (node.tagName === 'pre' && node.children?.[0]?.tagName === 'code') {
+        const codeNode = node.children[0]
+        const className = codeNode.properties?.className || []
+        const langMatch = className.find((c: string) =>
+          c.startsWith('language-'),
+        )
+        const lang = langMatch ? langMatch.slice(9) : 'text'
+        const code = codeNode.children[0]?.value || ''
+
+        const options: any = { lang }
+        if (typeof codeTheme === 'object') {
+          options.themes = {
+            light: codeTheme.light,
+            dark: codeTheme.dark,
+          }
+        } else {
+          options.theme = codeTheme
+        }
+
+        const html = highlighter.codeToHtml(code, options)
+
+        // Inject highlighted HTML and mark as highlighted for CodeBlock component
+        node.properties.dataHighlighted = 'true'
+        node.properties.highlightedHtml = html
+        node.children = []
+      }
+    })
+  }
+}

package/src/node/mdx/remark-shiki.ts

@@ -0,0 +1,61 @@
+import { visit } from 'unist-util-visit'
+import type { BoltdocsConfig } from '../config'
+import { getShikiHighlighter } from './highlighter'
+
+/**
+ * Custom remark plugin to highlight code in ComponentPreview components.
+ * This runs before rehype, ensuring that the 'highlightedHtml' prop is correctly
+ * attached to the MDX component as a JSX attribute.
+ *
+ * Supports both string literals and MDX expression values (template literals)
+ * for the 'code' attribute.
+ *
+ * @param config - The Boltdocs configuration
+ * @returns A remark plugin function
+ */
+export function remarkShiki(config?: BoltdocsConfig) {
+  return async (tree: any) => {
+    const codeTheme = config?.theme?.codeTheme ?? {
+      light: 'github-light',
+      dark: 'github-dark',
+    }
+    const highlighter = await getShikiHighlighter(codeTheme)
+
+    visit(tree, ['mdxJsxFlowElement', 'mdxJsxTextElement'], (node: any) => {
+      if (node.name !== 'ComponentPreview') return
+
+      const codeAttr = node.attributes?.find((a: any) => a.name === 'code')
+      let code = ''
+
+      if (codeAttr) {
+        if (typeof codeAttr.value === 'string') {
+          code = codeAttr.value
+        } else if (codeAttr.value?.type === 'mdxJsxAttributeValueExpression') {
+          const expr = codeAttr.value.value ?? ''
+          code = expr.match(/^[`'"](.+)[`'"]$/)?.[1] ?? expr
+        }
+      }
+
+      if (!code) return
+
+      const options: any =
+        typeof codeTheme === 'object'
+          ? {
+              themes: { light: codeTheme.light, dark: codeTheme.dark },
+              lang: 'tsx',
+            }
+          : { theme: codeTheme, lang: 'tsx' }
+
+      const html = highlighter.codeToHtml(code, options)
+
+      node.attributes = (node.attributes ?? []).filter(
+        (a: any) => a.name !== 'highlightedHtml',
+      )
+      node.attributes.push({
+        type: 'mdxJsxAttribute',
+        name: 'highlightedHtml',
+        value: html,
+      })
+    })
+  }
+}

package/src/node/plugin/html.ts

@@ -4,7 +4,7 @@ import type { BoltdocsConfig } from '../config'
  * Provides a default HTML template if none is found in the project root.
  */
 export function getHtmlTemplate(config: BoltdocsConfig): string {
-  const title = config.theme?.title || config.themeConfig?.title || 'Boltdocs'
+  const title = config.theme?.title || 'Boltdocs'
   return `<!doctype html>
 <html lang="en">
 <head>
@@ -27,7 +27,7 @@ export function getHtmlTemplate(config: BoltdocsConfig): string {
  * @returns {string} The modified HTML string with injected tags
  */
 export function injectHtmlMeta(html: string, config: BoltdocsConfig): string {
-  const theme = config.theme || config.themeConfig
+  const theme = config.theme
   const title = theme?.title || 'Boltdocs'
   const description = theme?.description || ''
 
@@ -46,12 +46,16 @@ export function injectHtmlMeta(html: string, config: BoltdocsConfig): string {
     `<meta name="description" content="${description}">`,
     `<meta property="og:title" content="${title}">`,
     `<meta property="og:description" content="${description}">`,
-    theme?.ogImage ? `<meta property="og:image" content="${theme.ogImage}">` : '',
+    theme?.ogImage
+      ? `<meta property="og:image" content="${theme.ogImage}">`
+      : '',
     `<meta property="og:type" content="website">`,
     `<meta name="twitter:card" content="summary_large_image">`,
     `<meta name="twitter:title" content="${title}">`,
     `<meta name="twitter:description" content="${description}">`,
-    theme?.ogImage ? `<meta name="twitter:image" content="${theme.ogImage}">` : '',
+    theme?.ogImage
+      ? `<meta name="twitter:image" content="${theme.ogImage}">`
+      : '',
     `<meta name="generator" content="Boltdocs">`,
   ]
     .filter(Boolean)

package/src/node/plugin/index.ts

@@ -11,7 +11,6 @@ import { injectHtmlMeta, getHtmlTemplate } from './html'
 import { generateRobotsTxt } from '../ssg/robots'
 import fs from 'fs'
 
-
 export * from './types'
 
 /**
@@ -55,7 +54,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 +88,40 @@ 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 || ''
 
+          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') &&
-            !url.includes('.') // Simple check for assets
+            !isAsset &&
+            isDocRoute
           ) {
-            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
-            }
+            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,89 @@ 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'))
@@ -211,7 +261,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,

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,17 @@ 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 +133,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