boltdocs 1.4.1 → 1.5.0

package/dist/client/ssr.mjs

@@ -1,6 +1,6 @@
 import {
   AppShell
-} from "../chunk-D7YBQG6H.mjs";
+} from "../chunk-FMQ4HRKZ.mjs";
 import "../chunk-FMTOYQLO.mjs";
 
 // src/client/ssr.tsx

package/dist/{config-BD5ZHz15.d.mts → config-DkZg5aCf.d.mts}

@@ -54,6 +54,8 @@ 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;

package/dist/{config-BD5ZHz15.d.ts → config-DkZg5aCf.d.ts}

@@ -54,6 +54,8 @@ 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;

package/dist/node/index.d.mts

@@ -1,6 +1,6 @@
 import { Plugin } from 'vite';
-import { B as BoltdocsConfig } from '../config-BD5ZHz15.mjs';
-export { a as BoltdocsThemeConfig } from '../config-BD5ZHz15.mjs';
+import { B as BoltdocsConfig } from '../config-DkZg5aCf.mjs';
+export { a as BoltdocsThemeConfig } from '../config-DkZg5aCf.mjs';
 
 /**
  * Configuration options specifically for the Boltdocs Vite plugin.

package/dist/node/index.d.ts

@@ -1,6 +1,6 @@
 import { Plugin } from 'vite';
-import { B as BoltdocsConfig } from '../config-BD5ZHz15.js';
-export { a as BoltdocsThemeConfig } from '../config-BD5ZHz15.js';
+import { B as BoltdocsConfig } from '../config-DkZg5aCf.js';
+export { a as BoltdocsThemeConfig } from '../config-DkZg5aCf.js';
 
 /**
  * Configuration options specifically for the Boltdocs Vite plugin.

package/dist/node/index.js

@@ -514,7 +514,11 @@ function parseDocFile(file, docsDir, basePath, config) {
     headings.push({ level, text: escapeHtml(text), id });
   }
   const sanitizedTitle = data.title ? escapeHtml(data.title) : inferredTitle;
-  const sanitizedDescription = data.description ? escapeHtml(data.description) : "";
+  let sanitizedDescription = data.description ? escapeHtml(data.description) : "";
+  if (!sanitizedDescription && content) {
+    const summary = content.replace(/^#+.*$/gm, "").replace(/\[([^\]]+)\]\([^\)]+\)/g, "$1").replace(/[_*`]/g, "").replace(/\n+/g, " ").trim().slice(0, 160);
+    sanitizedDescription = escapeHtml(summary);
+  }
   const sanitizedBadge = data.badge ? escapeHtml(data.badge) : void 0;
   return {
     route: {

package/dist/node/index.mjs

@@ -96,7 +96,11 @@ function parseDocFile(file, docsDir, basePath, config) {
     headings.push({ level, text: escapeHtml(text), id });
   }
   const sanitizedTitle = data.title ? escapeHtml(data.title) : inferredTitle;
-  const sanitizedDescription = data.description ? escapeHtml(data.description) : "";
+  let sanitizedDescription = data.description ? escapeHtml(data.description) : "";
+  if (!sanitizedDescription && content) {
+    const summary = content.replace(/^#+.*$/gm, "").replace(/\[([^\]]+)\]\([^\)]+\)/g, "$1").replace(/[_*`]/g, "").replace(/\n+/g, " ").trim().slice(0, 160);
+    sanitizedDescription = escapeHtml(summary);
+  }
   const sanitizedBadge = data.badge ? escapeHtml(data.badge) : void 0;
   return {
     route: {

package/dist/{types-CvrzTbEX.d.mts → types-DGIo1VKD.d.mts}

@@ -27,6 +27,8 @@ interface ComponentRoute {
         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/dist/{types-CvrzTbEX.d.ts → types-DGIo1VKD.d.ts}

@@ -27,6 +27,8 @@ interface ComponentRoute {
         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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "boltdocs",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "A lightweight documentation generator for React projects.",
   "main": "dist/node/index.js",
   "module": "dist/node/index.mjs",

package/src/client/app/index.tsx

@@ -27,11 +27,7 @@ export function useConfig() {
   return useContext(ConfigContext);
 }
 
-const CodeBlock = lazy(() =>
-  import("../theme/components/CodeBlock").then((m) => ({
-    default: m.CodeBlock,
-  })),
-);
+import { CodeBlock } from "../theme/components/CodeBlock";
 const Video = lazy(() =>
   import("../theme/components/Video").then((m) => ({ default: m.Video })),
 );
@@ -77,13 +73,7 @@ const mdxComponents = {
   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>
-    );
-  },
+  pre: (props: any) => <CodeBlock {...props}>{props.children}</CodeBlock>,
   video: (props: any) => (
     <Suspense fallback={<div className="video-skeleton" />}>
       <Video {...props} />

package/src/client/app/preload.tsx

@@ -3,10 +3,12 @@ import { ComponentRoute } from "../types";
 
 interface PreloadContextType {
   preload: (path: string) => void;
+  routes: ComponentRoute[];
 }
 
 const PreloadContext = createContext<PreloadContextType>({
   preload: () => {},
+  routes: [],
 });
 
 export function usePreload() {
@@ -49,7 +51,7 @@ export function PreloadProvider({
   );
 
   return (
-    <PreloadContext.Provider value={{ preload }}>
+    <PreloadContext.Provider value={{ preload, routes }}>
       {children}
     </PreloadContext.Provider>
   );

package/src/client/theme/components/CodeBlock/CodeBlock.tsx

@@ -16,17 +16,6 @@ export function CodeBlock({ children, ...props }: CodeBlockProps) {
   const [copied, setCopied] = useState(false);
   const preRef = useRef<HTMLPreElement>(null);
 
-  // Extract language from the child <code> element's data-language or className
-  let language = "";
-  if (React.isValidElement(children)) {
-    const childProps = children.props as any;
-    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);

package/src/client/theme/styles/markdown.css

@@ -218,7 +218,7 @@
   right: 0.75rem;
   z-index: 50;
   padding: 0.4rem;
-  background-color: rgba(20, 20, 30, 0.8);
+  background-color: var(--ld-surface);
   backdrop-filter: blur(8px);
   -webkit-backdrop-filter: blur(8px);
   border: 1px solid var(--ld-border-subtle);
@@ -227,14 +227,10 @@
   cursor: pointer;
   transition: all 0.2s ease;
   opacity: 0;
-  visibility: hidden;
-  pointer-events: none;
 }
 
 .code-block-wrapper:hover .code-block-copy {
   opacity: 1;
-  visibility: visible;
-  pointer-events: auto;
 }
 
 .code-block-copy:hover {

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

@@ -97,25 +97,44 @@ function useLocalizedTo(to: RouterLinkProps["to"]) {
   return finalPath === basePath ? basePath : finalPath;
 }
 
+import { LinkPreview } from "./LinkPreview";
+
 export interface LinkProps extends Omit<RouterLinkProps, "prefetch"> {
   /** Should prefetch the page on hover? Options: 'hover' | 'none'. Default 'hover' */
   boltdocsPrefetch?: "hover" | "none";
+  /** Should show a preview tooltip on hover? Default true */
+  boltdocsPreview?: boolean;
 }
 
 export const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(
   (props, ref) => {
     const {
       boltdocsPrefetch = "hover",
+      boltdocsPreview = true,
       onMouseEnter,
+      onMouseLeave,
       onFocus,
+      onBlur,
       onClick,
       to,
       ...rest
     } = props;
     const localizedTo = useLocalizedTo(to);
-    const { preload } = usePreload();
+    const { preload, routes } = usePreload();
+    const config = useConfig();
     const navigate = useNavigate();
 
+    const shouldShowPreview =
+      boltdocsPreview && config?.themeConfig?.linkPreview !== false;
+
+    const [preview, setPreview] = React.useState<{
+      visible: boolean;
+      x: number;
+      y: number;
+      title: string;
+      summary?: string;
+    }>({ visible: false, x: 0, y: 0, title: "" });
+
     const handleMouseEnter = (e: React.MouseEvent<HTMLAnchorElement>) => {
       onMouseEnter?.(e);
       if (
@@ -125,6 +144,37 @@ export const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(
       ) {
         preload(localizedTo);
       }
+
+      if (
+        shouldShowPreview &&
+        typeof localizedTo === "string" &&
+        localizedTo.startsWith("/")
+      ) {
+        const cleanPath = localizedTo.split("#")[0].split("?")[0];
+        const route = routes.find(
+          (r) => r.path === cleanPath || (cleanPath === "/" && r.path === ""),
+        );
+        if (route) {
+          setPreview({
+            visible: true,
+            x: e.clientX,
+            y: e.clientY,
+            title: route.title,
+            summary: route.description,
+          });
+        }
+      }
+    };
+
+    const handleMouseMove = (e: React.MouseEvent<HTMLAnchorElement>) => {
+      if (preview.visible) {
+        setPreview((prev) => ({ ...prev, x: e.clientX, y: e.clientY }));
+      }
+    };
+
+    const handleMouseLeave = (e: React.MouseEvent<HTMLAnchorElement>) => {
+      onMouseLeave?.(e);
+      setPreview((prev) => ({ ...prev, visible: false }));
     };
 
     const handleFocus = (e: React.FocusEvent<HTMLAnchorElement>) => {
@@ -138,9 +188,15 @@ export const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(
       }
     };
 
+    const handleBlur = (e: React.FocusEvent<HTMLAnchorElement>) => {
+      onBlur?.(e);
+      setPreview((prev) => ({ ...prev, visible: false }));
+    };
+
     const handleClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
       // Allow user onClick to handle defaults or custom logic
       onClick?.(e);
+      setPreview((prev) => ({ ...prev, visible: false }));
 
       // If default prevented or not a simple left click, don't handle
       if (
@@ -164,14 +220,28 @@ export const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(
     };
 
     return (
-      <RouterLink
-        ref={ref}
-        to={localizedTo}
-        onMouseEnter={handleMouseEnter}
-        onFocus={handleFocus}
-        onClick={handleClick}
-        {...rest}
-      />
+      <>
+        <RouterLink
+          ref={ref}
+          to={localizedTo}
+          onMouseEnter={handleMouseEnter}
+          onMouseMove={handleMouseMove}
+          onMouseLeave={handleMouseLeave}
+          onFocus={handleFocus}
+          onBlur={handleBlur}
+          onClick={handleClick}
+          {...rest}
+        />
+        {shouldShowPreview && (
+          <LinkPreview
+            isVisible={preview.visible}
+            title={preview.title}
+            summary={preview.summary}
+            x={preview.x}
+            y={preview.y}
+          />
+        )}
+      </>
     );
   },
 );
@@ -180,23 +250,40 @@ Link.displayName = "Link";
 export interface NavLinkProps extends Omit<RouterNavLinkProps, "prefetch"> {
   /** Should prefetch the page on hover? Options: 'hover' | 'none'. Default 'hover' */
   boltdocsPrefetch?: "hover" | "none";
+  /** Should show a preview tooltip on hover? Default true */
+  boltdocsPreview?: boolean;
 }
 
 export const NavLink = React.forwardRef<HTMLAnchorElement, NavLinkProps>(
   (props, ref) => {
     const {
       boltdocsPrefetch = "hover",
+      boltdocsPreview = true,
       onMouseEnter,
+      onMouseLeave,
       onFocus,
+      onBlur,
       onClick,
       to,
       ...rest
     } = props;
 
     const localizedTo = useLocalizedTo(to);
-    const { preload } = usePreload();
+    const { preload, routes } = usePreload();
+    const config = useConfig();
     const navigate = useNavigate();
 
+    const shouldShowPreview =
+      boltdocsPreview && config?.themeConfig?.linkPreview !== false;
+
+    const [preview, setPreview] = React.useState<{
+      visible: boolean;
+      x: number;
+      y: number;
+      title: string;
+      summary?: string;
+    }>({ visible: false, x: 0, y: 0, title: "" });
+
     const handleMouseEnter = (e: React.MouseEvent<HTMLAnchorElement>) => {
       onMouseEnter?.(e);
       if (
@@ -206,6 +293,37 @@ export const NavLink = React.forwardRef<HTMLAnchorElement, NavLinkProps>(
       ) {
         preload(localizedTo);
       }
+
+      if (
+        shouldShowPreview &&
+        typeof localizedTo === "string" &&
+        localizedTo.startsWith("/")
+      ) {
+        const cleanPath = localizedTo.split("#")[0].split("?")[0];
+        const route = routes.find(
+          (r) => r.path === cleanPath || (cleanPath === "/" && r.path === ""),
+        );
+        if (route) {
+          setPreview({
+            visible: true,
+            x: e.clientX,
+            y: e.clientY,
+            title: route.title,
+            summary: route.description,
+          });
+        }
+      }
+    };
+
+    const handleMouseMove = (e: React.MouseEvent<HTMLAnchorElement>) => {
+      if (preview.visible) {
+        setPreview((prev) => ({ ...prev, x: e.clientX, y: e.clientY }));
+      }
+    };
+
+    const handleMouseLeave = (e: React.MouseEvent<HTMLAnchorElement>) => {
+      onMouseLeave?.(e);
+      setPreview((prev) => ({ ...prev, visible: false }));
     };
 
     const handleFocus = (e: React.FocusEvent<HTMLAnchorElement>) => {
@@ -219,8 +337,14 @@ export const NavLink = React.forwardRef<HTMLAnchorElement, NavLinkProps>(
       }
     };
 
+    const handleBlur = (e: React.FocusEvent<HTMLAnchorElement>) => {
+      onBlur?.(e);
+      setPreview((prev) => ({ ...prev, visible: false }));
+    };
+
     const handleClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
       onClick?.(e);
+      setPreview((prev) => ({ ...prev, visible: false }));
       if (
         e.defaultPrevented ||
         e.button !== 0 ||
@@ -240,14 +364,28 @@ export const NavLink = React.forwardRef<HTMLAnchorElement, NavLinkProps>(
     };
 
     return (
-      <RouterNavLink
-        ref={ref}
-        to={localizedTo}
-        onMouseEnter={handleMouseEnter}
-        onFocus={handleFocus}
-        onClick={handleClick}
-        {...rest}
-      />
+      <>
+        <RouterNavLink
+          ref={ref}
+          to={localizedTo}
+          onMouseEnter={handleMouseEnter}
+          onMouseMove={handleMouseMove}
+          onMouseLeave={handleMouseLeave}
+          onFocus={handleFocus}
+          onBlur={handleBlur}
+          onClick={handleClick}
+          {...rest}
+        />
+        {shouldShowPreview && (
+          <LinkPreview
+            isVisible={preview.visible}
+            title={preview.title}
+            summary={preview.summary}
+            x={preview.x}
+            y={preview.y}
+          />
+        )}
+      </>
     );
   },
 );

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;

package/src/node/routes/parser.ts

@@ -122,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/dist/CodeBlock-QYIKJMEB.mjs

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