boltdocs 1.0.0

package/src/node/plugin/entry.ts

@@ -0,0 +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} },
+});
+`;
+}

package/src/node/plugin/html.ts

@@ -0,0 +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;
+}

package/src/node/plugin/index.ts

@@ -0,0 +1,190 @@
+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),
+  ];
+}

package/src/node/plugin/types.ts

@@ -0,0 +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;
+}

package/src/node/routes/cache.ts

@@ -0,0 +1,24 @@
+import { FileCache } from "../cache";
+import { ParsedDocFile } from "./types";
+
+const docCache = new FileCache<ParsedDocFile>();
+
+/**
+ * Invalidate all cached routes.
+ * Typically called when a file is added or deleted, requiring a complete route rebuild.
+ */
+export function invalidateRouteCache(): void {
+  docCache.invalidateAll();
+}
+
+/**
+ * Invalidate a specific file from cache.
+ * Called when a specific file is modified (changed).
+ *
+ * @param filePath - The absolute path of the file to invalidate
+ */
+export function invalidateFile(filePath: string): void {
+  docCache.invalidate(filePath);
+}
+
+export { docCache };

package/src/node/routes/index.ts

@@ -0,0 +1,152 @@
+import fastGlob from "fast-glob";
+import { BoltdocsConfig } from "../config";
+import { capitalize } from "../utils";
+
+import { RouteMeta, ParsedDocFile } from "./types";
+import { docCache, invalidateRouteCache, invalidateFile } from "./cache";
+import { parseDocFile } from "./parser";
+import { sortRoutes } from "./sorter";
+
+// Re-export public API
+export type { RouteMeta };
+export { invalidateRouteCache, invalidateFile };
+
+/**
+ * Generates the entire route map for the documentation site.
+ * This reads all `.md` and `.mdx` files in the `docsDir`, parses them (using cache),
+ * infers group hierarchies based on directory structure and `index.md` files,
+ * and returns a sorted array of RouteMeta objects intended for the client.
+ *
+ * @param docsDir - The root directory containing markdown files
+ * @param config - Optional configuration for i18n and versioning
+ * @param basePath - The base URL path to prefix to generated routes (e.g., '/docs')
+ * @returns A promise that resolves to the final list of RouteMeta objects
+ */
+export async function generateRoutes(
+  docsDir: string,
+  config?: BoltdocsConfig,
+  basePath: string = "/docs",
+): Promise<RouteMeta[]> {
+  const files = await fastGlob(["**/*.md", "**/*.mdx"], {
+    cwd: docsDir,
+    absolute: true,
+  });
+
+  // Prune cache entries for deleted files
+  docCache.pruneStale(new Set(files));
+
+  // Invalidate all caches if config changes drastically (e.g. i18n enabled)
+  if (config?.i18n) {
+    docCache.invalidateAll();
+  }
+
+  // Parse files in parallel using Promise.all for increased efficiency
+  const parsed: ParsedDocFile[] = await Promise.all(
+    files.map(async (file) => {
+      const cached = docCache.get(file);
+      if (cached) return cached;
+
+      const result = parseDocFile(file, docsDir, basePath, config);
+      docCache.set(file, result);
+      return result;
+    }),
+  );
+
+  // Collect group metadata from directory names and index files
+  const groupMeta = new Map<string, { title: string; position?: number }>();
+  for (const p of parsed) {
+    if (p.relativeDir) {
+      if (!groupMeta.has(p.relativeDir)) {
+        groupMeta.set(p.relativeDir, {
+          title: capitalize(p.relativeDir),
+          position: p.inferredGroupPosition,
+        });
+      } else {
+        const entry = groupMeta.get(p.relativeDir)!;
+        if (
+          entry.position === undefined &&
+          p.inferredGroupPosition !== undefined
+        ) {
+          entry.position = p.inferredGroupPosition;
+        }
+      }
+    }
+
+    if (p.isGroupIndex && p.relativeDir && p.groupMeta) {
+      const entry = groupMeta.get(p.relativeDir)!;
+      entry.title = p.groupMeta.title;
+      if (p.groupMeta.position !== undefined) {
+        entry.position = p.groupMeta.position;
+      }
+    }
+  }
+
+  // Build final routes with group info
+  const routes: RouteMeta[] = parsed.map((p) => {
+    const dir = p.relativeDir;
+    const meta = dir ? groupMeta.get(dir) : undefined;
+
+    return {
+      ...p.route,
+      group: dir,
+      groupTitle: meta?.title || (dir ? capitalize(dir) : undefined),
+      groupPosition: meta?.position,
+    };
+  });
+
+  // Add fallbacks if i18n is enabled
+  if (config?.i18n) {
+    const defaultLocale = config.i18n.defaultLocale;
+    const allLocales = Object.keys(config.i18n.locales);
+
+    const fallbackRoutes: RouteMeta[] = [];
+    const defaultRoutes = routes.filter(
+      (r) => (r.locale || defaultLocale) === defaultLocale,
+    );
+
+    for (const locale of allLocales) {
+      if (locale === defaultLocale) continue;
+
+      const localeRoutePaths = new Set(
+        routes.filter((r) => r.locale === locale).map((r) => r.path),
+      );
+
+      for (const defRoute of defaultRoutes) {
+        let prefix = basePath;
+        if (defRoute.version) {
+          prefix += "/" + defRoute.version;
+        }
+
+        let pathAfterVersion = defRoute.path.substring(prefix.length);
+
+        if (pathAfterVersion.startsWith("/" + defaultLocale + "/")) {
+          pathAfterVersion = pathAfterVersion.substring(
+            defaultLocale.length + 1,
+          );
+        } else if (pathAfterVersion === "/" + defaultLocale) {
+          pathAfterVersion = "/";
+        }
+
+        const targetPath =
+          prefix +
+          "/" +
+          locale +
+          (pathAfterVersion === "/" || pathAfterVersion === ""
+            ? ""
+            : pathAfterVersion);
+
+        if (!localeRoutePaths.has(targetPath)) {
+          fallbackRoutes.push({
+            ...defRoute,
+            path: targetPath,
+            locale: locale,
+          });
+        }
+      }
+    }
+
+    return sortRoutes([...routes, ...fallbackRoutes]);
+  }
+
+  return sortRoutes(routes);
+}

package/src/node/routes/parser.ts

@@ -0,0 +1,127 @@
+import path from "path";
+import GithubSlugger from "github-slugger";
+import { BoltdocsConfig } from "../config";
+import { ParsedDocFile } from "./types";
+import {
+  normalizePath,
+  parseFrontmatter,
+  fileToRoutePath,
+  capitalize,
+  stripNumberPrefix,
+  extractNumberPrefix,
+} from "../utils";
+
+/**
+ * Parses a single Markdown/MDX file and extracts its metadata for routing.
+ * Checks frontmatter for explicit titles, descriptions, and sidebar positions.
+ *
+ * @param file - The absolute path to the file
+ * @param docsDir - The root documentation directory (e.g., 'docs')
+ * @param basePath - The base URL path for the routes (default: '/docs')
+ * @returns A parsed structure ready for route assembly and caching
+ */
+export function parseDocFile(
+  file: string,
+  docsDir: string,
+  basePath: string,
+  config?: BoltdocsConfig,
+): ParsedDocFile {
+  const { data, content } = parseFrontmatter(file);
+  const relativePath = normalizePath(path.relative(docsDir, file));
+  let parts = relativePath.split("/");
+
+  let locale: string | undefined;
+  let version: string | undefined;
+
+  // Level 1: Check for version
+  if (config?.versions && parts.length > 0) {
+    const potentialVersion = parts[0];
+    if (config.versions.versions[potentialVersion]) {
+      version = potentialVersion;
+      parts = parts.slice(1);
+    }
+  }
+
+  // Level 2: Check for locale
+  if (config?.i18n && parts.length > 0) {
+    const potentialLocale = parts[0];
+    if (config.i18n.locales[potentialLocale]) {
+      locale = potentialLocale;
+      parts = parts.slice(1);
+    }
+  }
+
+  const cleanRelativePath = parts.join("/");
+  const cleanRoutePath = fileToRoutePath(cleanRelativePath || "index.md");
+
+  let finalPath = basePath;
+  if (version) {
+    finalPath += "/" + version;
+  }
+  if (locale) {
+    finalPath += "/" + locale;
+  }
+  finalPath += cleanRoutePath === "/" ? "" : cleanRoutePath;
+
+  if (!finalPath || finalPath === "") finalPath = "/";
+
+  const rawFileName = parts[parts.length - 1];
+  const cleanFileName = stripNumberPrefix(rawFileName);
+  const inferredTitle = stripNumberPrefix(
+    path.basename(file, path.extname(file)),
+  );
+  const sidebarPosition =
+    data.sidebarPosition ?? extractNumberPrefix(rawFileName);
+
+  const rawDirName = parts.length >= 2 ? parts[0] : undefined;
+  const cleanDirName = rawDirName ? stripNumberPrefix(rawDirName) : undefined;
+
+  const isGroupIndex = parts.length >= 2 && /^index\.mdx?$/.test(cleanFileName);
+
+  const headings: { level: number; text: string; id: string }[] = [];
+  const slugger = new GithubSlugger();
+  const headingsRegex = /^(#{2,4})\s+(.+)$/gm;
+  let match;
+  while ((match = headingsRegex.exec(content)) !== null) {
+    const level = match[1].length;
+    // Strip simple markdown formatting specifically for the plain-text search index
+    const text = match[2]
+      .replace(/\[([^\]]+)\]\([^\)]+\)/g, "$1")
+      .replace(/[_*`]/g, "")
+      .trim();
+    const id = slugger.slug(text);
+    headings.push({ level, text, id });
+  }
+
+  return {
+    route: {
+      path: finalPath,
+      componentPath: file,
+      filePath: relativePath,
+      title: data.title || inferredTitle,
+      description: data.description || "",
+      sidebarPosition,
+      headings,
+      locale,
+      version,
+      badge: data.badge,
+    },
+    relativeDir: cleanDirName,
+    isGroupIndex,
+    groupMeta: isGroupIndex
+      ? {
+          title:
+            data.groupTitle ||
+            data.title ||
+            (cleanDirName ? capitalize(cleanDirName) : ""),
+          position:
+            data.groupPosition ??
+            data.sidebarPosition ??
+            (rawDirName ? extractNumberPrefix(rawDirName) : undefined),
+        }
+      : undefined,
+    inferredGroupPosition: rawDirName
+      ? extractNumberPrefix(rawDirName)
+      : undefined,
+  };
+}

package/src/node/routes/sorter.ts

@@ -0,0 +1,42 @@
+import { RouteMeta } from "./types";
+
+/**
+ * Sorts an array of generated routes.
+ * Ungrouped items come first. Items within the same group are sorted by position, then alphabetically.
+ * Groups are sorted relative to each other by their group position, then alphabetically.
+ *
+ * @param routes - The unsorted routes
+ * @returns A new array of sorted routes suitable for sidebar generation
+ */
+export function sortRoutes(routes: RouteMeta[]): RouteMeta[] {
+  return routes.sort((a, b) => {
+    // Ungrouped first
+    if (!a.group && !b.group) return compareByPosition(a, b);
+    if (!a.group) return -1;
+    if (!b.group) return 1;
+
+    // Different groups: sort by group position
+    if (a.group !== b.group) {
+      return compareByGroupPosition(a, b);
+    }
+
+    // Same group: sort by item position
+    return compareByPosition(a, b);
+  });
+}
+
+function compareByPosition(a: RouteMeta, b: RouteMeta): number {
+  if (a.sidebarPosition !== undefined && b.sidebarPosition !== undefined)
+    return a.sidebarPosition - b.sidebarPosition;
+  if (a.sidebarPosition !== undefined) return -1;
+  if (b.sidebarPosition !== undefined) return 1;
+  return a.title.localeCompare(b.title);
+}
+
+function compareByGroupPosition(a: RouteMeta, b: RouteMeta): number {
+  if (a.groupPosition !== undefined && b.groupPosition !== undefined)
+    return a.groupPosition - b.groupPosition;
+  if (a.groupPosition !== undefined) return -1;
+  if (b.groupPosition !== undefined) return 1;
+  return (a.groupTitle || a.group!).localeCompare(b.groupTitle || b.group!);
+}