boltdocs 1.10.2 → 2.0.0

package/src/node/config.ts

@@ -1,16 +1,15 @@
-import path from "path";
-import { pathToFileURL } from "url";
-import fs from "fs";
-import type { Plugin as VitePlugin } from "vite";
+import path from 'path'
+import fs from 'fs'
+import { loadConfigFromFile, type Plugin as VitePlugin } from 'vite'
 
 /**
  * Represents a single social link in the configuration.
  */
 export interface BoltdocsSocialLink {
-  /** Identifier for the icon (e.g., 'github', 'twitter') */
-  icon: "discord" | "x" | string;
+  /** Identifier for the icon (e.g., 'github') */
+  icon: 'discord' | 'x' | 'github' | 'bluesky' | string
   /** The URL the social link points to */
-  link: string;
+  link: string
 }
 
 /**
@@ -18,7 +17,7 @@ export interface BoltdocsSocialLink {
  */
 export interface BoltdocsFooterConfig {
   /** Text to display in the footer (HTML is supported) */
-  text?: string;
+  text?: string
 }
 
 /**
@@ -26,77 +25,64 @@ export interface BoltdocsFooterConfig {
  */
 export interface BoltdocsThemeConfig {
   /** The global title of the documentation site */
-  title?: string;
+  title?: string
   /** The global description of the site (used for SEO) */
-  description?: string;
-  /** URL path to the site logo */
-  logo?: string;
+  description?: string
+  /** URL path to the site logo or an object for light/dark versions */
+  logo?:
+    | string
+    | {
+        dark: string
+        light: string
+        alt?: string
+        width?: number
+        height?: number
+      }
   /** Items to display in the top navigation bar */
   navbar?: Array<{
-    /** Text to display (alias for text) */
-    label?: string;
     /** Text to display */
-    text?: string;
-    /** URL path or external link (alias for link) */
-    to?: string;
-    /** URL path or external link (alias for link) */
-    href?: string;
+    label: string
     /** URL path or external link */
-    link?: string;
-    /** Alignment of the item in the navbar */
-    position?: "left" | "right";
-  }>;
+    href: string
+    /** Nested items for NavigationMenu */
+    items?: Array<{ label: string; href: string }>
+  }>
   /** Items to display in the sidebar, organized optionally by group URLs */
-  sidebar?: Record<string, Array<{ text: string; link: string }>>;
+  sidebar?: Record<string, Array<{ text: string; link: string }>>
   /** Social links to display in the navigation bar */
-  socialLinks?: BoltdocsSocialLink[];
+  socialLinks?: BoltdocsSocialLink[]
   /** Site footer configuration */
-  footer?: BoltdocsFooterConfig;
+  footer?: BoltdocsFooterConfig
   /** Whether to show breadcrumbs navigation (default: true) */
-  breadcrumbs?: boolean;
-  /** Path to a custom CSS file that overrides theme variables */
-  customCss?: string;
+  breadcrumbs?: boolean
   /** URL template for 'Edit this page'. Use :path as a placeholder. */
-  editLink?: string;
+  editLink?: string
   /** URL for the 'Community help' link. */
-  communityHelp?: string;
+  communityHelp?: string
   /** The current version of the project (e.g., 'v2.8.9'). Displayed in the Navbar. */
-  version?: string;
+  version?: string
   /** The GitHub repository in the format 'owner/repo' to fetch and display star count. */
-  githubRepo?: string;
+  githubRepo?: string
   /** Whether to show the 'Powered by LiteDocs' badge in the sidebar (default: true) */
-  poweredBy?: boolean;
-  /** Whether to show a preview tooltip on internal links hover (default: true) */
-  linkPreview?: boolean;
-  /** Granular layout customization props */
-  layoutProps?: {
-    navbar?: any;
-    sidebar?: any;
-    toc?: any;
-    background?: any;
-    head?: any;
-    breadcrumbs?: any;
-    className?: string;
-    style?: any;
-  };
+  poweredBy?: boolean
   /**
    * 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: string; icon?: string }>
   /**
    * The syntax highlighting theme for code blocks.
    * Supports any Shiki theme name (e.g., 'github-dark', 'one-dark-pro', 'aurora-x').
    * Can also be an object for multiple themes (e.g., { light: 'github-light', dark: 'github-dark' }).
-   * Default: 'one-dark-pro'
+   * Default: { light: 'github-light', dark: 'one-dark-pro' }
    */
-  codeTheme?: string | Record<string, string>;
+  codeTheme?: string | { light: string; dark: string }
   /**
    * Configuration for the 'Copy Markdown' button.
    * Can be a boolean or an object with text and icon.
    * Default: true
    */
-  copyMarkdown?: boolean | { text?: string; icon?: string };
+  copyMarkdown?: boolean | { text?: string; icon?: string }
 }
 
 /**
@@ -104,9 +90,9 @@ export interface BoltdocsThemeConfig {
  */
 export interface BoltdocsI18nConfig {
   /** The default locale (e.g., 'en') */
-  defaultLocale: string;
+  defaultLocale: string
   /** Available locales and their display names (e.g., { en: 'English', es: 'Español' }) */
-  locales: Record<string, string>;
+  locales: Record<string, string>
 }
 
 /**
@@ -114,9 +100,9 @@ export interface BoltdocsI18nConfig {
  */
 export interface BoltdocsVersionsConfig {
   /** The default version (e.g., 'v2') */
-  defaultVersion: string;
+  defaultVersion: string
   /** Available versions and their display names (e.g., { v1: 'Version 1.x', v2: 'Version 2.x' }) */
-  versions: Record<string, string>;
+  versions: Record<string, string>
 }
 
 /**
@@ -124,17 +110,30 @@ export interface BoltdocsVersionsConfig {
  */
 export interface BoltdocsPlugin {
   /** A unique name for the plugin */
-  name: string;
+  name: string
   /** Whether to run this plugin before or after default ones (optional) */
-  enforce?: "pre" | "post";
+  enforce?: 'pre' | 'post'
   /** Optional remark plugins to add to the MDX pipeline */
-  remarkPlugins?: any[];
+  remarkPlugins?: unknown[]
   /** Optional rehype plugins to add to the MDX pipeline */
-  rehypePlugins?: any[];
+  rehypePlugins?: unknown[]
   /** Optional Vite plugins to inject into the build process */
-  vitePlugins?: VitePlugin[];
+  vitePlugins?: VitePlugin[]
   /** Optional custom React components to register in MDX. Map of Name -> Module Path. */
-  components?: Record<string, string>;
+  components?: Record<string, string>
+}
+
+/**
+ * Configuration for external integrations (e.g., CodeSandbox).
+ */
+export interface BoltdocsIntegrationsConfig {
+  /** CodeSandbox integration settings */
+  sandbox?: {
+    /** Whether to enable the "Open in Sandbox" button in CodeBlocks */
+    enable?: boolean
+    /** Default options for the sandbox (files, dependencies, etc.) */
+    config?: Record<string, unknown>
+  }
 }
 
 /**
@@ -142,24 +141,35 @@ export interface BoltdocsPlugin {
  */
 export interface BoltdocsConfig {
   /** The base URL of the site, used for generating the sitemap */
-  siteUrl?: string;
+  siteUrl?: string
   /** Configuration pertaining to the UI and appearance */
-  themeConfig?: BoltdocsThemeConfig;
+  themeConfig?: BoltdocsThemeConfig
   /** The root directory containing markdown documentation files (default: 'docs') */
-  docsDir?: string;
+  docsDir?: string
   /** Configuration for internationalization */
-  i18n?: BoltdocsI18nConfig;
+  i18n?: BoltdocsI18nConfig
   /** Configuration for documentation versioning */
-  versions?: BoltdocsVersionsConfig;
+  versions?: BoltdocsVersionsConfig
   /** Custom plugins for extending functionality */
-  plugins?: BoltdocsPlugin[];
+  plugins?: BoltdocsPlugin[]
+  /** Map of custom external route paths to component file paths */
+  external?: Record<string, string>
+  /** External integrations configuration */
+  integrations?: BoltdocsIntegrationsConfig
 }
 
 export const CONFIG_FILES = [
-  "boltdocs.config.js",
-  "boltdocs.config.mjs",
-  "boltdocs.config.ts",
-];
+  'boltdocs.config.js',
+  'boltdocs.config.mjs',
+  'boltdocs.config.ts',
+]
+
+/**
+ * Small helper to handle partial config objects from user input.
+ */
+interface RawUserConfig
+  extends Partial<BoltdocsConfig>,
+    Partial<BoltdocsThemeConfig> {}
 
 /**
  * Loads user's configuration file (e.g., `boltdocs.config.js` or `boltdocs.config.ts`) if it exists,
@@ -173,53 +183,99 @@ export async function resolveConfig(
   docsDir: string,
   root: string = process.cwd(),
 ): Promise<BoltdocsConfig> {
-  const projectRoot = root;
+  const projectRoot = root
 
   const defaults: BoltdocsConfig = {
     docsDir: path.resolve(docsDir),
     themeConfig: {
-      title: "Boltdocs",
-      description: "A Vite documentation framework",
+      title: 'Boltdocs',
+      description: 'A Vite documentation framework',
       navbar: [
-        { text: "Home", link: "/" },
-        { text: "Documentation", link: "/docs" },
+        { label: 'Home', href: '/' },
+        { label: 'Documentation', href: '/docs' },
       ],
+      codeTheme: {
+        light: 'github-light',
+        dark: 'github-dark',
+      },
+      poweredBy: true,
+      breadcrumbs: true,
     },
-  };
+  }
+
+  let userConfig: RawUserConfig = {}
 
   // Try to load user config
   for (const filename of CONFIG_FILES) {
-    const configPath = path.resolve(projectRoot, filename);
+    const configPath = path.resolve(projectRoot, filename)
     if (fs.existsSync(configPath)) {
       try {
-        // Add a timestamp query parameter to bust the ESM cache in dev
-        const isTest =
-          process.env.NODE_ENV === "test" || (global as any).__vitest_worker__;
-        const fileUrl =
-          pathToFileURL(configPath).href + (isTest ? "" : "?t=" + Date.now());
-        const mod = await import(fileUrl);
-        const userConfig = mod.default || mod;
-
-        // Merge user themeConfig into defaults
-        // Support new format where user exports BoltdocsConfig directly
-        const userThemeConfig = userConfig.themeConfig || userConfig;
-
-        return {
-          docsDir: path.resolve(docsDir),
-          themeConfig: {
-            ...defaults.themeConfig,
-            ...userThemeConfig,
-          },
-          i18n: userConfig.i18n,
-          versions: userConfig.versions,
-          siteUrl: userConfig.siteUrl,
-          plugins: userConfig.plugins || [],
-        };
+        const loaded = await loadConfigFromFile(
+          { command: 'serve', mode: 'development' },
+          configPath,
+          projectRoot,
+        )
+        if (loaded) {
+          userConfig = loaded.config as RawUserConfig
+          break
+        }
       } catch (e) {
-        console.warn(`[boltdocs] Failed to load config from ${filename}:`, e);
+        console.warn(`[boltdocs] Failed to load config from ${filename}:`, e)
       }
     }
   }
 
-  return defaults;
+  // Robust merging strategy
+  const themeConfigFromTop: BoltdocsThemeConfig = {
+    title: userConfig.title,
+    description: userConfig.description,
+    logo: userConfig.logo,
+    navbar: userConfig.navbar,
+    sidebar: userConfig.sidebar,
+    socialLinks: userConfig.socialLinks,
+    footer: userConfig.footer,
+    githubRepo: userConfig.githubRepo,
+    tabs: userConfig.tabs,
+  }
+
+  // User can define properties at top level or inside themeConfig
+  const userThemeConfig: BoltdocsThemeConfig = {
+    ...themeConfigFromTop,
+    ...(userConfig.themeConfig || {}),
+  }
+
+  // Clean undefined properties
+  const cleanThemeConfig = Object.fromEntries(
+    Object.entries(userThemeConfig).filter(([_, v]) => v !== undefined),
+  ) as BoltdocsThemeConfig
+
+  // Transform old navbar items if necessary
+  if (cleanThemeConfig.navbar) {
+    cleanThemeConfig.navbar = cleanThemeConfig.navbar.map((item: any) => ({
+      label: item.label || item.text || '',
+      href: item.href || item.link || item.to || '',
+      items: item.items?.map((sub: any) => ({
+        label: sub.label || sub.text || '',
+        href: sub.href || sub.link || sub.to || '',
+      })),
+    }))
+  }
+
+  return {
+    docsDir: path.resolve(docsDir),
+    themeConfig: {
+      ...defaults.themeConfig,
+      ...cleanThemeConfig,
+      codeTheme:
+        cleanThemeConfig.codeTheme ||
+        (userConfig.themeConfig || userConfig).codeTheme ||
+        defaults.themeConfig?.codeTheme,
+    },
+    i18n: userConfig.i18n,
+    versions: userConfig.versions,
+    siteUrl: userConfig.siteUrl,
+    plugins: userConfig.plugins || [],
+    external: userConfig.external,
+    integrations: userConfig.integrations,
+  }
 }

package/src/node/index.ts

@@ -1,21 +1,21 @@
-import { Plugin } from "vite";
-import { boltdocsPlugin } from "./plugin/index";
-import { boltdocsMdxPlugin } from "./mdx";
-import { BoltdocsPluginOptions } from "./plugin/index";
+import type { Plugin } from 'vite'
+import { boltdocsPlugin } from './plugin/index'
+import { boltdocsMdxPlugin } from './mdx'
+import type { BoltdocsPluginOptions } from './plugin/index'
 
-import { resolveConfig } from "./config";
+import { resolveConfig } from './config'
 
 export default async function boltdocs(
   options?: BoltdocsPluginOptions,
 ): Promise<Plugin[]> {
-  const docsDir = options?.docsDir || "docs";
-  const config = await resolveConfig(docsDir);
+  const docsDir = options?.docsDir || 'docs'
+  const config = await resolveConfig(docsDir)
 
-  return [...boltdocsPlugin(options, config), boltdocsMdxPlugin(config)];
+  return [...boltdocsPlugin(options, config), boltdocsMdxPlugin(config)]
 }
 
-export type { BoltdocsPluginOptions };
-export { generateStaticPages } from "./ssg";
-export type { SSGOptions } from "./ssg";
-export type { RouteMeta } from "./routes";
-export type { BoltdocsConfig, BoltdocsThemeConfig } from "./config";
+export type { BoltdocsPluginOptions }
+export { generateStaticPages } from './ssg'
+export type { SSGOptions } from './ssg'
+export type { RouteMeta } from './routes'
+export type { BoltdocsConfig, BoltdocsThemeConfig } from './config'