boltdocs 1.4.0 → 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

@@ -64,7 +64,8 @@ function escapeXml(str) {
 }
 function fileToRoutePath(relativePath) {
   let cleanedPath = relativePath.split("/").map(stripNumberPrefix).join("/");
-  let routePath = cleanedPath.replace(/\.mdx?$/, "");
+  let routePath = cleanedPath.replace(/\/$/, "");
+  routePath = routePath.replace(/\.mdx?$/, "");
   if (routePath === "index" || routePath.endsWith("/index")) {
     routePath = routePath.replace(/index$/, "");
   }
@@ -478,7 +479,12 @@ function parseDocFile(file, docsDir, basePath, config) {
     }
   }
   const cleanRelativePath = parts.join("/");
-  const cleanRoutePath = fileToRoutePath(cleanRelativePath || "index.md");
+  let cleanRoutePath;
+  if (data.permalink) {
+    cleanRoutePath = data.permalink.startsWith("/") ? data.permalink : `/${data.permalink}`;
+  } else {
+    cleanRoutePath = fileToRoutePath(cleanRelativePath || "index.md");
+  }
   let finalPath = basePath;
   if (version) {
     finalPath += "/" + version;
@@ -508,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: {
@@ -677,8 +687,8 @@ var CONFIG_FILES = [
   "boltdocs.config.mjs",
   "boltdocs.config.ts"
 ];
-async function resolveConfig(docsDir) {
-  const projectRoot = process.cwd();
+async function resolveConfig(docsDir, root = process.cwd()) {
+  const projectRoot = root;
   const defaults = {
     docsDir: import_path3.default.resolve(docsDir),
     themeConfig: {
@@ -694,7 +704,8 @@ async function resolveConfig(docsDir) {
     const configPath = import_path3.default.resolve(projectRoot, filename);
     if (import_fs3.default.existsSync(configPath)) {
       try {
-        const fileUrl = (0, import_url.pathToFileURL)(configPath).href + "?t=" + Date.now();
+        const isTest = process.env.NODE_ENV === "test" || global.__vitest_worker__;
+        const fileUrl = (0, import_url.pathToFileURL)(configPath).href + (isTest ? "" : "?t=" + Date.now());
         const mod = await import(fileUrl);
         const userConfig = mod.default || mod;
         const userThemeConfig = userConfig.themeConfig || userConfig;
@@ -806,12 +817,6 @@ async function generateStaticPages(options) {
     return;
   }
   const template = import_fs4.default.readFileSync(templatePath, "utf-8");
-  let homePageComp;
-  if (config?._homePagePath) {
-    try {
-    } catch (e) {
-    }
-  }
   await Promise.all(
     routes.map(async (route) => {
       const pageTitle = `${route.title} | ${siteTitle}`;
@@ -825,7 +830,8 @@ async function generateStaticPages(options) {
           routes,
           config: config || {},
           modules: fakeModules,
-          homePage: homePageComp
+          homePage: void 0
+          // No custom home page for now
         });
         const html = replaceMetaTags(template, {
           title: escapeHtml(pageTitle),
@@ -1070,10 +1076,10 @@ var import_crypto2 = __toESM(require("crypto"));
 init_cache();
 var mdxCache = new TransformCache("mdx");
 var mdxCacheLoaded = false;
-function boltdocsMdxPlugin(config) {
+function boltdocsMdxPlugin(config, compiler = import_rollup.default) {
   const extraRemarkPlugins = config?.plugins?.flatMap((p) => p.remarkPlugins || []) || [];
   const extraRehypePlugins = config?.plugins?.flatMap((p) => p.rehypePlugins || []) || [];
-  const baseMdxPlugin = (0, import_rollup.default)({
+  const baseMdxPlugin = compiler({
     remarkPlugins: [import_remark_gfm.default, import_remark_frontmatter.default, ...extraRemarkPlugins],
     rehypePlugins: [
       import_rehype_slug.default,
@@ -1089,6 +1095,9 @@ function boltdocsMdxPlugin(config) {
     jsxRuntime: "automatic",
     providerImportSource: "@mdx-js/react"
   });
+  if (baseMdxPlugin.isMock) {
+    console.log("MDX PLUGIN IS MOCKED");
+  }
   return {
     ...baseMdxPlugin,
     name: "vite-plugin-boltdocs-mdx",
@@ -1123,8 +1132,6 @@ function boltdocsMdxPlugin(config) {
       );
       if (result && typeof result === "object" && result.code) {
         mdxCache.set(cacheKey, result.code);
-      } else if (typeof result === "string") {
-        mdxCache.set(cacheKey, result);
       }
       return result;
     },

package/dist/node/index.mjs

@@ -10,7 +10,7 @@ import {
   normalizePath,
   parseFrontmatter,
   stripNumberPrefix
-} from "../chunk-CYBWLFOG.mjs";
+} from "../chunk-FFBNU6IJ.mjs";
 
 // src/node/plugin/index.ts
 import { loadEnv } from "vite";
@@ -61,7 +61,12 @@ function parseDocFile(file, docsDir, basePath, config) {
     }
   }
   const cleanRelativePath = parts.join("/");
-  const cleanRoutePath = fileToRoutePath(cleanRelativePath || "index.md");
+  let cleanRoutePath;
+  if (data.permalink) {
+    cleanRoutePath = data.permalink.startsWith("/") ? data.permalink : `/${data.permalink}`;
+  } else {
+    cleanRoutePath = fileToRoutePath(cleanRelativePath || "index.md");
+  }
   let finalPath = basePath;
   if (version) {
     finalPath += "/" + version;
@@ -91,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: {
@@ -260,8 +269,8 @@ var CONFIG_FILES = [
   "boltdocs.config.mjs",
   "boltdocs.config.ts"
 ];
-async function resolveConfig(docsDir) {
-  const projectRoot = process.cwd();
+async function resolveConfig(docsDir, root = process.cwd()) {
+  const projectRoot = root;
   const defaults = {
     docsDir: path2.resolve(docsDir),
     themeConfig: {
@@ -277,7 +286,8 @@ async function resolveConfig(docsDir) {
     const configPath = path2.resolve(projectRoot, filename);
     if (fs.existsSync(configPath)) {
       try {
-        const fileUrl = pathToFileURL(configPath).href + "?t=" + Date.now();
+        const isTest = process.env.NODE_ENV === "test" || global.__vitest_worker__;
+        const fileUrl = pathToFileURL(configPath).href + (isTest ? "" : "?t=" + Date.now());
         const mod = await import(fileUrl);
         const userConfig = mod.default || mod;
         const userThemeConfig = userConfig.themeConfig || userConfig;
@@ -385,12 +395,6 @@ async function generateStaticPages(options) {
     return;
   }
   const template = fs2.readFileSync(templatePath, "utf-8");
-  let homePageComp;
-  if (config?._homePagePath) {
-    try {
-    } catch (e) {
-    }
-  }
   await Promise.all(
     routes.map(async (route) => {
       const pageTitle = `${route.title} | ${siteTitle}`;
@@ -404,7 +408,8 @@ async function generateStaticPages(options) {
           routes,
           config: config || {},
           modules: fakeModules,
-          homePage: homePageComp
+          homePage: void 0
+          // No custom home page for now
         });
         const html = replaceMetaTags(template, {
           title: escapeHtml(pageTitle),
@@ -430,7 +435,7 @@ async function generateStaticPages(options) {
   console.log(
     `[boltdocs] Generated ${routes.length} static pages + sitemap.xml`
   );
-  const { flushCache } = await import("../cache-GQHF6BXI.mjs");
+  const { flushCache } = await import("../cache-KNL5B4EE.mjs");
   await flushCache();
 }
 
@@ -612,7 +617,7 @@ function boltdocsPlugin(options = {}, passedConfig) {
         if (!isBuild) return;
         const outDir = viteConfig?.build?.outDir ? path4.resolve(viteConfig.root, viteConfig.build.outDir) : path4.resolve(process.cwd(), "dist");
         await generateStaticPages({ docsDir, outDir, config });
-        const { flushCache } = await import("../cache-GQHF6BXI.mjs");
+        const { flushCache } = await import("../cache-KNL5B4EE.mjs");
         await flushCache();
       }
     },
@@ -646,10 +651,10 @@ import rehypePrettyCode from "rehype-pretty-code";
 import crypto from "crypto";
 var mdxCache = new TransformCache("mdx");
 var mdxCacheLoaded = false;
-function boltdocsMdxPlugin(config) {
+function boltdocsMdxPlugin(config, compiler = mdxPlugin) {
   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,
@@ -665,6 +670,9 @@ function boltdocsMdxPlugin(config) {
     jsxRuntime: "automatic",
     providerImportSource: "@mdx-js/react"
   });
+  if (baseMdxPlugin.isMock) {
+    console.log("MDX PLUGIN IS MOCKED");
+  }
   return {
     ...baseMdxPlugin,
     name: "vite-plugin-boltdocs-mdx",
@@ -699,8 +707,6 @@ function boltdocsMdxPlugin(config) {
       );
       if (result && typeof result === "object" && result.code) {
         mdxCache.set(cacheKey, result.code);
-      } else if (typeof result === "string") {
-        mdxCache.set(cacheKey, result);
       }
       return result;
     },

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.0",
+  "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}
+          />
+        )}
+      </>
     );
   },
 );