create-eziwiki 0.1.1 → 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.1",
+  "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/layout.tsx

@@ -175,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/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 />
     </>
   );
 }

package/template/lib/content/assets.ts

@@ -0,0 +1,158 @@
+import fs from 'fs';
+import path from 'path';
+import { cached } from '../cache';
+
+/**
+ * Index of the static files a page can embed.
+ *
+ * `![[diagram.png]]` names a file the way a vault does — by its name, with no
+ * path — because that is what an author remembers and what Obsidian accepts.
+ * Turning that into a URL means knowing every file under `public/`, so they are
+ * scanned once and indexed by both their full path and their bare filename.
+ *
+ * Server-only: reads the filesystem.
+ */
+
+/** Directory whose contents are served from the site root. */
+export const PUBLIC_DIR = path.join(process.cwd(), 'public');
+
+/**
+ * Directories under `public/` that hold generated or structural files rather
+ * than embeddable assets. Indexing them would let `![[search-index.json]]`
+ * resolve, which is never what an author meant.
+ */
+const SKIP_DIRS = new Set(['fonts']);
+
+/** Extensions an embed may point at. */
+const EMBEDDABLE = new Set([
+  '.png',
+  '.jpg',
+  '.jpeg',
+  '.gif',
+  '.webp',
+  '.avif',
+  '.svg',
+  '.bmp',
+  '.ico',
+]);
+
+/** A file under `public/` that a page may embed. */
+export interface Asset {
+  /** Path relative to `public/`, e.g. 'images/docs/sample.jpg' */
+  path: string;
+  /** Root-relative URL, before the deployment base path is applied */
+  url: string;
+}
+
+/** Assets indexed for lookup. */
+export interface AssetRegistry {
+  /** Every embeddable asset found */
+  assets: Asset[];
+  /** By path relative to `public/`, lowercased */
+  byPath: Map<string, Asset>;
+  /** By bare filename, lowercased; several files may share one */
+  byName: Map<string, Asset[]>;
+}
+
+let memo: AssetRegistry | null = null;
+
+/**
+ * Collects embeddable files beneath a directory.
+ *
+ * @param dir - Directory to scan
+ * @param root - Directory that paths are made relative to
+ * @returns Paths relative to `root`, using forward slashes
+ */
+function walkAssets(dir: string, root: string): string[] {
+  if (!fs.existsSync(dir)) return [];
+
+  const found: string[] = [];
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue;
+
+    const full = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      if (dir === root && SKIP_DIRS.has(entry.name)) continue;
+      found.push(...walkAssets(full, root));
+      continue;
+    }
+
+    if (!EMBEDDABLE.has(path.extname(entry.name).toLowerCase())) continue;
+
+    found.push(path.relative(root, full).split(path.sep).join('/'));
+  }
+
+  return found;
+}
+
+/**
+ * Scans `public/` and indexes what an embed may point at.
+ *
+ * Memoised for the process, like the content registry, and for the same
+ * reason: the files cannot change during a build.
+ *
+ * @returns The populated registry
+ *
+ * @example
+ * ```typescript
+ * const { byName } = getAssetRegistry();
+ * byName.get('sample.jpg')?.[0].url; // '/images/docs/sample.jpg'
+ * ```
+ */
+export function getAssetRegistry(): AssetRegistry {
+  const hit = cached(memo);
+  if (hit) return hit;
+
+  const assets: Asset[] = walkAssets(PUBLIC_DIR, PUBLIC_DIR).map((relative) => ({
+    path: relative,
+    url: `/${relative}`,
+  }));
+
+  const byPath = new Map(assets.map((asset) => [asset.path.toLowerCase(), asset]));
+  const byName = new Map<string, Asset[]>();
+
+  for (const asset of assets) {
+    const name = path.basename(asset.path).toLowerCase();
+    const existing = byName.get(name);
+    if (existing) existing.push(asset);
+    else byName.set(name, [asset]);
+  }
+
+  memo = { assets, byPath, byName };
+  return memo;
+}
+
+/**
+ * Resolves an embed target to a file under `public/`.
+ *
+ * A full path wins over a bare filename, so `![[icons/logo.svg]]` is
+ * unambiguous even when another `logo.svg` exists elsewhere. A bare name that
+ * matches more than one file resolves to nothing rather than guessing: picking
+ * whichever was scanned first would silently embed the wrong image, and the
+ * author would have no indication of it.
+ *
+ * @param target - Text between the brackets, e.g. 'sample.jpg'
+ * @returns The asset, or null when nothing or too much matches
+ *
+ * @example
+ * ```typescript
+ * resolveAsset('sample.jpg')?.url; // '/images/docs/sample.jpg'
+ * resolveAsset('/images/docs/sample.jpg')?.url; // '/images/docs/sample.jpg'
+ * ```
+ */
+export function resolveAsset(target: string): Asset | null {
+  const key = target.trim().replace(/^\/+/, '').toLowerCase();
+  if (!key) return null;
+
+  const { byPath, byName } = getAssetRegistry();
+
+  const exact = byPath.get(key);
+  if (exact) return exact;
+
+  const matches = byName.get(key);
+  if (matches?.length === 1) return matches[0];
+
+  return null;
+}