boltdocs 1.4.0 → 1.5.0

package/src/client/theme/ui/Link/LinkPreview.tsx

@@ -0,0 +1,64 @@
+import { useEffect, useState, useRef } from "react";
+import { createPortal } from "react-dom";
+import "./link-preview.css";
+
+interface LinkPreviewProps {
+  isVisible: boolean;
+  title: string;
+  summary?: string;
+  x: number;
+  y: number;
+}
+
+export function LinkPreview({
+  isVisible,
+  title,
+  summary,
+  x,
+  y,
+}: LinkPreviewProps) {
+  const [mounted, setMounted] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+  const [position, setPosition] = useState({ top: 0, left: 0 });
+
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  useEffect(() => {
+    if (isVisible && ref.current) {
+      const rect = ref.current.getBoundingClientRect();
+      const padding = 15;
+
+      let top = y + padding;
+      let left = x + padding;
+
+      // Keep within viewport
+      if (left + rect.width > window.innerWidth) {
+        left = x - rect.width - padding;
+      }
+      if (top + rect.height > window.innerHeight) {
+        top = y - rect.height - padding;
+      }
+
+      setPosition({ top, left });
+    }
+  }, [isVisible, x, y]);
+
+  if (!mounted) return null;
+
+  return createPortal(
+    <div
+      ref={ref}
+      className={`boltdocs-link-preview ${isVisible ? "is-visible" : ""}`}
+      style={{
+        top: position.top,
+        left: position.left,
+      }}
+    >
+      <span className="boltdocs-link-preview-title">{title}</span>
+      {summary && <p className="boltdocs-link-preview-summary">{summary}</p>}
+    </div>,
+    document.body,
+  );
+}

package/src/client/theme/ui/Link/link-preview.css

@@ -0,0 +1,64 @@
+.boltdocs-link-preview {
+  position: fixed;
+  z-index: 1000;
+  width: 320px;
+  padding: 1rem;
+  background-color: var(--ld-navbar-bg);
+  backdrop-filter: blur(var(--ld-navbar-blur));
+  -webkit-backdrop-filter: blur(var(--ld-navbar-blur));
+  border: 1px solid var(--ld-border-subtle);
+  border-radius: var(--ld-radius-md);
+  box-shadow:
+    0 10px 25px -5px rgba(0, 0, 0, 0.1),
+    0 8px 10px -6px rgba(0, 0, 0, 0.1);
+  pointer-events: none;
+  opacity: 0;
+  transform: translateY(10px) scale(0.95);
+  transition:
+    opacity 0.2s cubic-bezier(0.4, 0, 0.2, 1),
+    transform 0.2s cubic-bezier(0.4, 0, 0.2, 1);
+  font-family: var(--ld-font-sans);
+}
+
+.boltdocs-link-preview.is-visible {
+  opacity: 1;
+  transform: translateY(0) scale(1);
+}
+
+.boltdocs-link-preview-title {
+  display: block;
+  font-weight: 600;
+  font-size: 0.95rem;
+  color: var(--ld-text-main);
+  margin-bottom: 0.5rem;
+  line-height: 1.4;
+}
+
+.boltdocs-link-preview-summary {
+  display: block;
+  font-size: 0.85rem;
+  color: var(--ld-text-muted);
+  line-height: 1.5;
+  display: -webkit-box;
+  -webkit-line-clamp: 4;
+  line-clamp: 4;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
+/* Dark mode adjustments */
+[data-theme="dark"] .boltdocs-link-preview {
+  background-color: var(--ld-navbar-bg);
+  border-color: var(--ld-border-subtle);
+  box-shadow:
+    0 20px 25px -5px rgba(0, 0, 0, 0.3),
+    0 10px 10px -5px rgba(0, 0, 0, 0.2);
+}
+
+[data-theme="dark"] .boltdocs-link-preview-title {
+  color: #f8fafc;
+}
+
+[data-theme="dark"] .boltdocs-link-preview-summary {
+  color: #94a3b8;
+}

package/src/client/types.ts

@@ -23,6 +23,8 @@ export interface ComponentRoute {
   groupPosition?: number;
   /** Extracted markdown headings for search indexing */
   headings?: { level: number; text: string; id: string }[];
+  /** The page summary or description */
+  description?: string;
   /** The locale this route belongs to, if i18n is configured */
   locale?: string;
   /** The version this route belongs to, if versioning is configured */

package/src/node/config.ts

@@ -53,6 +53,8 @@ export interface BoltdocsThemeConfig {
   githubRepo?: string;
   /** Whether to show the 'Powered by LiteDocs' badge in the sidebar (default: true) */
   poweredBy?: boolean;
+  /** Whether to show a preview tooltip on internal links hover (default: true) */
+  linkPreview?: boolean;
   /** Granular layout customization props */
   layoutProps?: {
     navbar?: any;
@@ -139,11 +141,15 @@ export const CONFIG_FILES = [
  * 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
+ * @param docsDir - The directory containing the documentation files
+ * @param root - The project root directory (defaults to process.cwd())
+ * @returns The merged configuration object
  */
-export async function resolveConfig(docsDir: string): Promise<BoltdocsConfig> {
-  const projectRoot = process.cwd();
+export async function resolveConfig(
+  docsDir: string,
+  root: string = process.cwd(),
+): Promise<BoltdocsConfig> {
+  const projectRoot = root;
 
   const defaults: BoltdocsConfig = {
     docsDir: path.resolve(docsDir),
@@ -162,8 +168,11 @@ export async function resolveConfig(docsDir: string): Promise<BoltdocsConfig> {
     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();
+        // Add a timestamp query parameter to bust the ESM cache in dev
+        const isTest =
+          process.env.NODE_ENV === "test" || (global as any).__vitest_worker__;
+        const fileUrl =
+          pathToFileURL(configPath).href + (isTest ? "" : "?t=" + Date.now());
         const mod = await import(fileUrl);
         const userConfig = mod.default || mod;
 

package/src/node/mdx.ts

@@ -24,15 +24,19 @@ let mdxCacheLoaded = false;
  * Also wraps the plugin with a persistent cache to avoid re-compiling unchanged MDX files.
  *
  * @param config - The Boltdocs configuration containing custom plugins
+ * @param compiler - The MDX compiler plugin (for testing)
  * @returns A Vite plugin configured for MDX parsing with caching
  */
-export function boltdocsMdxPlugin(config?: BoltdocsConfig): Plugin {
+export function boltdocsMdxPlugin(
+  config?: BoltdocsConfig,
+  compiler = mdxPlugin,
+): Plugin {
   const extraRemarkPlugins =
     config?.plugins?.flatMap((p) => p.remarkPlugins || []) || [];
   const extraRehypePlugins =
     config?.plugins?.flatMap((p) => p.rehypePlugins || []) || [];
 
-  const baseMdxPlugin = mdxPlugin({
+  const baseMdxPlugin = compiler({
     remarkPlugins: [remarkGfm, remarkFrontmatter, ...extraRemarkPlugins],
     rehypePlugins: [
       rehypeSlug,
@@ -49,6 +53,11 @@ export function boltdocsMdxPlugin(config?: BoltdocsConfig): Plugin {
     providerImportSource: "@mdx-js/react",
   }) as Plugin;
 
+  // @ts-ignore
+  if (baseMdxPlugin.isMock) {
+    console.log("MDX PLUGIN IS MOCKED");
+  }
+
   return {
     ...baseMdxPlugin,
     name: "vite-plugin-boltdocs-mdx",
@@ -90,8 +99,6 @@ export function boltdocsMdxPlugin(config?: BoltdocsConfig): Plugin {
 
       if (result && typeof result === "object" && result.code) {
         mdxCache.set(cacheKey, result.code);
-      } else if (typeof result === "string") {
-        mdxCache.set(cacheKey, result);
       }
 
       return result;

package/src/node/routes/parser.ts

@@ -70,7 +70,16 @@ export function parseDocFile(
   }
 
   const cleanRelativePath = parts.join("/");
-  const cleanRoutePath = fileToRoutePath(cleanRelativePath || "index.md");
+
+  let cleanRoutePath: string;
+  if (data.permalink) {
+    // If a permalink is specified, ensure it starts with a slash
+    cleanRoutePath = data.permalink.startsWith("/")
+      ? data.permalink
+      : `/${data.permalink}`;
+  } else {
+    cleanRoutePath = fileToRoutePath(cleanRelativePath || "index.md");
+  }
 
   let finalPath = basePath;
   if (version) {
@@ -113,9 +122,22 @@ export function parseDocFile(
   }
 
   const sanitizedTitle = data.title ? escapeHtml(data.title) : inferredTitle;
-  const sanitizedDescription = data.description
+  let sanitizedDescription = data.description
     ? escapeHtml(data.description)
     : "";
+
+  // If no description is provided, extract a summary from the content
+  if (!sanitizedDescription && content) {
+    const summary = content
+      .replace(/^#+.*$/gm, "") // Remove headers
+      .replace(/\[([^\]]+)\]\([^\)]+\)/g, "$1") // Simplify links
+      .replace(/[_*`]/g, "") // Remove formatting
+      .replace(/\n+/g, " ") // Normalize whitespace
+      .trim()
+      .slice(0, 160);
+    sanitizedDescription = escapeHtml(summary);
+  }
+
   const sanitizedBadge = data.badge ? escapeHtml(data.badge) : undefined;
 
   return {

package/src/node/ssg/index.ts

@@ -49,15 +49,6 @@ export async function generateStaticPages(options: SSGOptions): Promise<void> {
   }
   const template = fs.readFileSync(templatePath, "utf-8");
 
-  // Load user's homePage if configured
-  let homePageComp;
-  if ((config as any)?._homePagePath) {
-    try {
-      // Simplistic: if there's a custom home page compiled, we'd need it available to SSR.
-      // In a full framework this is complex, but for Boltdocs we assume it's bundled if needed.
-    } catch (e) {}
-  }
-
   // Generate an HTML file for each route concurrently
   await Promise.all(
     routes.map(async (route) => {
@@ -74,7 +65,7 @@ export async function generateStaticPages(options: SSGOptions): Promise<void> {
           routes: routes,
           config: config || {},
           modules: fakeModules,
-          homePage: homePageComp,
+          homePage: undefined, // No custom home page for now
         });
 
         const html = replaceMetaTags(template, {

package/src/node/utils.ts

@@ -113,7 +113,10 @@ export function fileToRoutePath(relativePath: string): string {
   // Strip number prefixes from every segment
   let cleanedPath = relativePath.split("/").map(stripNumberPrefix).join("/");
 
-  let routePath = cleanedPath.replace(/\.mdx?$/, "");
+  // Remove trailing slash if present
+  let routePath = cleanedPath.replace(/\/$/, "");
+
+  routePath = routePath.replace(/\.mdx?$/, "");
 
   // Handle index files → directory root
   if (routePath === "index" || routePath.endsWith("/index")) {

package/dist/CodeBlock-QYIKJMEB.mjs

@@ -1,7 +0,0 @@
-import {
-  CodeBlock
-} from "./chunk-KS5B3O6W.mjs";
-import "./chunk-FMTOYQLO.mjs";
-export {
-  CodeBlock
-};

package/dist/chunk-KS5B3O6W.mjs

@@ -1,43 +0,0 @@
-import {
-  copyToClipboard
-} from "./chunk-FMTOYQLO.mjs";
-
-// src/client/theme/components/CodeBlock/CodeBlock.tsx
-import React, { useState, useRef, useCallback } from "react";
-import { Copy, Check } from "lucide-react";
-import { jsx, jsxs } from "react/jsx-runtime";
-function CodeBlock({ children, ...props }) {
-  const [copied, setCopied] = useState(false);
-  const preRef = useRef(null);
-  let language = "";
-  if (React.isValidElement(children)) {
-    const childProps = children.props;
-    language = childProps?.["data-language"] || "";
-    if (!language && childProps?.className) {
-      const match = childProps.className.match(/language-(\w+)/);
-      if (match) language = match[1];
-    }
-  }
-  const handleCopy = useCallback(async () => {
-    const code = preRef.current?.textContent || "";
-    copyToClipboard(code);
-    setCopied(true);
-    setTimeout(() => setCopied(false), 2e3);
-  }, []);
-  return /* @__PURE__ */ jsxs("div", { className: "code-block-wrapper", children: [
-    /* @__PURE__ */ jsx(
-      "button",
-      {
-        className: `code-block-copy ${copied ? "copied" : ""}`,
-        onClick: handleCopy,
-        "aria-label": "Copy code",
-        children: copied ? /* @__PURE__ */ jsx(Check, { size: 16 }) : /* @__PURE__ */ jsx(Copy, { size: 16 })
-      }
-    ),
-    /* @__PURE__ */ jsx("pre", { ref: preRef, ...props, children })
-  ] });
-}
-
-export {
-  CodeBlock
-};