boltdocs 1.0.0

package/src/client/theme/ui/VersionSwitcher/VersionSwitcher.tsx

@@ -0,0 +1,136 @@
+import { useState, useRef, useEffect } from "react";
+import { Layers, ChevronDown } from "lucide-react";
+import { useNavigate, useLocation } from "react-router-dom";
+import { BoltdocsVersionsConfig } from "../../../../node/config";
+import { ComponentRoute } from "../../../app";
+
+function getBaseFilePath(
+  filePath: string,
+  version: string | undefined,
+  locale: string | undefined,
+): string {
+  let path = filePath;
+  if (version && (path === version || path.startsWith(version + "/"))) {
+    path = path === version ? "index.md" : path.slice(version.length + 1);
+  }
+  if (locale && (path === locale || path.startsWith(locale + "/"))) {
+    path = path === locale ? "index.md" : path.slice(locale.length + 1);
+  }
+  return path;
+}
+
+export function VersionSwitcher({
+  versions,
+  currentVersion,
+  currentLocale,
+  allRoutes,
+}: {
+  versions: BoltdocsVersionsConfig;
+  currentVersion: string;
+  currentLocale?: string;
+  allRoutes: ComponentRoute[];
+}) {
+  const [isOpen, setIsOpen] = useState(false);
+  const dropdownRef = useRef<HTMLDivElement>(null);
+  const navigate = useNavigate();
+  const location = useLocation();
+
+  useEffect(() => {
+    function handleClickOutside(event: MouseEvent) {
+      if (
+        dropdownRef.current &&
+        !dropdownRef.current.contains(event.target as Node)
+      ) {
+        setIsOpen(false);
+      }
+    }
+    document.addEventListener("mousedown", handleClickOutside);
+    return () => document.removeEventListener("mousedown", handleClickOutside);
+  }, []);
+
+  const handleSelect = (version: string) => {
+    setIsOpen(false);
+    if (version === currentVersion) return;
+
+    const currentRoute = allRoutes.find((r) => r.path === location.pathname);
+    let targetPath = `/docs/${version}`; // Default to root of the new version
+
+    if (currentRoute) {
+      const baseFile = getBaseFilePath(
+        currentRoute.filePath,
+        currentRoute.version,
+        currentRoute.locale,
+      );
+
+      const targetRoute = allRoutes.find(
+        (r) =>
+          getBaseFilePath(r.filePath, r.version, r.locale) === baseFile &&
+          (r.version || versions.defaultVersion) === version &&
+          (currentLocale ? r.locale === currentLocale : !r.locale),
+      );
+
+      if (targetRoute) {
+        targetPath = targetRoute.path;
+      } else {
+        // Fallback to version index
+        const versionIndexRoute = allRoutes.find(
+          (r) =>
+            getBaseFilePath(r.filePath, r.version, r.locale) === "index.md" &&
+            (r.version || versions.defaultVersion) === version &&
+            (currentLocale ? r.locale === currentLocale : !r.locale),
+        );
+        targetPath = versionIndexRoute
+          ? versionIndexRoute.path
+          : `/docs/${version}${currentLocale ? `/${currentLocale}` : ""}`;
+      }
+    }
+
+    navigate(targetPath);
+  };
+
+  return (
+    <div
+      className="boltdocs-version-switcher"
+      ref={dropdownRef}
+      style={{ position: "relative", display: "flex", alignItems: "center" }}
+    >
+      <button
+        className="navbar-version"
+        onClick={() => setIsOpen(!isOpen)}
+        aria-label="Switch version"
+        aria-expanded={isOpen}
+        aria-haspopup="listbox"
+        style={{
+          fontFamily: "inherit",
+          padding: "0.25rem 0.5rem",
+          marginLeft: "0.5rem",
+        }}
+      >
+        <span>{versions.versions[currentVersion] || currentVersion}</span>
+        <ChevronDown size={14} />
+      </button>
+
+      {isOpen && (
+        <div
+          className="language-dropdown"
+          style={{
+            left: "0.5rem",
+            right: "auto",
+            minWidth: "150px",
+            top: "calc(100% + 8px)",
+          }}
+        >
+          {Object.entries(versions.versions).map(([key, label]) => (
+            <button
+              key={key}
+              className={`language-option ${key === currentVersion ? "active" : ""}`}
+              onClick={() => handleSelect(key)}
+            >
+              {label}
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/client/theme/ui/VersionSwitcher/index.ts

@@ -0,0 +1 @@
+export { VersionSwitcher } from "./VersionSwitcher";

package/src/client/utils.ts

@@ -0,0 +1,26 @@
+/**
+ * Get the number of stars for a GitHub repository.
+ * @param repo - The repository name in the format "owner/repo".
+ * @returns The number of stars for the repository.
+ */
+export async function getStarsRepo(repo: string) {
+  const response = await fetch(`https://api.github.com/repos/${repo}`);
+  const data = await response.json();
+  if (data.stargazers_count !== undefined) {
+    return formatStars(data.stargazers_count);
+  } else {
+    return "0"; // Fallback
+  }
+}
+
+/**
+ * Format a number of stars in a compact form.
+ * @param count - The number of stars to format.
+ * @returns The formatted number of stars.
+ */
+const formatStars = (count: number): string => {
+  return Intl.NumberFormat("en", {
+    notation: "compact",
+    compactDisplay: "short",
+  }).format(count);
+};

package/src/node/cache.ts

@@ -0,0 +1,94 @@
+import { getFileMtime } from "./utils";
+
+/**
+ * Per-file cache entry. Stores parsed data + the mtime at parse time.
+ */
+interface FileCacheEntry<T> {
+  data: T;
+  mtime: number;
+}
+
+/**
+ * Generic file-based cache with per-file granularity.
+ * Only re-parses files whose mtime has changed.
+ */
+export class FileCache<T> {
+  private entries = new Map<string, FileCacheEntry<T>>();
+
+  /**
+   * Retrieves parsed data for a file from the cache.
+   * Compares the current filesystem mtime with the cached mtime.
+   *
+   * @param filePath - The absolute path of the file
+   * @returns The cached data if valid, or `null` if the file has changed or doesn't exist
+   */
+  get(filePath: string): T | null {
+    const entry = this.entries.get(filePath);
+    if (!entry) return null;
+
+    const currentMtime = getFileMtime(filePath);
+    if (currentMtime !== entry.mtime) return null;
+
+    return entry.data;
+  }
+
+  /**
+   * Stores parsed data for a file in the cache, recording its current mtime.
+   *
+   * @param filePath - The absolute path to the file
+   * @param data - The parsed data to store
+   */
+  set(filePath: string, data: T): void {
+    this.entries.set(filePath, {
+      data,
+      mtime: getFileMtime(filePath),
+    });
+  }
+
+  /**
+   * Checks if a specific file's cache is still valid (based on its mtime).
+   *
+   * @param filePath - The absolute path to the file
+   * @returns `true` if the cache is valid, `false` otherwise
+   */
+  isValid(filePath: string): boolean {
+    return this.get(filePath) !== null;
+  }
+
+  /**
+   * Manually removes a specific file from the cache.
+   * Useful when forcefully invalidating a single updated file.
+   *
+   * @param filePath - The absolute path to the file
+   */
+  invalidate(filePath: string): void {
+    this.entries.delete(filePath);
+  }
+
+  /**
+   * Clears the entire cache, forcing all files to be re-parsed on the next request.
+   * Useful when global dependencies (like config) change.
+   */
+  invalidateAll(): void {
+    this.entries.clear();
+  }
+
+  /**
+   * Removes cached entries for files that no longer exist on the filesystem.
+   * Prevents memory leaks from deleted files.
+   *
+   * @param currentFiles - A Set of absolute file paths currently discovered on the disk
+   */
+  pruneStale(currentFiles: Set<string>): void {
+    for (const key of this.entries.keys()) {
+      if (!currentFiles.has(key)) {
+        this.entries.delete(key);
+      }
+    }
+  }
+
+  /** Number of cached entries */
+  get size(): number {
+    return this.entries.size;
+  }
+}

package/src/node/cli/commands/config.ts

@@ -0,0 +1,15 @@
+import path from "path";
+import { resolveConfig } from "../../config";
+
+export async function configAction(root?: string) {
+  const rootDir = root ? path.resolve(root) : process.cwd();
+  const docsDir = path.resolve(rootDir, "docs");
+
+  try {
+    const config = await resolveConfig(docsDir);
+    process.stdout.write(JSON.stringify(config, null, 2) + "\n");
+  } catch (e) {
+    process.stderr.write("Failed to resolve configuration: " + e + "\n");
+    process.exit(1);
+  }
+}

package/src/node/cli/commands/generate-css.ts

@@ -0,0 +1,24 @@
+import path from "path";
+import fs from "node:fs";
+import { DEFAULT_CSS_VARIABLES } from "../constants";
+
+export function generateCssAction(outputPath?: string) {
+  try {
+    const target = process.cwd();
+    const filename = outputPath || "custom.css";
+    const filepath = path.resolve(target, filename);
+
+    if (fs.existsSync(filepath)) {
+      process.stderr.write(
+        "Error: File " + filename + " already exists in " + target + ".\n",
+      );
+      process.exit(1);
+    }
+
+    fs.writeFileSync(filepath, DEFAULT_CSS_VARIABLES);
+    process.stdout.write("Success! Generated " + filename + "\n");
+  } catch (e) {
+    process.stderr.write("Failed to generate CSS: " + e + "\n");
+    process.exit(1);
+  }
+}

package/src/node/cli/constants.ts

@@ -0,0 +1,70 @@
+export const DEFAULT_CSS_VARIABLES = `:root {
+  /* ─ Base palette ─ */
+  --ld-bg-main: #0a0a0f;
+  --ld-bg-soft: #0f0f18;
+  --ld-bg-mute: #141420;
+  --ld-surface: #1a1a2e;
+  --ld-border-subtle: rgba(255, 255, 255, 0.06);
+  --ld-border-strong: rgba(255, 255, 255, 0.12);
+
+  /* ─ Text ─ */
+  --ld-text-main: #e4e4ed;
+  --ld-text-muted: #9d9db5;
+  --ld-text-dim: #6b6b85;
+
+  /* ─ Accent ─ */
+  --ld-color-primary: #ffff;
+  --ld-color-primary-hover: #f8f8f8;
+  --ld-color-primary-muted: rgba(255, 255, 255, 0.05);
+  --ld-color-primary-glow: rgba(255, 255, 255, 0.15);
+  --ld-color-primary-text: #010101;
+  --ld-color-accent: #ffff; /* Yellow accent for TOC */
+
+  /* ─ Code ─ */
+  --ld-code-bg: #0d0d14;
+  --ld-code-header: #111119;
+  --ld-code-text: #d4d4d4;
+
+  /* ─ Typography ─ */
+  --ld-font-sans: "Inter", system-ui, -apple-system, sans-serif;
+  --ld-font-mono:
+    "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas,
+    monospace;
+
+  /* ─ Dimensions ─ */
+  --ld-navbar-height: 3.5rem;
+  --ld-sidebar-width: 14.5rem;
+  --ld-toc-width: 13rem;
+  --ld-content-max-width: 820px;
+  --ld-radius-sm: 4px;
+  --ld-radius-md: 8px;
+  --ld-radius-lg: 12px;
+  --ld-radius-full: 9999px;
+}
+
+[data-theme="light"],
+.theme-light {
+  --ld-bg-main: #ffffff;
+  --ld-bg-soft: #f9fafb;
+  --ld-bg-mute: #f3f4f6;
+
+  --ld-surface: #ffffff;
+
+  --ld-border-subtle: #e5e7eb;
+  --ld-border-strong: #d1d5db;
+
+  --ld-text-main: #111827;
+  --ld-text-muted: #4b5563;
+  --ld-text-dim: #6b7280;
+
+  --ld-color-primary: #010101;
+  --ld-color-primary-hover: #010101;
+  --ld-color-primary-muted: rgba(127, 19, 236, 0.1);
+  --ld-color-primary-glow: rgba(127, 19, 236, 0.25);
+  --ld-color-primary-text: #010101;
+
+  --ld-code-bg: #f3f4f6;
+  --ld-code-header: #e5e7eb;
+  --ld-code-text: #1f2937;
+}
+`;

package/src/node/cli/index.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import cac from "cac";
+import { configAction } from "./commands/config";
+import { generateCssAction } from "./commands/generate-css";
+
+const cli = cac("boltdocs");
+
+cli
+  .command("config [root]", "Output the resolved boltdocs configuration")
+  .action(configAction);
+
+cli
+  .command(
+    "generate:css [path]",
+    "Generate a custom.css file with default Boltdocs CSS variables",
+  )
+  .action(generateCssAction);
+
+cli.help();
+cli.version("1.0.0");
+
+cli.parse();

package/src/node/config.ts

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

package/src/node/index.ts

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

package/src/node/mdx.ts

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