boltdocs 1.0.4 → 1.3.1

package/src/node/config.ts

@@ -1,185 +1,192 @@
-import path from "path";
-import { pathToFileURL } from "url";
-import fs from "fs";
-import 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;
-  /** The URL the social link points to */
-  link: string;
-}
-
-/**
- * Configuration for the site footer.
- */
-export interface BoltdocsFooterConfig {
-  /** Text to display in the footer (HTML is supported) */
-  text?: string;
-}
-
-/**
- * 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;
-  /** URL path to the site logo */
-  logo?: string;
-  /** Items to display in the top navigation bar */
-  navbar?: Array<{ text: string; link: string }>;
-  /** Items to display in the sidebar, organized optionally by group URLs */
-  sidebar?: Record<string, Array<{ text: string; link: string }>>;
-  /** Social links to display in the navigation bar */
-  socialLinks?: BoltdocsSocialLink[];
-  /** Site footer configuration */
-  footer?: BoltdocsFooterConfig;
-  /** Whether to show breadcrumbs navigation (default: true) */
-  breadcrumbs?: boolean;
-  /** Path to a custom CSS file that overrides theme variables */
-  customCss?: string;
-  /** URL template for 'Edit this page'. Use :path as a placeholder. */
-  editLink?: string;
-  /** URL for the 'Community help' link. */
-  communityHelp?: string;
-  /** The current version of the project (e.g., 'v2.8.9'). Displayed in the Navbar. */
-  version?: string;
-  /** The GitHub repository in the format 'owner/repo' to fetch and display star count. */
-  githubRepo?: string;
-  /** Whether to show the 'Powered by LiteDocs' badge in the sidebar (default: true) */
-  poweredBy?: boolean;
-  /** Granular layout customization props */
-  layoutProps?: {
-    navbar?: any;
-    sidebar?: any;
-    toc?: any;
-    background?: any;
-    head?: any;
-    breadcrumbs?: any;
-    className?: string;
-    style?: any;
-  };
-}
-
-/**
- * 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' }) */
-  locales: Record<string, string>;
-}
-
-/**
- * Configuration for documentation versioning.
- */
-export interface BoltdocsVersionsConfig {
-  /** The default version (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>;
-}
-
-/**
- * Defines a Boltdocs plugin that can extend the build process and client-side functionality.
- */
-export interface BoltdocsPlugin {
-  /** A unique name for the plugin */
-  name: string;
-  /** Whether to run this plugin before or after default ones (optional) */
-  enforce?: "pre" | "post";
-  /** Optional remark plugins to add to the MDX pipeline */
-  remarkPlugins?: any[];
-  /** Optional rehype plugins to add to the MDX pipeline */
-  rehypePlugins?: any[];
-  /** Optional Vite plugins to inject into the build process */
-  vitePlugins?: VitePlugin[];
-  /** Optional custom React components to register in MDX. Map of Name -> Module Path. */
-  components?: Record<string, string>;
-}
-
-/**
- * The root configuration object for Boltdocs.
- */
-export interface BoltdocsConfig {
-  /** The base URL of the site, used for generating the sitemap */
-  siteUrl?: string;
-  /** Configuration pertaining to the UI and appearance */
-  themeConfig?: BoltdocsThemeConfig;
-  /** The root directory containing markdown documentation files (default: 'docs') */
-  docsDir?: string;
-  /** Configuration for internationalization */
-  i18n?: BoltdocsI18nConfig;
-  /** Configuration for documentation versioning */
-  versions?: BoltdocsVersionsConfig;
-  /** Custom plugins for extending functionality */
-  plugins?: BoltdocsPlugin[];
-}
-
-export const CONFIG_FILES = [
-  "boltdocs.config.js",
-  "boltdocs.config.mjs",
-  "boltdocs.config.ts",
-];
-
-/**
- * Loads user's configuration file (e.g., `boltdocs.config.js` or `boltdocs.config.ts`) if it exists,
- * merges it with the default configuration, and returns the final `BoltdocsConfig`.
- *
- * @param docsDir - The fallback/default documentation directory
- * @returns A promise resolving to the final merged configuration object
- */
-export async function resolveConfig(docsDir: string): Promise<BoltdocsConfig> {
-  const projectRoot = process.cwd();
-
-  const defaults: BoltdocsConfig = {
-    docsDir: path.resolve(docsDir),
-    themeConfig: {
-      title: "Boltdocs",
-      description: "A Vite documentation framework",
-      navbar: [
-        { text: "Home", link: "/" },
-        { text: "Documentation", link: "/docs" },
-      ],
-    },
-  };
-
-  // Try to load user config
-  for (const filename of CONFIG_FILES) {
-    const configPath = path.resolve(projectRoot, filename);
-    if (fs.existsSync(configPath)) {
-      try {
-        // Add a timestamp query parameter to bust the ESM cache
-        const fileUrl = pathToFileURL(configPath).href + "?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 || [],
-        };
-      } catch (e) {
-        console.warn(`[boltdocs] Failed to load config from ${filename}:`, e);
-      }
-    }
-  }
-
-  return defaults;
-}
+import path from "path";
+import { pathToFileURL } from "url";
+import fs from "fs";
+import 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;
+  /** The URL the social link points to */
+  link: string;
+}
+
+/**
+ * Configuration for the site footer.
+ */
+export interface BoltdocsFooterConfig {
+  /** Text to display in the footer (HTML is supported) */
+  text?: string;
+}
+
+/**
+ * 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;
+  /** URL path to the site logo */
+  logo?: string;
+  /** Items to display in the top navigation bar */
+  navbar?: Array<{ text: string; link: string }>;
+  /** Items to display in the sidebar, organized optionally by group URLs */
+  sidebar?: Record<string, Array<{ text: string; link: string }>>;
+  /** Social links to display in the navigation bar */
+  socialLinks?: BoltdocsSocialLink[];
+  /** Site footer configuration */
+  footer?: BoltdocsFooterConfig;
+  /** Whether to show breadcrumbs navigation (default: true) */
+  breadcrumbs?: boolean;
+  /** Path to a custom CSS file that overrides theme variables */
+  customCss?: string;
+  /** URL template for 'Edit this page'. Use :path as a placeholder. */
+  editLink?: string;
+  /** URL for the 'Community help' link. */
+  communityHelp?: string;
+  /** The current version of the project (e.g., 'v2.8.9'). Displayed in the Navbar. */
+  version?: string;
+  /** The GitHub repository in the format 'owner/repo' to fetch and display star count. */
+  githubRepo?: string;
+  /** Whether to show the 'Powered by LiteDocs' badge in the sidebar (default: true) */
+  poweredBy?: boolean;
+  /** Granular layout customization props */
+  layoutProps?: {
+    navbar?: any;
+    sidebar?: any;
+    toc?: any;
+    background?: any;
+    head?: any;
+    breadcrumbs?: any;
+    className?: string;
+    style?: any;
+  };
+  /**
+   * 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'
+   */
+  codeTheme?: string | Record<string, 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' }) */
+  locales: Record<string, string>;
+}
+
+/**
+ * Configuration for documentation versioning.
+ */
+export interface BoltdocsVersionsConfig {
+  /** The default version (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>;
+}
+
+/**
+ * Defines a Boltdocs plugin that can extend the build process and client-side functionality.
+ */
+export interface BoltdocsPlugin {
+  /** A unique name for the plugin */
+  name: string;
+  /** Whether to run this plugin before or after default ones (optional) */
+  enforce?: "pre" | "post";
+  /** Optional remark plugins to add to the MDX pipeline */
+  remarkPlugins?: any[];
+  /** Optional rehype plugins to add to the MDX pipeline */
+  rehypePlugins?: any[];
+  /** Optional Vite plugins to inject into the build process */
+  vitePlugins?: VitePlugin[];
+  /** Optional custom React components to register in MDX. Map of Name -> Module Path. */
+  components?: Record<string, string>;
+}
+
+/**
+ * The root configuration object for Boltdocs.
+ */
+export interface BoltdocsConfig {
+  /** The base URL of the site, used for generating the sitemap */
+  siteUrl?: string;
+  /** Configuration pertaining to the UI and appearance */
+  themeConfig?: BoltdocsThemeConfig;
+  /** The root directory containing markdown documentation files (default: 'docs') */
+  docsDir?: string;
+  /** Configuration for internationalization */
+  i18n?: BoltdocsI18nConfig;
+  /** Configuration for documentation versioning */
+  versions?: BoltdocsVersionsConfig;
+  /** Custom plugins for extending functionality */
+  plugins?: BoltdocsPlugin[];
+}
+
+export const CONFIG_FILES = [
+  "boltdocs.config.js",
+  "boltdocs.config.mjs",
+  "boltdocs.config.ts",
+];
+
+/**
+ * Loads user's configuration file (e.g., `boltdocs.config.js` or `boltdocs.config.ts`) if it exists,
+ * merges it with the default configuration, and returns the final `BoltdocsConfig`.
+ *
+ * @param docsDir - The fallback/default documentation directory
+ * @returns A promise resolving to the final merged configuration object
+ */
+export async function resolveConfig(docsDir: string): Promise<BoltdocsConfig> {
+  const projectRoot = process.cwd();
+
+  const defaults: BoltdocsConfig = {
+    docsDir: path.resolve(docsDir),
+    themeConfig: {
+      title: "Boltdocs",
+      description: "A Vite documentation framework",
+      navbar: [
+        { text: "Home", link: "/" },
+        { text: "Documentation", link: "/docs" },
+      ],
+    },
+  };
+
+  // Try to load user config
+  for (const filename of CONFIG_FILES) {
+    const configPath = path.resolve(projectRoot, filename);
+    if (fs.existsSync(configPath)) {
+      try {
+        // Add a timestamp query parameter to bust the ESM cache
+        const fileUrl = pathToFileURL(configPath).href + "?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 || [],
+        };
+      } catch (e) {
+        console.warn(`[boltdocs] Failed to load config from ${filename}:`, e);
+      }
+    }
+  }
+
+  return defaults;
+}

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 { resolveConfig } from "./config";
-
-export default async function boltdocs(
-  options?: BoltdocsPluginOptions,
-): Promise<Plugin[]> {
-  const docsDir = options?.docsDir || "docs";
-  const config = await resolveConfig(docsDir);
-
-  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";
+import { Plugin } from "vite";
+import { boltdocsPlugin } from "./plugin/index";
+import { boltdocsMdxPlugin } from "./mdx";
+import { BoltdocsPluginOptions } from "./plugin/index";
+
+import { resolveConfig } from "./config";
+
+export default async function boltdocs(
+  options?: BoltdocsPluginOptions,
+): Promise<Plugin[]> {
+  const docsDir = options?.docsDir || "docs";
+  const config = await resolveConfig(docsDir);
+
+  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";

package/src/node/mdx.ts

@@ -1,41 +1,120 @@
-import mdxPlugin from "@mdx-js/rollup";
-import remarkGfm from "remark-gfm";
-import remarkFrontmatter from "remark-frontmatter";
-import rehypeSlug from "rehype-slug";
-import rehypePrettyCode from "rehype-pretty-code";
-import type { Plugin } from "vite";
-
-import type { BoltdocsConfig } from "./config";
-
-/**
- * Configures the MDX compiler for Vite using `@mdx-js/rollup`.
- * Includes standard remark and rehype plugins for GitHub Flavored Markdown (GFM),
- * frontmatter extraction, auto-linking headers, and syntax highlighting via `rehype-pretty-code`.
- *
- * @param config - The Boltdocs configuration containing custom plugins
- * @returns A Vite plugin configured for MDX parsing
- */
-export function boltdocsMdxPlugin(config?: BoltdocsConfig): Plugin {
-  const extraRemarkPlugins =
-    config?.plugins?.flatMap((p) => p.remarkPlugins || []) || [];
-  const extraRehypePlugins =
-    config?.plugins?.flatMap((p) => p.rehypePlugins || []) || [];
-
-  return mdxPlugin({
-    remarkPlugins: [remarkGfm, remarkFrontmatter, ...extraRemarkPlugins],
-    rehypePlugins: [
-      rehypeSlug,
-      ...extraRehypePlugins,
-      [
-        rehypePrettyCode,
-        {
-          theme: "one-dark-pro",
-          keepBackground: false,
-        },
-      ],
-    ],
-    // Provide React as default for JSX
-    jsxRuntime: "automatic",
-    providerImportSource: "@mdx-js/react",
-  }) as Plugin;
-}
+import mdxPlugin from "@mdx-js/rollup";
+import remarkGfm from "remark-gfm";
+import remarkFrontmatter from "remark-frontmatter";
+import rehypeSlug from "rehype-slug";
+import rehypePrettyCode from "rehype-pretty-code";
+import type { Plugin } from "vite";
+import crypto from "crypto";
+
+import type { BoltdocsConfig } from "./config";
+import { TransformCache } from "./cache";
+
+/**
+ * Persistent cache for MDX transformations.
+ * Saves results to `.boltdocs/transform-mdx.json.gz`.
+ */
+const mdxCache = new TransformCache("mdx");
+let mdxCacheLoaded = false;
+
+/**
+ * Configures the MDX compiler for Vite using `@mdx-js/rollup`.
+ * Includes standard remark and rehype plugins for GitHub Flavored Markdown (GFM),
+ * frontmatter extraction, auto-linking headers, and syntax highlighting via `rehype-pretty-code`.
+ *
+ * Also wraps the plugin with a persistent cache to avoid re-compiling unchanged MDX files.
+ *
+ * @param config - The Boltdocs configuration containing custom plugins
+ * @returns A Vite plugin configured for MDX parsing with caching
+ */
+export function boltdocsMdxPlugin(config?: BoltdocsConfig): Plugin {
+  const extraRemarkPlugins =
+    config?.plugins?.flatMap((p) => p.remarkPlugins || []) || [];
+  const extraRehypePlugins =
+    config?.plugins?.flatMap((p) => p.rehypePlugins || []) || [];
+
+  const baseMdxPlugin = mdxPlugin({
+    remarkPlugins: [remarkGfm, remarkFrontmatter, ...extraRemarkPlugins],
+    rehypePlugins: [
+      rehypeSlug,
+      ...extraRehypePlugins,
+      [
+        rehypePrettyCode,
+        {
+          theme: config?.themeConfig?.codeTheme || "one-dark-pro",
+          keepBackground: false,
+        },
+      ],
+    ],
+    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;
+      }
+      if (baseMdxPlugin.buildStart) {
+        await (baseMdxPlugin.buildStart as any).call(this);
+      }
+    },
+
+    async transform(code, id, options) {
+      if (!id.endsWith(".md") && !id.endsWith(".mdx")) {
+        return (baseMdxPlugin.transform as any)?.call(this, code, id, options);
+      }
+
+      total++;
+      // Create a cache key based on path, content, and config (simplified)
+      const contentHash = crypto.createHash("md5").update(code).digest("hex");
+      const cacheKey = `${id}:${contentHash}`;
+
+      const cached = mdxCache.get(cacheKey);
+      if (cached) {
+        hits++;
+        return { code: cached, map: null };
+      }
+
+      const result = await (baseMdxPlugin.transform as any).call(
+        this,
+        code,
+        id,
+        options,
+      );
+
+      if (result && typeof result === "object" && result.code) {
+        mdxCache.set(cacheKey, result.code);
+      } else if (typeof result === "string") {
+        mdxCache.set(cacheKey, result);
+      }
+
+      return result;
+    },
+
+    async buildEnd() {
+      mdxCache.save();
+      await mdxCache.flush(); // Use instance flush or global flushCache
+      if (baseMdxPlugin.buildEnd) {
+        await (baseMdxPlugin.buildEnd as any).call(this);
+      }
+    },
+  };
+}
+
+/**
+ * Returns the current MDX cache statistics.
+ * @returns An object with total and hit counts
+ * @deprecated Removed for performance
+ */
+export function getMdxCacheStats() {
+  return { hits: 0, total: 0 };
+}
+
+let hits = 0;
+let total = 0;