create-eziwiki 0.1.0 → 0.2.0

package/README.md

@@ -16,8 +16,9 @@ A complete, static-exportable wiki:
 - **Pages from files** — every Markdown file under `content/` is published, no registration step
 - **Search** — full-text over titles, headings, and body, with a ⌘K palette; runs entirely in the browser
 - **Contents rail** with scroll tracking, generated at build time
-- **Wiki links** — `[[page]]` resolves by path, file name, or title
-- **Backlinks** on every page, and a **graph view** of how pages connect
+- **Wiki links** — `[[page]]` resolves by path, file name, or title, and hovering one previews where it goes
+- **Embeds** — `![[image.png]]` places a file, `![[page]]` includes another page's text, `![[page#section]]` just one section
+- **Backlinks** on every page, plus a graph of its **neighbourhood** — and a `/graph` view of the whole site
 - **Build-time rendering** — Markdown is compiled and syntax-highlighted during the build, so no parser ships to the browser
 - Dark mode, maths, GFM, SEO metadata, sitemap
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-eziwiki",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Scaffold a new eziwiki documentation site",
   "type": "module",
   "bin": {

package/template/app/[...slug]/page.tsx

@@ -2,7 +2,8 @@ import { MarkdownContent } from '@/components/markdown/MarkdownContent';
 import { PageTransition } from '@/components/markdown/PageTransition';
 import { TableOfContents } from '@/components/layout/TableOfContents';
 import { Backlinks } from '@/components/layout/Backlinks';
-import { getBacklinks } from '@/lib/graph/build';
+import { LocalGraph } from '@/components/layout/LocalGraph';
+import { getBacklinks, getLocalGraph } from '@/lib/graph/build';
 import { renderDoc } from '@/lib/markdown/render';
 import { getDoc, type ContentDoc } from '@/lib/content/registry';
 import { docPathToUrl, urlToDocPath } from '@/lib/navigation/url';
@@ -149,6 +150,7 @@ export default async function ContentPage({ params }: PageProps) {
           <ArticleSchema doc={doc} url={resolved.url} />
           <MarkdownContent html={rendered.html} />
           <Backlinks links={getBacklinks(resolved.path)} />
+          <LocalGraph graph={getLocalGraph(resolved.path)} path={resolved.path} />
         </article>
 
         <aside className="hidden w-56 flex-shrink-0 xl:block">

package/template/app/globals.css

@@ -9,15 +9,19 @@
 @import '../styles/markdown.css';
 
 /*
- * `@font-face` for Pretendard and SUITE is declared in `app/layout.tsx`, not
- * here: the font URLs need the deployment base path prefixed, which a
- * stylesheet cannot read. See FONT_FACES there.
+ * `@font-face` for Pretendard is declared in `app/layout.tsx`, not here: the
+ * font URLs need the deployment base path prefixed, which a stylesheet cannot
+ * read. See FONT_FACES there, which also splits each weight by `unicode-range`
+ * so a page fetches only the character sets it uses.
  */
 
 body {
+  /* SUITE used to sit between Pretendard and the system stack. Pretendard
+     covers Latin and Korean, so nothing ever reached it except the emoji in
+     section names — which it has no glyphs for either, and which the platform
+     emoji font renders. It was 274 kB nobody saw. */
   font-family:
     'Pretendard',
-    'SUITE',
     -apple-system,
     BlinkMacSystemFont,
     'Segoe UI',

package/template/app/layout.tsx

@@ -74,6 +74,23 @@ export const metadata: Metadata = {
     : undefined,
 };
 
+/**
+ * Character ranges each font file covers.
+ *
+ * Pretendard carries the full Korean syllabary, which is most of its weight:
+ * one weight is 750 kB whole, 27 kB once the Hangul is taken out. Splitting it
+ * and declaring what each half covers lets the browser fetch only the halves a
+ * page actually uses — an English page never asks for the Korean file, and a
+ * Korean one pays for it once and keeps it, since `public/` is served
+ * immutable.
+ */
+const RANGES = {
+  latin:
+    'U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+2000-206F,' +
+    'U+2074,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD',
+  korean: 'U+1100-11FF,U+3000-303F,U+3130-318F,U+A960-A97F,U+AC00-D7A3,U+D7B0-D7FF,U+FF00-FFEF',
+} as const;
+
 /**
  * Web fonts, declared here rather than in `globals.css`.
  *
@@ -83,31 +100,34 @@ export const metadata: Metadata = {
  * the declarations from here puts them through `asset()` like every other file
  * in `public/`.
  *
- * `preload` marks the weights the first paint needs; the rest load on demand.
+ * Only the Latin halves are preloaded. Preloading the Korean ones would undo
+ * the split by fetching them before anything has asked for a Korean glyph.
  */
-const FONT_FACES = [
-  { family: 'SUITE', weight: 400, file: '/fonts/SUITE/SUITE-Regular.woff2' },
-  { family: 'SUITE', weight: 600, file: '/fonts/SUITE/SUITE-SemiBold.woff2' },
-  { family: 'SUITE', weight: 700, file: '/fonts/SUITE/SUITE-Bold.woff2' },
-  {
-    family: 'Pretendard',
-    weight: 400,
-    file: '/fonts/Pretandard/Pretendard-Regular.woff2',
-    preload: true,
-  },
-  {
-    family: 'Pretendard',
-    weight: 600,
-    file: '/fonts/Pretandard/Pretendard-SemiBold.woff2',
-    preload: true,
-  },
-  { family: 'Pretendard', weight: 700, file: '/fonts/Pretandard/Pretendard-Bold.woff2' },
+interface FontFace {
+  weight: number;
+  subset: keyof typeof RANGES;
+  preload?: boolean;
+}
+
+const FONT_FACES: FontFace[] = [
+  { weight: 400, subset: 'latin', preload: true },
+  { weight: 400, subset: 'korean' },
+  { weight: 600, subset: 'latin', preload: true },
+  { weight: 600, subset: 'korean' },
+  { weight: 700, subset: 'latin' },
+  { weight: 700, subset: 'korean' },
 ];
 
+/** Where a weight-and-subset pair is served from. */
+function fontFile({ weight, subset }: FontFace): string {
+  return `/fonts/Pretendard/pretendard-${weight}-${subset}.woff2`;
+}
+
 const fontFaceCss = FONT_FACES.map(
-  ({ family, weight, file }) =>
-    `@font-face{font-family:'${family}';font-weight:${weight};` +
-    `src:url('${asset(file)}') format('woff2');font-display:swap}`,
+  (font) =>
+    `@font-face{font-family:'Pretendard';font-weight:${font.weight};` +
+    `src:url('${asset(fontFile(font))}') format('woff2');font-display:swap;` +
+    `unicode-range:${RANGES[font.subset]}}`,
 ).join('');
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {
@@ -119,9 +139,9 @@ export default function RootLayout({ children }: { children: React.ReactNode })
       <head>
         {FONT_FACES.filter((font) => font.preload).map((font) => (
           <link
-            key={font.file}
+            key={fontFile(font)}
             rel="preload"
-            href={asset(font.file)}
+            href={asset(fontFile(font))}
             as="font"
             type="font/woff2"
             crossOrigin="anonymous"
@@ -155,7 +175,9 @@ export default function RootLayout({ children }: { children: React.ReactNode })
         </a>
         <UrlMapProvider value={site.urlMap}>
           <TabInitializer navigation={site.navigation} />
-          <PageLayout navigation={site.navigation}>{children}</PageLayout>
+          <PageLayout navigation={site.navigation} repoUrl={site.global.repoUrl}>
+            {children}
+          </PageLayout>
           <SearchDialog />
         </UrlMapProvider>
       </body>

package/template/app/robots.ts

@@ -3,8 +3,17 @@ import { payload } from '@/payload/config';
 import { fileUrl } from '@/lib/basePath';
 
 /**
- * Generate robots.txt file
- * Controls how search engines crawl and index the site
+ * Generates robots.txt.
+ *
+ * Nothing is disallowed. Search engines render a page before judging it, so
+ * blocking `/_next/` — where the stylesheet and scripts live — leaves the
+ * crawler looking at an unstyled document and reporting the assets as blocked
+ * resources. There is no `/api/` either: the site is a static export.
+ *
+ * Pages that should stay out of the index carry `noindex` in their own
+ * metadata, which is the mechanism that actually keeps them out. A path
+ * disallowed here would still be indexable if something linked to it, since a
+ * crawler that is told not to fetch a page cannot read the `noindex` on it.
  *
  * @returns Robots configuration
  */
@@ -13,7 +22,6 @@ export default function robots(): MetadataRoute.Robots {
     rules: {
       userAgent: '*',
       allow: '/',
-      disallow: ['/api/', '/_next/'],
     },
     sitemap: fileUrl('/sitemap.xml', payload.global.baseUrl),
   };

package/template/components/graph/GraphView.tsx

@@ -24,6 +24,10 @@ export interface GraphViewNode {
 interface GraphViewProps {
   nodes: GraphViewNode[];
   edges: LayoutEdge[];
+  /** Page to mark as the one being read, when the graph is centred on one */
+  activePath?: string;
+  /** Height utility class; the default suits a full page of its own */
+  heightClass?: string;
 }
 
 /** Nominal layout area; the SVG viewBox scales the result to fit. */
@@ -33,7 +37,7 @@ const AREA = { width: 900, height: 640 };
 const MIN_RADIUS = 5;
 const MAX_RADIUS = 14;
 
-export function GraphView({ nodes, edges }: GraphViewProps) {
+export function GraphView({ nodes, edges, activePath, heightClass = 'h-[70vh]' }: GraphViewProps) {
   const router = useRouter();
   const [hovered, setHovered] = useState<string | null>(null);
 
@@ -75,7 +79,7 @@ export function GraphView({ nodes, edges }: GraphViewProps) {
     <div className="overflow-hidden rounded-lg border border-gray-200 bg-gray-50 dark:border-gray-800 dark:bg-gray-900">
       <svg
         viewBox={`${box.x} ${box.y} ${box.width} ${box.height}`}
-        className="h-[70vh] w-full"
+        className={`${heightClass} w-full`}
         role="img"
         aria-label={`Link graph of ${nodes.length} pages and ${edges.length} links`}
       >
@@ -110,6 +114,7 @@ export function GraphView({ nodes, edges }: GraphViewProps) {
             const radius =
               MIN_RADIUS + (MAX_RADIUS - MIN_RADIUS) * Math.sqrt(node.degree / maxDegree);
             const active = !connected || connected.has(node.path);
+            const isCurrent = node.path === activePath;
 
             return (
               <g
@@ -131,18 +136,26 @@ export function GraphView({ nodes, edges }: GraphViewProps) {
                 aria-label={node.title}
               >
                 <circle
-                  r={radius}
+                  r={isCurrent ? radius + 2 : radius}
                   className={
-                    hovered === node.path
-                      ? 'fill-blue-500 stroke-white dark:stroke-gray-900'
-                      : 'fill-blue-400/80 stroke-white dark:fill-blue-500/70 dark:stroke-gray-900'
+                    isCurrent
+                      ? // The page being read is filled solid rather than tinted,
+                        // so it is findable in its own neighbourhood at a glance.
+                        'fill-blue-600 stroke-white dark:fill-blue-400 dark:stroke-gray-900'
+                      : hovered === node.path
+                        ? 'fill-blue-500 stroke-white dark:stroke-gray-900'
+                        : 'fill-blue-400/80 stroke-white dark:fill-blue-500/70 dark:stroke-gray-900'
                   }
                   strokeWidth={1.5}
                 />
                 <text
                   y={radius + 12}
                   textAnchor="middle"
-                  className="pointer-events-none fill-gray-700 text-[11px] dark:fill-gray-300"
+                  className={`pointer-events-none text-[11px] ${
+                    isCurrent
+                      ? 'fill-gray-900 font-semibold dark:fill-gray-100'
+                      : 'fill-gray-700 dark:fill-gray-300'
+                  }`}
                 >
                   {node.title}
                 </text>

package/template/components/layout/LocalGraph.tsx

@@ -0,0 +1,52 @@
+import { Share2 } from 'lucide-react';
+import { GraphView } from '@/components/graph/GraphView';
+import type { LocalGraph as LocalGraphData } from '@/lib/graph/build';
+
+/**
+ * Shows the pages immediately around the one being read.
+ *
+ * The whole-site graph on its own page answers what the wiki looks like. This
+ * answers what is next to *here*, which is the question a reader has while
+ * reading, and which the full graph stops answering once there are more than a
+ * few dozen pages to draw.
+ *
+ * It sits below the backlinks list and covers the same ground from the other
+ * side: backlinks name the pages that point here, the graph shows those and the
+ * ones this page points at, and how they relate to each other.
+ *
+ * Computed at build time, so this is a plain server component; only the SVG
+ * beneath it is interactive.
+ *
+ * @param props - Component props
+ * @param props.graph - Neighbourhood from `getLocalGraph()`
+ * @param props.path - Content path of the page at the centre
+ */
+export function LocalGraph({ graph, path }: { graph: LocalGraphData; path: string }) {
+  // A page with nothing linking either way has no neighbourhood to draw, and an
+  // empty box would only be a question the reader cannot answer.
+  if (graph.nodes.length < 2) return null;
+
+  const neighbours = graph.nodes.length - 1;
+
+  return (
+    <section
+      aria-labelledby="local-graph-heading"
+      className="mt-10 border-t border-gray-200 pt-6 dark:border-gray-800"
+    >
+      <h2
+        id="local-graph-heading"
+        className="mb-3 flex items-center gap-2 text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-400"
+      >
+        <Share2 className="h-3.5 w-3.5" />
+        Connected to {neighbours} {neighbours === 1 ? 'page' : 'pages'}
+      </h2>
+
+      <GraphView
+        nodes={graph.nodes}
+        edges={graph.edges}
+        activePath={path}
+        heightClass="h-64 sm:h-72"
+      />
+    </section>
+  );
+}

package/template/components/layout/MobileMenu.tsx

@@ -7,6 +7,7 @@ import { NavigationItem } from '@/lib/payload/types';
 import { useTabStore } from '@/lib/store/tabStore';
 import { useUrlMap } from '@/components/providers/UrlMapProvider';
 import { filterHiddenItems } from '@/lib/navigation/builder';
+import { Github } from 'lucide-react';
 
 /**
  * Props for the MobileMenu component
@@ -18,6 +19,8 @@ interface MobileMenuProps {
   isOpen: boolean;
   /** Callback function to close the menu */
   onClose: () => void;
+  /** Source repository, linked from the drawer header when configured */
+  repoUrl?: string;
 }
 
 /**
@@ -221,7 +224,7 @@ function MobileNavigationItem({
  * @param props.onClose - Callback function to close the menu
  *
  */
-export function MobileMenu({ navigation, isOpen, onClose }: MobileMenuProps) {
+export function MobileMenu({ navigation, isOpen, onClose, repoUrl }: MobileMenuProps) {
   const pathname = usePathname();
   const { toPath } = useUrlMap();
 
@@ -267,6 +270,18 @@ export function MobileMenu({ navigation, isOpen, onClose }: MobileMenuProps) {
           <nav>
             <div className="flex items-center justify-between mb-1">
               <div className="flex-1" />
+              {repoUrl && (
+                <a
+                  href={repoUrl}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  aria-label="Source repository"
+                  title="Source repository"
+                  className="rounded-md p-2 text-gray-500 transition-colors hover:text-gray-700 active:bg-gray-100 dark:text-gray-400 dark:hover:text-gray-200 dark:active:bg-gray-800"
+                >
+                  <Github className="h-5 w-5" />
+                </a>
+              )}
               <button
                 onClick={onClose}
                 className="p-2 text-gray-500 hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-200 active:bg-gray-100 dark:active:bg-gray-800 rounded-md transition-colors touch-manipulation"

package/template/components/layout/PageLayout.tsx

@@ -15,6 +15,8 @@ import { SearchTrigger } from '@/components/search/SearchTrigger';
 interface PageLayoutProps {
   /** Array of top-level navigation items */
   navigation: NavigationItem[];
+  /** Source repository, linked from the sidebar when configured */
+  repoUrl?: string;
   /** Page content to render in the main area */
   children: React.ReactNode;
 }
@@ -25,10 +27,11 @@ interface PageLayoutProps {
  *
  * @param props - Component props
  * @param props.navigation - Array of navigation items to display in sidebar/menu
+ * @param props.repoUrl - Source repository, linked from the sidebar when set
  * @param props.children - Page content to render in the main content area
  *
  */
-export function PageLayout({ navigation, children }: PageLayoutProps) {
+export function PageLayout({ navigation, repoUrl, children }: PageLayoutProps) {
   const [isMobileMenuOpen, setIsMobileMenuOpen] = useState(false);
 
   const toggleMobileMenu = () => {
@@ -63,10 +66,15 @@ export function PageLayout({ navigation, children }: PageLayoutProps) {
         </div>
       </header>
 
-      <MobileMenu navigation={navigation} isOpen={isMobileMenuOpen} onClose={closeMobileMenu} />
+      <MobileMenu
+        navigation={navigation}
+        isOpen={isMobileMenuOpen}
+        onClose={closeMobileMenu}
+        repoUrl={repoUrl}
+      />
 
       <div className="flex">
-        <Sidebar navigation={navigation} />
+        <Sidebar navigation={navigation} repoUrl={repoUrl} />
 
         <main id="main-content" tabIndex={-1} className="flex-1 min-w-0 flex flex-col">
           <div className="sticky top-0 z-20 bg-white dark:bg-gray-950">

package/template/components/layout/Sidebar.tsx

@@ -3,7 +3,7 @@
 import React, { useState, useRef, useEffect } from 'react';
 import Link from 'next/link';
 import { useRouter } from 'next/navigation';
-import { ChevronRight, ChevronsLeft, ChevronsRight, Search, Share2 } from 'lucide-react';
+import { ChevronRight, ChevronsLeft, ChevronsRight, Github, Search, Share2 } from 'lucide-react';
 import { NavigationItem } from '@/lib/payload/types';
 import { useTabStore } from '@/lib/store/tabStore';
 import { ThemeToggle } from '@/components/ThemeToggle';
@@ -18,6 +18,32 @@ import { filterHiddenItems } from '@/lib/navigation/builder';
 interface SidebarProps {
   /** Array of top-level navigation items */
   navigation: NavigationItem[];
+  /** Source repository, linked from the header when configured */
+  repoUrl?: string;
+}
+
+/**
+ * Links out to the site's source repository.
+ *
+ * Rendered only when the payload names one, so a wiki with no public source
+ * does not show a dead control. A published site otherwise gives a reader no
+ * way to reach the project it came from.
+ */
+function RepoLink({ href, collapsed }: { href: string; collapsed: boolean }) {
+  return (
+    <a
+      href={href}
+      target="_blank"
+      rel="noopener noreferrer"
+      aria-label="Source repository"
+      title="Source repository"
+      className={`rounded-md p-2 text-gray-600 transition-colors hover:bg-gray-200 dark:text-gray-400 dark:hover:bg-gray-800 ${
+        collapsed ? '' : 'flex-shrink-0'
+      }`}
+    >
+      <Github className="h-4 w-4" />
+    </a>
+  );
 }
 
 /**
@@ -235,7 +261,7 @@ function NavigationItemComponent({
  * @param props.navigation - Array of top-level navigation items to display
  *
  */
-export function Sidebar({ navigation }: SidebarProps) {
+export function Sidebar({ navigation, repoUrl }: SidebarProps) {
   const { sidebarWidth, sidebarCollapsed, setSidebarWidth, setSidebarCollapsed } = useTabStore();
 
   const visibleNavigation = filterHiddenItems(navigation);
@@ -312,6 +338,7 @@ export function Sidebar({ navigation }: SidebarProps) {
           <>
             <SearchTrigger className="min-w-0 flex-1" />
             <ThemeToggle className="w-4 h-4" />
+            {repoUrl && <RepoLink href={repoUrl} collapsed={false} />}
             <button
               onClick={handleToggle}
               className="p-2 text-gray-600 dark:text-gray-400 hover:bg-gray-200 dark:hover:bg-gray-800 rounded-md transition-colors flex-shrink-0"
@@ -331,6 +358,7 @@ export function Sidebar({ navigation }: SidebarProps) {
             >
               <Search className="h-4 w-4" />
             </button>
+            {repoUrl && <RepoLink href={repoUrl} collapsed />}
             <button
               onClick={handleToggle}
               className="rounded-md p-2 text-gray-600 transition-colors hover:bg-gray-200 dark:text-gray-400 dark:hover:bg-gray-800"

package/template/components/markdown/LinkPreview.tsx

@@ -0,0 +1,164 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+
+/**
+ * Shows where a wiki link goes before a reader commits to following it.
+ *
+ * The title and summary are already on the anchor as `data-preview-*`,
+ * written there during the build, so the card costs no request and appears
+ * immediately. A single delegated listener covers every link on the page,
+ * including any that arrive with a transcluded block.
+ *
+ * Rendered into `document.body` rather than in place. The card is positioned
+ * against the viewport, and `position: fixed` resolves against the nearest
+ * transformed ancestor instead — which the page-transition wrapper is, so a
+ * card rendered here landed roughly a screenful off the top of the window.
+ *
+ * @example
+ * ```tsx
+ * <article dangerouslySetInnerHTML={{ __html: html }} />
+ * <LinkPreview />
+ * ```
+ */
+
+/** Milliseconds a pointer must rest on a link before the card appears. */
+const OPEN_DELAY_MS = 350;
+
+/** Milliseconds before a card closes, so a pointer may cross a gap. */
+const CLOSE_DELAY_MS = 120;
+
+/** Distance from the link to the card. */
+const OFFSET_PX = 8;
+
+/** Card width, needed here to keep it on screen. */
+const WIDTH_PX = 320;
+
+interface PreviewState {
+  title: string;
+  excerpt: string;
+  top: number;
+  left: number;
+  /** Whether the card sits below its link rather than above */
+  below: boolean;
+}
+
+export function LinkPreview() {
+  const [preview, setPreview] = useState<PreviewState | null>(null);
+  const openTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const closeTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    function clearTimers() {
+      if (openTimer.current) clearTimeout(openTimer.current);
+      if (closeTimer.current) clearTimeout(closeTimer.current);
+    }
+
+    function place(anchor: HTMLElement): PreviewState | null {
+      const title = anchor.getAttribute('data-preview-title');
+      if (!title) return null;
+
+      const rect = anchor.getBoundingClientRect();
+
+      // Above the link by default, below it when there is no room above —
+      // a card that opens off the top of the viewport shows nothing.
+      const below = rect.top < 160;
+
+      return {
+        title,
+        excerpt: anchor.getAttribute('data-preview') ?? '',
+        top: below ? rect.bottom + OFFSET_PX : rect.top - OFFSET_PX,
+        left: Math.max(8, Math.min(rect.left, document.documentElement.clientWidth - WIDTH_PX - 8)),
+        below,
+      };
+    }
+
+    function open(anchor: HTMLElement, delay: number) {
+      clearTimers();
+      openTimer.current = setTimeout(() => {
+        const next = place(anchor);
+        if (next) setPreview(next);
+      }, delay);
+    }
+
+    function close(delay = CLOSE_DELAY_MS) {
+      clearTimers();
+      closeTimer.current = setTimeout(() => setPreview(null), delay);
+    }
+
+    function anchorFrom(target: EventTarget | null): HTMLElement | null {
+      return (target as HTMLElement | null)?.closest?.<HTMLElement>('a.ezw-wikilink') ?? null;
+    }
+
+    function handleOver(event: MouseEvent) {
+      const anchor = anchorFrom(event.target);
+      if (anchor) open(anchor, OPEN_DELAY_MS);
+    }
+
+    function handleOut(event: MouseEvent) {
+      if (anchorFrom(event.target)) close();
+    }
+
+    // Keyboard users reach the link by tabbing, and get the same card without
+    // the delay a pointer needs to signal intent.
+    function handleFocus(event: FocusEvent) {
+      const anchor = anchorFrom(event.target);
+      if (anchor) open(anchor, 0);
+    }
+
+    function handleBlur(event: FocusEvent) {
+      if (anchorFrom(event.target)) close(0);
+    }
+
+    // Dismissible without moving the pointer, which WCAG asks of anything that
+    // appears on hover.
+    function handleKey(event: KeyboardEvent) {
+      if (event.key === 'Escape') close(0);
+    }
+
+    document.addEventListener('mouseover', handleOver);
+    document.addEventListener('mouseout', handleOut);
+    document.addEventListener('focusin', handleFocus);
+    document.addEventListener('focusout', handleBlur);
+    // Any movement of the page leaves the card pointing at nothing. Named so
+    // that the cleanup below can actually remove it.
+    function handleScroll() {
+      close(0);
+    }
+
+    document.addEventListener('keydown', handleKey);
+    window.addEventListener('scroll', handleScroll, { passive: true });
+
+    return () => {
+      clearTimers();
+      document.removeEventListener('mouseover', handleOver);
+      document.removeEventListener('mouseout', handleOut);
+      document.removeEventListener('focusin', handleFocus);
+      document.removeEventListener('focusout', handleBlur);
+      document.removeEventListener('keydown', handleKey);
+      window.removeEventListener('scroll', handleScroll);
+    };
+  }, []);
+
+  if (!preview || typeof document === 'undefined') return null;
+
+  return createPortal(
+    <div
+      // Presentational: the link it describes is already in the accessible
+      // tree, and announcing the summary twice would be noise.
+      aria-hidden="true"
+      className="ezw-link-preview"
+      style={{
+        top: preview.top,
+        left: preview.left,
+        width: WIDTH_PX,
+        transform: preview.below ? undefined : 'translateY(-100%)',
+      }}
+    >
+      <p className="ezw-link-preview__title">{preview.title}</p>
+      {preview.excerpt && <p className="ezw-link-preview__excerpt">{preview.excerpt}</p>}
+    </div>,
+    document.body,
+  );
+}

package/template/components/markdown/MarkdownContent.tsx

@@ -1,4 +1,5 @@
 import { CodeCopy } from './CodeCopy';
+import { LinkPreview } from './LinkPreview';
 
 /**
  * Props for the MarkdownContent component
@@ -13,7 +14,7 @@ interface MarkdownContentProps {
  *
  * The markup arrives already parsed, highlighted, and link-resolved from
  * `renderDoc()`, so this is a server component that emits static HTML. The only
- * client-side code is the small copy-button listener.
+ * client-side code is the copy-button and link-preview listeners.
  *
  * Passing build-time output to `dangerouslySetInnerHTML` is safe here in the
  * sense that matters: the input is the repository's own content files, not user
@@ -33,6 +34,7 @@ export function MarkdownContent({ html }: MarkdownContentProps) {
     <>
       <div className="ezw-prose" dangerouslySetInnerHTML={{ __html: html }} />
       <CodeCopy />
+      <LinkPreview />
     </>
   );
 }