boltdocs 1.0.0

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "boltdocs",
+  "version": "1.0.0",
+  "description": "A lightweight documentation generator for React projects.",
+  "main": "dist/node/index.js",
+  "module": "dist/node/index.mjs",
+  "types": "dist/node/index.d.ts",
+  "bin": {
+    "boltdocs": "./dist/node/cli/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/node/index.d.ts",
+      "import": "./dist/node/index.mjs",
+      "require": "./dist/node/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.mjs",
+      "require": "./dist/client/index.js"
+    },
+    "./style.css": "./dist/client/index.css"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "keywords": [
+    "docs",
+    "documentation",
+    "static site generator",
+    "ssg",
+    "markdown",
+    "mdx",
+    "react",
+    "vite",
+    "typescript"
+  ],
+  "author": "Jesus Alcala",
+  "license": "ISC",
+  "type": "commonjs",
+  "dependencies": {
+    "@mdx-js/react": "^3.1.1",
+    "@mdx-js/rollup": "^3.1.1",
+    "cac": "^7.0.0",
+    "fast-glob": "^3.3.3",
+    "github-slugger": "^2.0.0",
+    "gray-matter": "^4.0.3",
+    "lucide-react": "^0.575.0",
+    "react-live": "^4.1.8",
+    "react-router-dom": "^6.30.3",
+    "rehype-pretty-code": "^0.14.1",
+    "rehype-slug": "^6.0.0",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.1",
+    "sharp": "^0.34.5",
+    "shiki": "^3.23.0",
+    "svgo": "^4.0.0",
+    "unist-util-visit": "^5.1.0",
+    "vite": "^7.3.1",
+    "vite-plugin-image-optimizer": "^2.0.3"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "packageManager": "pnpm@10.30.2",
+  "devDependencies": {
+    "@types/node": "^25.3.2",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^18.3.7",
+    "@types/react-router-dom": "^5.3.3",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}

package/src/client/app/index.tsx

@@ -0,0 +1,422 @@
+import React, { useEffect, useState } from "react";
+import ReactDOM from "react-dom/client";
+import {
+  BrowserRouter,
+  Routes,
+  Route,
+  Outlet,
+  useLocation,
+} from "react-router-dom";
+import { ThemeLayout } from "../theme/ui/Layout";
+import { NotFound } from "../theme/ui/NotFound";
+import { Loading } from "../theme/ui/Loading";
+import { MDXProvider } from "@mdx-js/react";
+import {
+  createContext,
+  useContext,
+  Suspense,
+  lazy,
+  useLayoutEffect,
+} from "react";
+import { Link as LucideLink } from "lucide-react";
+
+export const ConfigContext = createContext<any>(null);
+
+export function useConfig() {
+  return useContext(ConfigContext);
+}
+
+const CodeBlock = lazy(() =>
+  import("../theme/components/CodeBlock").then((m) => ({
+    default: m.CodeBlock,
+  })),
+);
+const Video = lazy(() =>
+  import("../theme/components/Video").then((m) => ({ default: m.Video })),
+);
+const PackageManagerTabs = lazy(() =>
+  import("../theme/components/PackageManagerTabs").then((m) => ({
+    default: m.PackageManagerTabs,
+  })),
+);
+const Playground = lazy(() =>
+  import("../theme/components/Playground").then((m) => ({
+    default: m.Playground,
+  })),
+);
+
+import {
+  Button,
+  Badge,
+  Card,
+  Cards,
+  Tabs,
+  Tab,
+  Admonition,
+  Note,
+  Tip,
+  Warning,
+  Danger,
+  InfoBox,
+  List,
+} from "../theme/components/mdx";
+declare global {
+  interface ImportMeta {
+    env: Record<string, any>;
+  }
+}
+
+import { PreloadProvider } from "./preload";
+
+const Heading = ({
+  level,
+  id,
+  children,
+}: {
+  level: number;
+  id?: string;
+  children: React.ReactNode;
+}) => {
+  const Tag = `h${level}` as keyof JSX.IntrinsicElements;
+  return (
+    <Tag id={id} className="boltdocs-heading">
+      {children}
+      {id && (
+        <a href={`#${id}`} className="header-anchor" aria-label="Anchor">
+          <LucideLink size={16} />
+        </a>
+      )}
+    </Tag>
+  );
+};
+
+const mdxComponents = {
+  h1: (props: any) => <Heading level={1} {...props} />,
+  h2: (props: any) => <Heading level={2} {...props} />,
+  h3: (props: any) => <Heading level={3} {...props} />,
+  h4: (props: any) => <Heading level={4} {...props} />,
+  h5: (props: any) => <Heading level={5} {...props} />,
+  h6: (props: any) => <Heading level={6} {...props} />,
+  pre: (props: any) => {
+    return (
+      <Suspense fallback={<div className="code-block-skeleton" />}>
+        <CodeBlock {...props}>{props.children}</CodeBlock>
+      </Suspense>
+    );
+  },
+  video: (props: any) => (
+    <Suspense fallback={<div className="video-skeleton" />}>
+      <Video {...props} />
+    </Suspense>
+  ),
+  PackageManagerTabs: (props: any) => (
+    <Suspense fallback={<div className="pkg-tabs-skeleton" />}>
+      <PackageManagerTabs {...props} />
+    </Suspense>
+  ),
+  Playground: (props: any) => (
+    <Suspense fallback={<div className="playground-skeleton" />}>
+      <Playground {...props} />
+    </Suspense>
+  ),
+  Button,
+  Badge,
+  Card,
+  Cards,
+  Tabs,
+  Tab,
+  Admonition,
+  Note,
+  Tip,
+  Warning,
+  Danger,
+  InfoBox,
+  List,
+};
+
+/**
+ * Metadata provided by the server for a specific route.
+ * Maps closely to the `RouteMeta` type in the Node environment.
+ */
+export interface ComponentRoute {
+  /** The final URL path */
+  path: string;
+  /** The absolute filesystem path of the source file */
+  componentPath: string;
+  /** The page title */
+  title: string;
+  /** Explicit order in the sidebar */
+  sidebarPosition?: number;
+  /** The relative path from the docs directory */
+  filePath: string;
+  /** The group directory name */
+  group?: string;
+  /** The display title of the group */
+  groupTitle?: string;
+  /** Explicit order of the group in the sidebar */
+  groupPosition?: number;
+  /** Extracted markdown headings for search indexing */
+  headings?: { level: number; text: string; id: string }[];
+  /** The locale this route belongs to, if i18n is configured */
+  locale?: string;
+  /** The version this route belongs to, if versioning is configured */
+  version?: string;
+}
+
+/**
+ * Configuration options for initializing the Boltdocs client app.
+ */
+export interface CreateBoltdocsAppOptions {
+  /** CSS selector for the DOM element where the app should mount (e.g. '#root') */
+  target: string;
+  /** Initial routes generated by the Vite plugin (`virtual:boltdocs-routes`) */
+  routes: ComponentRoute[];
+  /** Site configuration (`virtual:boltdocs-config`) */
+  config: any;
+  /** Dynamic import mapping from `import.meta.glob` for the documentation pages */
+  modules: Record<string, () => Promise<any>>;
+  /** The `import.meta.hot` instance necessary for fast refresh/HMR updates */
+  hot?: any;
+  /** Optional custom React component to render when visiting the root path ('/') */
+  homePage?: React.ComponentType;
+  /** Optional custom MDX components provided by plugins */
+  components?: Record<string, React.ComponentType<any>>;
+}
+
+export function AppShell({
+  initialRoutes,
+  initialConfig,
+  modules,
+  hot,
+  homePage: HomePage,
+  components: customComponents = {},
+}: {
+  initialRoutes: ComponentRoute[];
+  initialConfig: any;
+  modules: Record<string, () => Promise<any>>;
+  hot?: any;
+  homePage?: React.ComponentType;
+  components?: Record<string, React.ComponentType<any>>;
+}) {
+  const [routesInfo, setRoutesInfo] = useState<ComponentRoute[]>(initialRoutes);
+  const [config] = useState(initialConfig);
+  const [resolvedRoutes, setResolvedRoutes] = useState<any[]>([]);
+
+  // Subscribe to HMR events
+  useEffect(() => {
+    if (hot) {
+      hot.on("boltdocs:routes-update", (newRoutes: ComponentRoute[]) => {
+        setRoutesInfo(newRoutes);
+      });
+    }
+  }, [hot]);
+
+  // Resolve MDX components
+  useEffect(() => {
+    const mapped = routesInfo
+      .filter(
+        (route) => !(HomePage && (route.path === "/" || route.path === "")),
+      )
+      .map((route) => {
+        const loaderKey = Object.keys(modules).find((k) =>
+          k.endsWith("/" + route.filePath),
+        );
+        const loader = loaderKey ? modules[loaderKey] : null;
+
+        return {
+          ...route,
+          Component: React.lazy(() => {
+            if (!loader)
+              return Promise.resolve({ default: () => <NotFound /> });
+            return loader() as any;
+          }),
+        };
+      });
+
+    setResolvedRoutes(mapped);
+  }, [routesInfo, modules]);
+
+  return (
+    <ConfigContext.Provider value={config}>
+      <PreloadProvider routes={routesInfo} modules={modules}>
+        <ScrollHandler />
+        <Routes>
+          {/* Custom home page WITHOUT docs layout */}
+          {HomePage && (
+            <Route
+              path="/"
+              element={
+                <ThemeLayout
+                  config={config}
+                  routes={routesInfo}
+                  sidebar={null}
+                  toc={null}
+                  breadcrumbs={null}
+                  {...config.themeConfig?.layoutProps}
+                >
+                  <HomePage />
+                </ThemeLayout>
+              }
+            />
+          )}
+
+          {/* Documentation pages WITH sidebar + TOC layout */}
+          <Route element={<DocsLayout config={config} routes={routesInfo} />}>
+            {resolvedRoutes.map((route: any) => (
+              <Route
+                key={route.path}
+                path={route.path === "" ? "/" : route.path}
+                element={
+                  <React.Suspense fallback={<Loading />}>
+                    <MdxPage
+                      Component={route.Component}
+                      customComponents={customComponents}
+                    />
+                  </React.Suspense>
+                }
+              />
+            ))}
+          </Route>
+
+          <Route
+            path="*"
+            element={
+              <ThemeLayout
+                config={config}
+                routes={routesInfo}
+                {...config.themeConfig?.layoutProps}
+              >
+                <NotFound />
+              </ThemeLayout>
+            }
+          />
+        </Routes>
+      </PreloadProvider>
+    </ConfigContext.Provider>
+  );
+}
+
+/**
+ * Handles scroll restoration and hash scrolling on navigation.
+ */
+function ScrollHandler() {
+  const { pathname, hash } = useLocation();
+
+  useLayoutEffect(() => {
+    if (hash) {
+      const id = hash.replace("#", "");
+      const element = document.getElementById(id);
+      if (element) {
+        const offset = 80;
+        const bodyRect = document.body.getBoundingClientRect().top;
+        const elementRect = element.getBoundingClientRect().top;
+        const elementPosition = elementRect - bodyRect;
+        const offsetPosition = elementPosition - offset;
+
+        window.scrollTo({
+          top: offsetPosition,
+          behavior: "smooth",
+        });
+        return;
+      }
+    }
+    window.scrollTo(0, 0);
+  }, [pathname, hash]);
+
+  return null;
+}
+
+/** Wrapper layout for doc pages (sidebar + content + TOC) */
+function DocsLayout({
+  config,
+  routes,
+}: {
+  config: any;
+  routes: ComponentRoute[];
+}) {
+  return (
+    <ThemeLayout
+      config={config}
+      routes={routes}
+      {...config.themeConfig?.layoutProps}
+    >
+      <Outlet />
+    </ThemeLayout>
+  );
+}
+
+/**
+ * Renders an MDX page securely, injecting required custom components.
+ * For example, this overrides the default `<pre>` HTML tags emitted by MDX
+ * with the Boltdocs `CodeBlock` component for syntax highlighting.
+ *
+ * @param props - Contains the dynamically loaded React component representing the MDX page
+ */
+function MdxPage({
+  Component,
+  customComponents = {},
+}: {
+  Component: React.LazyExoticComponent<any>;
+  customComponents?: Record<string, React.ComponentType<any>>;
+}) {
+  const allComponents = { ...mdxComponents, ...customComponents };
+  return (
+    <MDXProvider components={allComponents}>
+      <Component />
+    </MDXProvider>
+  );
+}
+
+/**
+ * Creates and mounts the Boltdocs documentation app.
+ *
+ * Usage:
+ * ```tsx
+ * import { createBoltdocsApp } from 'boltdocs/client'
+ * import routes from 'virtual:boltdocs-routes'
+ * import config from 'virtual:boltdocs-config'
+ * import 'boltdocs/style.css'
+ * import HomePage from './HomePage'
+ *
+ * createBoltdocsApp({
+ *   target: '#root',
+ *   routes,
+ *   config,
+ *   modules: import.meta.glob('/docs/**\/*.{md,mdx}'),
+ *   hot: import.meta.hot,
+ *   homePage: HomePage,
+ * })
+ * ```
+ */
+export function createBoltdocsApp(options: CreateBoltdocsAppOptions) {
+  const { target, routes, config, modules, hot, homePage } = options;
+  const container = document.querySelector(target);
+  if (!container) {
+    throw new Error(
+      `[boltdocs] Mount target "${target}" not found in document.`,
+    );
+  }
+
+  const app = (
+    <React.StrictMode>
+      <BrowserRouter>
+        <AppShell
+          initialRoutes={routes}
+          initialConfig={config}
+          modules={modules}
+          hot={hot}
+          homePage={homePage}
+          components={options.components}
+        />
+      </BrowserRouter>
+    </React.StrictMode>
+  );
+
+  // In production (built app), the HTML is pre-rendered by SSG, so we hydrate.
+  // In development, the root is empty, so we createRoot.
+  if (import.meta.env.PROD && container.innerHTML.trim() !== "") {
+    ReactDOM.hydrateRoot(container as HTMLElement, app);
+  } else {
+    ReactDOM.createRoot(container as HTMLElement).render(app);
+  }
+}

package/src/client/app/preload.tsx

@@ -0,0 +1,56 @@
+import React, { createContext, useContext, useCallback } from "react";
+import { ComponentRoute } from "./index";
+
+interface PreloadContextType {
+  preload: (path: string) => void;
+}
+
+const PreloadContext = createContext<PreloadContextType>({
+  preload: () => {},
+});
+
+export function usePreload() {
+  return useContext(PreloadContext);
+}
+
+export function PreloadProvider({
+  routes,
+  modules,
+  children,
+}: {
+  routes: ComponentRoute[];
+  modules: Record<string, () => Promise<any>>;
+  children: React.ReactNode;
+}) {
+  const preload = useCallback(
+    (path: string) => {
+      // Normalize path (remove hash and search)
+      const cleanPath = path.split("#")[0].split("?")[0];
+
+      // Support index routes matching "/"
+      const route = routes.find(
+        (r) => r.path === cleanPath || (cleanPath === "/" && r.path === ""),
+      );
+
+      if (route && route.filePath) {
+        const loaderKey = Object.keys(modules).find((k) =>
+          k.endsWith("/" + route.filePath),
+        );
+
+        if (loaderKey) {
+          // Trigger the dynamic import
+          modules[loaderKey]().catch((err: any) => {
+            console.error(`[boltdocs] Failed to preload route ${path}:`, err);
+          });
+        }
+      }
+    },
+    [routes, modules],
+  );
+
+  return (
+    <PreloadContext.Provider value={{ preload }}>
+      {children}
+    </PreloadContext.Provider>
+  );
+}

package/src/client/index.ts

@@ -0,0 +1,40 @@
+export type { BoltdocsConfig, BoltdocsThemeConfig } from "../node/config";
+export type { ComponentRoute, CreateBoltdocsAppOptions } from "./app";
+export { createBoltdocsApp } from "./app";
+export { ThemeLayout } from "./theme/ui/Layout";
+export { Navbar } from "./theme/ui/Navbar";
+export { Sidebar } from "./theme/ui/Sidebar";
+export { OnThisPage } from "./theme/ui/OnThisPage";
+export { Head } from "./theme/ui/Head";
+export { Breadcrumbs } from "./theme/ui/Breadcrumbs";
+export { BackgroundGradient } from "./theme/ui/BackgroundGradient";
+export { Playground } from "./theme/components/Playground";
+export { NotFound } from "./theme/ui/NotFound";
+export { Loading } from "./theme/ui/Loading";
+export { CodeBlock } from "./theme/components/CodeBlock";
+export { Video } from "./theme/components/Video";
+export {
+  Button,
+  Badge,
+  Card,
+  Cards,
+  Tabs,
+  Tab,
+  Admonition,
+  Note,
+  Tip,
+  Warning,
+  Danger,
+  InfoBox,
+  List,
+} from "./theme/components/mdx";
+export type {
+  ButtonProps,
+  BadgeProps,
+  CardProps,
+  CardsProps,
+  TabsProps,
+  TabProps,
+  AdmonitionProps,
+  ListProps,
+} from "./theme/components/mdx";

package/src/client/ssr.tsx

@@ -0,0 +1,50 @@
+import React from "react";
+import ReactDOMServer from "react-dom/server";
+import { StaticRouter } from "react-router-dom/server";
+import { AppShell, ComponentRoute } from "./app";
+
+/**
+ * Options for rendering the Boltdocs application on the server (SSG).
+ */
+export interface RenderOptions {
+  /** The URL path currently being rendered */
+  path: string;
+  /** Initial routes generated by the Vite plugin (`virtual:boltdocs-routes`) */
+  routes: ComponentRoute[];
+  /** Site configuration (`virtual:boltdocs-config`) */
+  config: any;
+  /** Optional custom React component to render when visiting the root path ('/') */
+  homePage?: React.ComponentType;
+  /** Preloaded modules (since SSR cannot use dynamic imports easily) */
+  modules: Record<string, any>;
+}
+
+/**
+ * Renders the full React application into an HTML string for a specific route.
+ * This is called by the Node SSG script during the Vite build process.
+ */
+export async function render(options: RenderOptions): Promise<string> {
+  const { path, routes, config, modules, homePage } = options;
+
+  // For SSR, we must resolve modules synchronously. We create a mock 'loader'
+  // that instantly returns the module since the SSG script already loaded it.
+  const resolvedModules: Record<string, () => Promise<any>> = {};
+  for (const [key, mod] of Object.entries(modules)) {
+    resolvedModules[key] = () => Promise.resolve(mod);
+  }
+
+  const html = ReactDOMServer.renderToString(
+    <React.StrictMode>
+      <StaticRouter location={path}>
+        <AppShell
+          initialRoutes={routes}
+          initialConfig={config}
+          modules={resolvedModules}
+          homePage={homePage}
+        />
+      </StaticRouter>
+    </React.StrictMode>,
+  );
+
+  return html;
+}