boltdocs 2.1.1 → 2.3.0

package/src/node/cli/ui.ts

@@ -0,0 +1,54 @@
+/**
+ * ANSI Escape sequences for terminal coloring and styling.
+ * Used to provide a premium and consistent CLI experience.
+ */
+export const colors = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  gray: '\x1b[90m',
+}
+
+/**
+ * Formats a message with the boltdocs prefix and provided styling.
+ *
+ * @param message - The content to log
+ * @param style - Optional ANSI style prefix
+ * @returns The formatted string
+ */
+export function formatLog(message: string, style: string = ''): string {
+  return `${style}${colors.bold}[boltdocs]${colors.reset} ${message}${colors.reset}`
+}
+
+/**
+ * Logs a standard informational message to the console.
+ *
+ * @param message - The message to display
+ */
+export function info(message: string) {
+  console.log(formatLog(message))
+}
+
+/**
+ * Logs an error message to the console with red styling.
+ *
+ * @param message - The error description
+ * @param error - Optional error object for stack tracing
+ */
+export function error(message: string, error?: any) {
+  console.error(formatLog(message, colors.red))
+  if (error) console.error(error)
+}
+
+/**
+ * Logs a success message to the console with green styling.
+ *
+ * @param message - The success description
+ */
+export function success(message: string) {
+  console.log(formatLog(message, colors.green))
+}

package/src/node/cli-entry.ts

@@ -1,24 +1,24 @@
 #!/usr/bin/env node
-import cac from "cac";
-import { devAction, buildAction, previewAction } from "./cli";
+import cac from 'cac'
+import {
+  devAction,
+  buildAction,
+  previewAction,
+  doctorAction,
+} from './cli/index'
 
-const cli = cac("boltdocs");
+const cli = cac('boltdocs')
 
-cli
-  .command("[root]", "Start development server")
-  .alias("dev")
-  .action(devAction);
+cli.command('[root]', 'Start development server').alias('dev').action(devAction)
 
-cli
-  .command("build [root]", "Build for production")
-  .action(buildAction);
+cli.command('build [root]', 'Build for production').action(buildAction)
 
-cli
-  .command("preview [root]", "Preview production build")
-  .action(previewAction);
+cli.command('preview [root]', 'Preview production build').action(previewAction)
 
-cli.help();
+cli.command('doctor [root]', 'Check documentation health').action(doctorAction)
+
+cli.help()
 // This will be replaced at build time or package publishing, but hardcoded to 2.0.0 for now
-cli.version("2.0.0");
+cli.version('2.0.0')
 
-cli.parse();
+cli.parse()

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')

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/entry.ts

@@ -19,7 +19,7 @@ export function generateEntryCode(
   const homeImport = options.homePage
     ? `import HomePage from '${normalizePath(options.homePage)}';`
     : ''
-  
+
   // Auto-import index.css if it exists
   const cssPath = path.resolve(process.cwd(), 'index.css')
   const cssImport = fs.existsSync(cssPath) ? "import './index.css';" : ''

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)