create-eziwiki 0.1.0 → 0.2.0

package/template/components/search/SearchTrigger.tsx

@@ -22,17 +22,24 @@ export function SearchTrigger({ className = '' }: { className?: string }) {
   }, []);
 
   return (
+    // No aria-label: it read "Search documentation" while the control visibly
+    // says "Search…", so the spoken name did not contain the written one and
+    // voice control had nothing to match. The text names the button instead;
+    // the icon and the shortcut are hidden from the name, the latter because
+    // `aria-keyshortcuts` already announces it.
     <button
       type="button"
       onClick={open}
-      aria-label="Search documentation"
       aria-keyshortcuts="Meta+K Control+K"
-      className={`flex items-center gap-2 rounded-md border border-gray-300 bg-white px-2 py-1 text-sm text-gray-400 transition-colors hover:border-gray-400 dark:border-gray-700 dark:bg-gray-800 dark:hover:border-gray-600 ${className}`}
+      className={`flex items-center gap-2 rounded-md border border-gray-300 bg-white px-2 py-1 text-sm text-gray-500 transition-colors hover:border-gray-400 dark:border-gray-700 dark:bg-gray-800 dark:text-gray-400 dark:hover:border-gray-600 ${className}`}
     >
-      <Search className="h-4 w-4 flex-shrink-0" />
+      <Search className="h-4 w-4 flex-shrink-0" aria-hidden="true" />
       <span className="min-w-0 flex-1 truncate text-left">Search…</span>
       {shortcut && (
-        <kbd className="hidden flex-shrink-0 rounded border border-gray-300 px-1 py-0.5 text-[10px] text-gray-500 sm:block dark:border-gray-600 dark:text-gray-400">
+        <kbd
+          aria-hidden="true"
+          className="hidden flex-shrink-0 rounded border border-gray-300 px-1 py-0.5 text-[10px] text-gray-500 sm:block dark:border-gray-600 dark:text-gray-400"
+        >
           {shortcut}
         </kbd>
       )}

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;
+}

package/template/lib/content/excerpt.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from 'vitest';
+import { buildExcerpt, getExcerpt } from './excerpt';
+
+describe('buildExcerpt', () => {
+  it('prefers the description an author wrote', () => {
+    expect(buildExcerpt('# Title\n\nThe body.', 'A deliberate summary')).toBe(
+      'A deliberate summary',
+    );
+  });
+
+  it('falls back to the opening prose', () => {
+    expect(buildExcerpt('# Title\n\nThe first sentence.')).toBe('The first sentence.');
+  });
+
+  // The card shows the title on its own line, so repeating it as the summary
+  // would waste the space there is.
+  it('skips the title heading', () => {
+    expect(buildExcerpt('# Page Title\n\nBody text.')).not.toContain('Page Title');
+  });
+
+  it('skips code, rules and tables to reach the prose', () => {
+    const markdown = '# T\n\n```bash\nnpm install\n```\n\n---\n\nThe actual sentence.';
+
+    expect(buildExcerpt(markdown)).toBe('The actual sentence.');
+  });
+
+  // A page opening with a figure should preview as the sentence under it, not
+  // as the image's alt text.
+  it('leaves image alt text out', () => {
+    expect(buildExcerpt('# T\n\n![a diagram of the pipeline](/x.png)\n\nReal prose.')).toBe(
+      'Real prose.',
+    );
+  });
+
+  it('flattens inline markup and whitespace', () => {
+    expect(buildExcerpt('# T\n\nSome **bold**\nand `code` here.')).toBe('Some bold and code here.');
+  });
+
+  it('cuts at a word boundary rather than mid-word', () => {
+    const long = `# T\n\n${'alpha '.repeat(80)}`;
+    const excerpt = buildExcerpt(long);
+
+    expect(excerpt.endsWith('…')).toBe(true);
+    expect(excerpt).not.toMatch(/alph…$/);
+    expect(excerpt.length).toBeLessThanOrEqual(181);
+  });
+
+  it('returns nothing for a document with no prose', () => {
+    expect(buildExcerpt('# Only a title\n')).toBe('');
+  });
+});
+
+describe('getExcerpt', () => {
+  // `intro` is the one document both this repository and a freshly scaffolded
+  // project have, so this test travels with the engine rather than having to be
+  // held back from it.
+  it('summarises a document from the registry', () => {
+    expect(getExcerpt('intro').length).toBeGreaterThan(0);
+  });
+
+  it('returns the same summary on a repeat call', () => {
+    expect(getExcerpt('intro')).toBe(getExcerpt('intro'));
+  });
+
+  it('returns an empty summary for an unknown path', () => {
+    expect(getExcerpt('no/such/document')).toBe('');
+  });
+});

package/template/lib/content/excerpt.ts

@@ -0,0 +1,142 @@
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import { visit } from 'unist-util-visit';
+import type { Root, RootContent } from 'mdast';
+import { toString as mdastToString } from 'mdast-util-to-string';
+import { getDoc } from './registry';
+import { CACHE_DERIVED_CONTENT } from '../cache';
+
+/**
+ * Short plain-text summaries of documents.
+ *
+ * Used for the card that appears when a reader hovers a wiki link. Deriving it
+ * from Markdown rather than from the rendered HTML keeps markup, syntax
+ * highlighting, and the `ezw-` wrappers out of what is meant to be one or two
+ * readable sentences.
+ *
+ * Server-only.
+ */
+
+/** How much of a document the card shows before trailing off. */
+const MAX_LENGTH = 180;
+
+/** Parser used only to reach the text; no rendering plugins. */
+const parser = unified().use(remarkParse).use(remarkGfm);
+
+/**
+ * Node types that carry no prose worth previewing.
+ *
+ * A page opening with a diagram or a command should preview as the sentence
+ * underneath it, not as an empty string or a line of shell.
+ */
+const SKIPPED = new Set(['code', 'thematicBreak', 'image', 'html', 'table', 'math']);
+
+/**
+ * Whether a node is the document's own title heading.
+ *
+ * The card shows the title separately, so repeating it as the first line of the
+ * body wastes the little space there is.
+ */
+function isTitleHeading(node: RootContent): boolean {
+  return node.type === 'heading' && node.depth === 1;
+}
+
+/**
+ * Collapses a node's text into a single line.
+ */
+function flatten(node: RootContent): string {
+  // An image alt is not prose; strip it so a paragraph that is only a figure
+  // does not preview as its alt text.
+  const clone: Root = { type: 'root', children: [structuredClone(node)] };
+  visit(clone, 'image', (_image, index, parent) => {
+    if (parent && index !== undefined) parent.children.splice(index, 1);
+    return index;
+  });
+
+  return mdastToString(clone).replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Builds a one-or-two sentence summary of a Markdown document.
+ *
+ * Prefers the frontmatter description, which an author wrote deliberately.
+ * Otherwise takes prose from the top of the document, skipping the title and
+ * anything that is not text, and stops at a word boundary so the card never
+ * cuts mid-word.
+ *
+ * @param markdown - Document body, with frontmatter already stripped
+ * @param description - `description` from the frontmatter, when present
+ * @returns The summary, or an empty string when the document has no prose
+ *
+ * @example
+ * ```typescript
+ * buildExcerpt('# Title\n\nThe first sentence.'); // 'The first sentence.'
+ * buildExcerpt('# Title\n\nIgnored.', 'From the frontmatter'); // 'From the frontmatter'
+ * ```
+ */
+export function buildExcerpt(markdown: string, description?: string): string {
+  if (description?.trim()) return truncate(description.trim());
+
+  const tree = parser.parse(markdown) as Root;
+  const parts: string[] = [];
+
+  for (const node of tree.children) {
+    if (isTitleHeading(node) || SKIPPED.has(node.type)) continue;
+
+    const text = flatten(node);
+    if (!text) continue;
+
+    parts.push(text);
+    if (parts.join(' ').length >= MAX_LENGTH) break;
+  }
+
+  return truncate(parts.join(' '));
+}
+
+const cache = new Map<string, string>();
+
+/**
+ * Returns a document's summary, memoised by path.
+ *
+ * A popular page is linked from dozens of others, and each of those links asks
+ * for the same summary while its page is rendered. Parsing the target once per
+ * build rather than once per link keeps that from showing up in build time.
+ *
+ * @param docPath - Content-relative path without extension
+ * @returns The summary, or an empty string when there is no such document
+ *
+ * @example
+ * ```typescript
+ * getExcerpt('getting-started/quick-start'); // 'Get a wiki running in…'
+ * ```
+ */
+export function getExcerpt(docPath: string): string {
+  // Checked through the map rather than `cached()`, because an empty summary is
+  // a legitimate result and would otherwise be indistinguishable from a miss.
+  if (CACHE_DERIVED_CONTENT) {
+    const hit = cache.get(docPath);
+    if (hit !== undefined) return hit;
+  }
+
+  const doc = getDoc(docPath);
+  const excerpt = doc ? buildExcerpt(doc.content, doc.description) : '';
+
+  cache.set(docPath, excerpt);
+  return excerpt;
+}
+
+/**
+ * Shortens text to the preview length, breaking at a space.
+ *
+ * @param text - Text to shorten
+ * @returns The text, with an ellipsis when it was cut
+ */
+function truncate(text: string): string {
+  if (text.length <= MAX_LENGTH) return text;
+
+  const cut = text.slice(0, MAX_LENGTH);
+  const lastSpace = cut.lastIndexOf(' ');
+
+  return `${(lastSpace > MAX_LENGTH / 2 ? cut.slice(0, lastSpace) : cut).trimEnd()}…`;
+}

package/template/lib/graph/build.ts

@@ -6,6 +6,7 @@ import type { Root, Link, Text } from 'mdast';
 import { getContentRegistry, type ContentDoc } from '../content/registry';
 import { resolveTarget } from '../content/resolver';
 import { findWikiLinks } from '../markdown/wikilink';
+import { resolveAsset } from '../content/assets';
 import { getSite } from '../site';
 import { cached } from '../cache';
 
@@ -117,6 +118,12 @@ function scanDoc(doc: ContentDoc): { targets: Set<string>; broken: BrokenLink[]
       // An anchor-only link stays within the page and is not an edge.
       if (!link.target) continue;
 
+      // `![[diagram.png]]` embeds a file. It is neither an edge between pages
+      // nor a broken reference, so it leaves the graph here. An embed that
+      // names no such file falls through, matching the renderer, which treats
+      // it as a link to a document.
+      if (link.embed && resolveAsset(link.target)) continue;
+
       const resolution = resolveTarget(link.target);
 
       if (resolution.doc) {
@@ -197,6 +204,54 @@ export function getLinkGraph(): LinkGraph {
   return memo;
 }
 
+/** A page and everything one link away from it. */
+export interface LocalGraph {
+  /** The page itself, plus its immediate neighbours */
+  nodes: GraphNode[];
+  /** Links among those nodes, including ones not touching the page */
+  edges: GraphEdge[];
+}
+
+/**
+ * Returns the neighbourhood around a page.
+ *
+ * The whole-site graph answers "how is this wiki shaped"; past a few dozen
+ * pages it stops answering "what is near this one", which is the question a
+ * reader has while reading. This is that view: the page, everything it links
+ * to, everything linking to it, and the links among them — the last so the
+ * neighbours read as a cluster rather than a fan of unconnected dots.
+ *
+ * Direction is deliberately not distinguished. A reader looking for related
+ * pages cares that two are connected, not which one did the linking; the
+ * backlinks list already says that for the pages that point here.
+ *
+ * @param path - Content path of the page at the centre
+ * @returns The neighbourhood, or empty when the page has no links either way
+ *
+ * @example
+ * ```typescript
+ * const { nodes, edges } = getLocalGraph('features/wiki-links');
+ * nodes.length; // the page plus its neighbours
+ * ```
+ */
+export function getLocalGraph(path: string): LocalGraph {
+  const graph = getLinkGraph();
+
+  const neighbours = new Set<string>([
+    ...(graph.outbound.get(path) ?? []),
+    ...(graph.backlinks.get(path) ?? []),
+  ]);
+
+  if (neighbours.size === 0) return { nodes: [], edges: [] };
+
+  const included = new Set<string>([path, ...neighbours]);
+
+  return {
+    nodes: graph.nodes.filter((node) => included.has(node.path)),
+    edges: graph.edges.filter((edge) => included.has(edge.from) && included.has(edge.to)),
+  };
+}
+
 /**
  * Returns the documents that link to a given page.
  *

package/template/lib/markdown/rehype-plugins.ts

@@ -49,6 +49,11 @@ export function rehypeCollectHeadings() {
     visit(tree, 'element', (node: Element) => {
       if (!TOC_LEVELS.has(node.tagName)) return;
 
+      // A transcluded heading belongs to the document it came from. Listing it
+      // would offer a reader sections that are not this page's own, and two
+      // entries with the same name whenever a page includes part of another.
+      if (node.properties?.dataTranscluded) return;
+
       const id = node.properties?.id;
       if (typeof id !== 'string' || !id) return;
 
@@ -221,15 +226,32 @@ export function rehypeBasePath(basePath: string) {
 }
 
 /**
- * Adds lazy loading and consistent styling hooks to content images.
+ * Adds loading hints and consistent styling hooks to content images.
+ *
+ * Every image was deferred, including the first one. On a page that opens with
+ * a figure that image is what the browser measures as the largest contentful
+ * paint, and `loading="lazy"` keeps it out of the preload scan — the request
+ * only starts once layout has reached it, so the headline metric waits on a
+ * round trip that need not have been late. The first image is therefore
+ * fetched eagerly and marked high priority; the rest, which are further down,
+ * keep deferring.
  */
 export function rehypeImages() {
   return (tree: Root) => {
+    let seen = 0;
+
     visit(tree, 'element', (node: Element) => {
       if (node.tagName !== 'img') return;
 
       node.properties ??= {};
-      node.properties.loading ??= 'lazy';
+      const isFirst = seen++ === 0;
+
+      if (isFirst) {
+        node.properties.loading ??= 'eager';
+        node.properties.fetchPriority ??= 'high';
+      } else {
+        node.properties.loading ??= 'lazy';
+      }
       node.properties.decoding ??= 'async';
 
       const className = node.properties.className;