boltdocs 1.0.4 → 1.3.1

package/src/node/plugin/entry.ts

@@ -1,58 +1,58 @@
-import { normalizePath } from "../utils";
-import type { BoltdocsConfig } from "../config";
-import type { BoltdocsPluginOptions } from "./types";
-
-/**
- * Generates the raw source code for the virtual entry file (`\0virtual:boltdocs-entry`).
- * This code initializes the client-side React application.
- *
- * @param options - Plugin options containing potential custom overrides (like `homePage` or `customCss`)
- * @param config - The resolved Boltdocs configuration containing custom plugins and components
- * @returns A string of JavaScript code to be evaluated by the browser
- */
-export function generateEntryCode(
-  options: BoltdocsPluginOptions,
-  config?: BoltdocsConfig,
-): string {
-  const homeImport = options.homePage
-    ? `import HomePage from '${normalizePath(options.homePage)}';`
-    : "";
-  const homeOption = options.homePage ? "homePage: HomePage," : "";
-  const customCssImport = options.customCss
-    ? `import '${normalizePath(options.customCss)}';`
-    : "";
-
-  const pluginComponents =
-    config?.plugins?.flatMap((p) => Object.entries(p.components || {})) || [];
-
-  const componentImports = pluginComponents
-    .map(
-      ([
-        name,
-        path,
-      ]) => `import * as _comp_${name} from '${normalizePath(path)}';
-const ${name} = _comp_${name}.default || _comp_${name}['${name}'] || _comp_${name};`,
-    )
-    .join("\n");
-  const componentMap = pluginComponents.map(([name]) => name).join(", ");
-
-  return `
-import { createBoltdocsApp as _createApp } from 'boltdocs/client';
-import 'boltdocs/style.css';
-${customCssImport}
-import _routes from 'virtual:boltdocs-routes';
-import _config from 'virtual:boltdocs-config';
-${homeImport}
-${componentImports}
-
-_createApp({
-  target: '#root',
-  routes: _routes,
-  config: _config,
-  modules: import.meta.glob('/docs/**/*.{md,mdx}'),
-  hot: import.meta.hot,
-  ${homeOption}
-  components: { ${componentMap} },
-});
-`;
-}
+import { normalizePath } from "../utils";
+import type { BoltdocsConfig } from "../config";
+import type { BoltdocsPluginOptions } from "./types";
+
+/**
+ * Generates the raw source code for the virtual entry file (`\0virtual:boltdocs-entry`).
+ * This code initializes the client-side React application.
+ *
+ * @param options - Plugin options containing potential custom overrides (like `homePage` or `customCss`)
+ * @param config - The resolved Boltdocs configuration containing custom plugins and components
+ * @returns A string of JavaScript code to be evaluated by the browser
+ */
+export function generateEntryCode(
+  options: BoltdocsPluginOptions,
+  config?: BoltdocsConfig,
+): string {
+  const homeImport = options.homePage
+    ? `import HomePage from '${normalizePath(options.homePage)}';`
+    : "";
+  const homeOption = options.homePage ? "homePage: HomePage," : "";
+  const customCssImport = options.customCss
+    ? `import '${normalizePath(options.customCss)}';`
+    : "";
+
+  const pluginComponents =
+    config?.plugins?.flatMap((p) => Object.entries(p.components || {})) || [];
+
+  const componentImports = pluginComponents
+    .map(
+      ([
+        name,
+        path,
+      ]) => `import * as _comp_${name} from '${normalizePath(path)}';
+const ${name} = _comp_${name}.default || _comp_${name}['${name}'] || _comp_${name};`,
+    )
+    .join("\n");
+  const componentMap = pluginComponents.map(([name]) => name).join(", ");
+
+  return `
+import { createBoltdocsApp as _createApp } from 'boltdocs/client';
+import 'boltdocs/style.css';
+${customCssImport}
+import _routes from 'virtual:boltdocs-routes';
+import _config from 'virtual:boltdocs-config';
+${homeImport}
+${componentImports}
+
+_createApp({
+  target: '#root',
+  routes: _routes,
+  config: _config,
+  modules: import.meta.glob('/docs/**/*.{md,mdx}'),
+  hot: import.meta.hot,
+  ${homeOption}
+  components: { ${componentMap} },
+});
+`;
+}

package/src/node/plugin/html.ts

@@ -1,55 +1,55 @@
-import type { BoltdocsConfig } from "../config";
-
-/**
- * Injects OpenGraph, Twitter, and generic SEO meta tags into the final HTML output.
- * Also ensures the virtual entry file is injected if it's missing (e.g., standard Vite index.html).
- *
- * @param html - The original HTML string
- * @param config - The resolved Boltdocs configuration containing site metadata
- * @returns The modified HTML string with injected tags
- */
-export function injectHtmlMeta(html: string, config: BoltdocsConfig): string {
-  const title = config.themeConfig?.title || "Boltdocs";
-  const description = config.themeConfig?.description || "";
-
-  const seoTags = [
-    `<meta name="description" content="${description}">`,
-    `<meta property="og:title" content="${title}">`,
-    `<meta property="og:description" content="${description}">`,
-    `<meta property="og:type" content="website">`,
-    `<meta name="twitter:card" content="summary">`,
-    `<meta name="twitter:title" content="${title}">`,
-    `<meta name="twitter:description" content="${description}">`,
-    `<meta name="generator" content="Boltdocs">`,
-  ].join("\n    ");
-
-  const themeScript = `
-    <script>
-      (function() {
-        try {
-          var stored = localStorage.getItem("boltdocs-theme");
-          var theme = stored || (window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light");
-          if (theme === "light") {
-            document.documentElement.classList.add("theme-light");
-            document.documentElement.dataset.theme = "light";
-          } else {
-            document.documentElement.classList.remove("theme-light");
-            document.documentElement.dataset.theme = "dark";
-          }
-        } catch (e) {}
-      })();
-    </script>
-  `;
-
-  html = html.replace(/<title>.*?<\/title>/, `<title>${title}</title>`);
-  html = html.replace("</head>", `    ${seoTags}\n${themeScript}  </head>`);
-
-  if (!html.includes("src/main")) {
-    html = html.replace(
-      "</body>",
-      '  <script type="module">import "virtual:boltdocs-entry";</script>\n  </body>',
-    );
-  }
-
-  return html;
-}
+import type { BoltdocsConfig } from "../config";
+
+/**
+ * Injects OpenGraph, Twitter, and generic SEO meta tags into the final HTML output.
+ * Also ensures the virtual entry file is injected if it's missing (e.g., standard Vite index.html).
+ *
+ * @param html - The original HTML string
+ * @param config - The resolved Boltdocs configuration containing site metadata
+ * @returns The modified HTML string with injected tags
+ */
+export function injectHtmlMeta(html: string, config: BoltdocsConfig): string {
+  const title = config.themeConfig?.title || "Boltdocs";
+  const description = config.themeConfig?.description || "";
+
+  const seoTags = [
+    `<meta name="description" content="${description}">`,
+    `<meta property="og:title" content="${title}">`,
+    `<meta property="og:description" content="${description}">`,
+    `<meta property="og:type" content="website">`,
+    `<meta name="twitter:card" content="summary">`,
+    `<meta name="twitter:title" content="${title}">`,
+    `<meta name="twitter:description" content="${description}">`,
+    `<meta name="generator" content="Boltdocs">`,
+  ].join("\n    ");
+
+  const themeScript = `
+    <script>
+      (function() {
+        try {
+          var stored = localStorage.getItem("boltdocs-theme");
+          var theme = stored || (window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light");
+          if (theme === "light") {
+            document.documentElement.classList.add("theme-light");
+            document.documentElement.dataset.theme = "light";
+          } else {
+            document.documentElement.classList.remove("theme-light");
+            document.documentElement.dataset.theme = "dark";
+          }
+        } catch (e) {}
+      })();
+    </script>
+  `;
+
+  html = html.replace(/<title>.*?<\/title>/, `<title>${title}</title>`);
+  html = html.replace("</head>", `    ${seoTags}\n${themeScript}  </head>`);
+
+  if (!html.includes("src/main")) {
+    html = html.replace(
+      "</body>",
+      '  <script type="module">import "virtual:boltdocs-entry";</script>\n  </body>',
+    );
+  }
+
+  return html;
+}

package/src/node/plugin/index.ts

@@ -1,190 +1,193 @@
-import { Plugin, ResolvedConfig, loadEnv } from "vite";
-import {
-  generateRoutes,
-  invalidateRouteCache,
-  invalidateFile,
-} from "../routes";
-import { ViteImageOptimizer } from "vite-plugin-image-optimizer";
-import { resolveConfig, BoltdocsConfig, CONFIG_FILES } from "../config";
-import { generateStaticPages } from "../ssg";
-import { normalizePath, isDocFile } from "../utils";
-import path from "path";
-
-import { BoltdocsPluginOptions } from "./types";
-import { generateEntryCode } from "./entry";
-import { injectHtmlMeta } from "./html";
-
-export * from "./types";
-
-/**
- * The core Boltdocs Vite plugin.
- * Handles virtual module resolution, HMR for documentation files,
- * injecting HTML meta tags for SEO, and triggering the SSG process on build.
- *
- * @param options - Optional configuration for the plugin
- * @param passedConfig - Pre-resolved configuration (internal use)
- * @returns An array of Vite plugins
- */
-export function boltdocsPlugin(
-  options: BoltdocsPluginOptions = {},
-  passedConfig?: BoltdocsConfig,
-): Plugin[] {
-  const docsDir = path.resolve(process.cwd(), options.docsDir || "docs");
-  const normalizedDocsDir = normalizePath(docsDir);
-  let config: BoltdocsConfig = passedConfig!;
-  let viteConfig: ResolvedConfig;
-  let isBuild = false;
-
-  const extraVitePlugins =
-    config?.plugins?.flatMap((p) => p.vitePlugins || []) || [];
-
-  return [
-    {
-      name: "vite-plugin-boltdocs",
-      enforce: "pre",
-
-      async config(userConfig, env) {
-        isBuild = env.command === "build";
-
-        // Load env variables and inject into process.env so they are available in boltdocs.config.js
-        const envDir = userConfig.envDir || process.cwd();
-        const envs = loadEnv(env.mode, envDir, "");
-        Object.assign(process.env, envs);
-
-        // Resolve config async if not already passed
-        if (!config) {
-          config = await resolveConfig(docsDir);
-        }
-
-        // If customCss specified in user's config file, use it
-        if (!options.customCss && config.themeConfig?.customCss) {
-          options.customCss = config.themeConfig.customCss;
-        }
-
-        return {
-          optimizeDeps: { include: ["react", "react-dom"] },
-        };
-      },
-
-      configResolved(resolved) {
-        viteConfig = resolved;
-      },
-
-      configureServer(server) {
-        // Explicitly watch config files to trigger server restarts
-        const configPaths = CONFIG_FILES.map((c) =>
-          path.resolve(process.cwd(), c),
-        );
-        server.watcher.add(configPaths);
-
-        const handleFileEvent = async (
-          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;
-          }
-
-          if (
-            !normalized.startsWith(normalizedDocsDir) ||
-            !isDocFile(normalized)
-          )
-            return;
-
-          // Invalidate appropriately
-          if (type === "add" || type === "unlink") {
-            invalidateRouteCache();
-          } else {
-            invalidateFile(file);
-          }
-
-          // Regenerate and push to client
-          const newRoutes = await generateRoutes(docsDir, config);
-
-          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,
-          });
-        };
-
-        server.watcher.on("add", (f) => handleFileEvent(f, "add"));
-        server.watcher.on("unlink", (f) => handleFileEvent(f, "unlink"));
-        server.watcher.on("change", (f) => handleFileEvent(f, "change"));
-      },
-
-      resolveId(id) {
-        if (
-          id === "virtual:boltdocs-routes" ||
-          id === "virtual:boltdocs-config" ||
-          id === "virtual:boltdocs-entry"
-        ) {
-          return "\0" + id;
-        }
-      },
-
-      async load(id) {
-        if (id === "\0virtual:boltdocs-routes") {
-          const routes = await generateRoutes(docsDir, config);
-          return `export default ${JSON.stringify(routes, null, 2)};`;
-        }
-        if (id === "\0virtual:boltdocs-config") {
-          const clientConfig = {
-            themeConfig: config?.themeConfig,
-            i18n: config?.i18n,
-            versions: config?.versions,
-            siteUrl: config?.siteUrl,
-          };
-          return `export default ${JSON.stringify(clientConfig, null, 2)};`;
-        }
-        if (id === "\0virtual:boltdocs-entry") {
-          const code = generateEntryCode(options, config);
-          return code;
-        }
-      },
-
-      transformIndexHtml: {
-        order: "pre",
-        handler(html) {
-          return injectHtmlMeta(html, config);
-        },
-      },
-
-      async closeBundle() {
-        if (!isBuild) return;
-        const outDir = viteConfig?.build?.outDir
-          ? path.resolve(viteConfig.root, viteConfig.build.outDir)
-          : path.resolve(process.cwd(), "dist");
-
-        await generateStaticPages({ docsDir, outDir, config });
-      },
-    },
-    ViteImageOptimizer({
-      includePublic: true,
-      png: { quality: 80 },
-      jpeg: { quality: 80 },
-      jpg: { quality: 80 },
-      webp: { quality: 80 },
-      avif: { quality: 80 },
-      svg: {
-        multipass: true,
-        plugins: [
-          {
-            name: "preset-default",
-            params: { overrides: { removeViewBox: false } },
-          },
-        ] as any,
-      },
-    }),
-    ...extraVitePlugins.filter((p): p is Plugin => !!p),
-  ];
-}
+import { Plugin, ResolvedConfig, loadEnv } from "vite";
+import {
+  generateRoutes,
+  invalidateRouteCache,
+  invalidateFile,
+} from "../routes";
+import { ViteImageOptimizer } from "vite-plugin-image-optimizer";
+import { resolveConfig, BoltdocsConfig, CONFIG_FILES } from "../config";
+import { generateStaticPages } from "../ssg";
+import { normalizePath, isDocFile } from "../utils";
+import path from "path";
+
+import { BoltdocsPluginOptions } from "./types";
+import { generateEntryCode } from "./entry";
+import { injectHtmlMeta } from "./html";
+
+export * from "./types";
+
+/**
+ * The core Boltdocs Vite plugin.
+ * Handles virtual module resolution, HMR for documentation files,
+ * injecting HTML meta tags for SEO, and triggering the SSG process on build.
+ *
+ * @param options - Optional configuration for the plugin
+ * @param passedConfig - Pre-resolved configuration (internal use)
+ * @returns An array of Vite plugins
+ */
+export function boltdocsPlugin(
+  options: BoltdocsPluginOptions = {},
+  passedConfig?: BoltdocsConfig,
+): Plugin[] {
+  const docsDir = path.resolve(process.cwd(), options.docsDir || "docs");
+  const normalizedDocsDir = normalizePath(docsDir);
+  let config: BoltdocsConfig = passedConfig!;
+  let viteConfig: ResolvedConfig;
+  let isBuild = false;
+
+  const extraVitePlugins =
+    config?.plugins?.flatMap((p) => p.vitePlugins || []) || [];
+
+  return [
+    {
+      name: "vite-plugin-boltdocs",
+      enforce: "pre",
+
+      async config(userConfig, env) {
+        isBuild = env.command === "build";
+
+        // Load env variables and inject into process.env so they are available in boltdocs.config.js
+        const envDir = userConfig.envDir || process.cwd();
+        const envs = loadEnv(env.mode, envDir, "");
+        Object.assign(process.env, envs);
+
+        // Resolve config async if not already passed
+        if (!config) {
+          config = await resolveConfig(docsDir);
+        }
+
+        // If customCss specified in user's config file, use it
+        if (!options.customCss && config.themeConfig?.customCss) {
+          options.customCss = config.themeConfig.customCss;
+        }
+
+        return {
+          optimizeDeps: { include: ["react", "react-dom"] },
+        };
+      },
+
+      configResolved(resolved) {
+        viteConfig = resolved;
+      },
+
+      configureServer(server) {
+        // Explicitly watch config files to trigger server restarts
+        const configPaths = CONFIG_FILES.map((c) =>
+          path.resolve(process.cwd(), c),
+        );
+        server.watcher.add(configPaths);
+
+        const handleFileEvent = async (
+          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;
+          }
+
+          if (
+            !normalized.startsWith(normalizedDocsDir) ||
+            !isDocFile(normalized)
+          )
+            return;
+
+          // Invalidate appropriately
+          if (type === "add" || type === "unlink") {
+            invalidateRouteCache();
+          } else {
+            invalidateFile(file);
+          }
+
+          // Regenerate and push to client
+          const newRoutes = await generateRoutes(docsDir, config);
+
+          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,
+          });
+        };
+
+        server.watcher.on("add", (f) => handleFileEvent(f, "add"));
+        server.watcher.on("unlink", (f) => handleFileEvent(f, "unlink"));
+        server.watcher.on("change", (f) => handleFileEvent(f, "change"));
+      },
+
+      resolveId(id) {
+        if (
+          id === "virtual:boltdocs-routes" ||
+          id === "virtual:boltdocs-config" ||
+          id === "virtual:boltdocs-entry"
+        ) {
+          return "\0" + id;
+        }
+      },
+
+      async load(id) {
+        if (id === "\0virtual:boltdocs-routes") {
+          const routes = await generateRoutes(docsDir, config);
+          return `export default ${JSON.stringify(routes, null, 2)};`;
+        }
+        if (id === "\0virtual:boltdocs-config") {
+          const clientConfig = {
+            themeConfig: config?.themeConfig,
+            i18n: config?.i18n,
+            versions: config?.versions,
+            siteUrl: config?.siteUrl,
+          };
+          return `export default ${JSON.stringify(clientConfig, null, 2)};`;
+        }
+        if (id === "\0virtual:boltdocs-entry") {
+          const code = generateEntryCode(options, config);
+          return code;
+        }
+      },
+
+      transformIndexHtml: {
+        order: "pre",
+        handler(html) {
+          return injectHtmlMeta(html, config);
+        },
+      },
+
+      async closeBundle() {
+        if (!isBuild) return;
+        const outDir = viteConfig?.build?.outDir
+          ? path.resolve(viteConfig.root, viteConfig.build.outDir)
+          : path.resolve(process.cwd(), "dist");
+
+        await generateStaticPages({ docsDir, outDir, config });
+
+        const { flushCache } = await import("../cache");
+        await flushCache();
+      },
+    },
+    ViteImageOptimizer({
+      includePublic: true,
+      png: { quality: 80 },
+      jpeg: { quality: 80 },
+      jpg: { quality: 80 },
+      webp: { quality: 80 },
+      avif: { quality: 80 },
+      svg: {
+        multipass: true,
+        plugins: [
+          {
+            name: "preset-default",
+            params: { overrides: { removeViewBox: false } },
+          },
+        ] as any,
+      },
+    }),
+    ...extraVitePlugins.filter((p): p is Plugin => !!p),
+  ];
+}

package/src/node/plugin/types.ts

@@ -1,11 +1,11 @@
-/**
- * Configuration options specifically for the Boltdocs Vite plugin.
- */
-export interface BoltdocsPluginOptions {
-  /** The root directory containing markdown files (default: 'docs') */
-  docsDir?: string;
-  /** Path to a custom home page component (relative to project root) to render at '/' */
-  homePage?: string;
-  /** Path to a custom CSS file to override theme variables. Can also be set in boltdocs.config.js */
-  customCss?: string;
-}
+/**
+ * Configuration options specifically for the Boltdocs Vite plugin.
+ */
+export interface BoltdocsPluginOptions {
+  /** The root directory containing markdown files (default: 'docs') */
+  docsDir?: string;
+  /** Path to a custom home page component (relative to project root) to render at '/' */
+  homePage?: string;
+  /** Path to a custom CSS file to override theme variables. Can also be set in boltdocs.config.js */
+  customCss?: string;
+}