create-eziwiki 0.1.1 → 0.2.0

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;
 

package/template/lib/markdown/remark-wikilink.ts

@@ -1,5 +1,13 @@
 import { visit } from 'unist-util-visit';
-import type { Root, Text, PhrasingContent, Parent } from 'mdast';
+import type {
+  Root,
+  Text,
+  PhrasingContent,
+  Parent,
+  Paragraph,
+  RootContent,
+  BlockContent,
+} from 'mdast';
 import { WIKILINK_PATTERN, parseWikiLink, type WikiLink } from './wikilink';
 
 /**
@@ -18,6 +26,8 @@ export interface WikiLinkTarget {
   url: string;
   /** Default display text when the author gave no label */
   title: string;
+  /** One-line summary, carried on the link so a hover card needs no request */
+  excerpt?: string;
 }
 
 /**
@@ -25,6 +35,48 @@ export interface WikiLinkTarget {
  */
 export type WikiLinkResolver = (target: string) => WikiLinkTarget | null;
 
+/**
+ * Resolves an embed target to a static file, or null when there is none.
+ */
+export type EmbedResolver = (target: string) => { url: string } | null;
+
+/** A document whose content is to be shown inside another. */
+export interface TranscludeTarget {
+  /** Content path, used to detect a page including itself */
+  path: string;
+  /** Href of the source document */
+  url: string;
+  /** Title of the source document */
+  title: string;
+  /** The Markdown nodes to splice in */
+  nodes: RootContent[];
+}
+
+/**
+ * Resolves an embed target to a document's content, or null when the target is
+ * not a document or the named section does not exist.
+ */
+export type TranscludeResolver = (target: string, anchor?: string) => TranscludeTarget | null;
+
+/** How a wiki link should be turned into a node. */
+export interface WikiLinkResolvers {
+  /** Resolves a document target */
+  link: WikiLinkResolver;
+  /** Resolves an embeddable file; absent when embeds are not supported */
+  embed?: EmbedResolver;
+  /** Resolves a document to include inline; absent disables transclusion */
+  transclude?: TranscludeResolver;
+}
+
+/**
+ * How deeply a transclusion may nest.
+ *
+ * A page including a page that includes a page is already hard to read; past
+ * that it is more likely a mistake than an intent, and each level multiplies
+ * the work the build does.
+ */
+const MAX_TRANSCLUSION_DEPTH = 3;
+
 /**
  * Builds the replacement node for one wiki link.
  *
@@ -32,7 +84,24 @@ export type WikiLinkResolver = (target: string) => WikiLinkTarget | null;
  * that goes nowhere is worse than visibly broken text, because it looks
  * clickable and silently is not.
  */
-function toNode(link: WikiLink, resolve: WikiLinkResolver): PhrasingContent {
+function toNode(link: WikiLink, resolvers: WikiLinkResolvers): PhrasingContent {
+  const resolve = resolvers.link;
+
+  // `![[file.png]]` shows the file rather than linking to it. Only static
+  // assets are embedded for now; `![[some-note]]` falls through to a link, so
+  // an author who writes it gets a working reference instead of nothing.
+  if (link.embed && resolvers.embed) {
+    const asset = resolvers.embed(link.target);
+
+    if (asset) {
+      return {
+        type: 'image',
+        url: asset.url,
+        alt: link.label ?? link.target,
+      };
+    }
+  }
+
   // An anchor-only link points within the current page, so there is nothing to
   // resolve.
   if (!link.target && link.anchor) {
@@ -65,7 +134,14 @@ function toNode(link: WikiLink, resolve: WikiLinkResolver): PhrasingContent {
     type: 'link',
     url: link.anchor ? `${resolved.url}#${link.anchor}` : resolved.url,
     data: {
-      hProperties: { className: ['ezw-wikilink'] },
+      hProperties: {
+        className: ['ezw-wikilink'],
+        // The card's contents travel with the link rather than being fetched.
+        // The build already knows them, and a reader who hovers should not wait
+        // on a request to find out where a link goes.
+        'data-preview-title': resolved.title,
+        ...(resolved.excerpt ? { 'data-preview': resolved.excerpt } : {}),
+      },
     },
     children: [{ type: 'text', value: link.label ?? resolved.title }],
   };
@@ -75,10 +151,10 @@ function toNode(link: WikiLink, resolve: WikiLinkResolver): PhrasingContent {
  * Splits a text node into text and link nodes.
  *
  * @param node - The text node to split
- * @param resolve - Target resolver
+ * @param resolvers - Target resolvers for links and embeds
  * @returns Replacement nodes, or null when the text contains no wiki links
  */
-function splitText(node: Text, resolve: WikiLinkResolver): PhrasingContent[] | null {
+function splitText(node: Text, resolvers: WikiLinkResolvers): PhrasingContent[] | null {
   const { value } = node;
   if (!value.includes('[[')) return null;
 
@@ -89,7 +165,7 @@ function splitText(node: Text, resolve: WikiLinkResolver): PhrasingContent[] | n
   // matchAll on a global pattern is safe here because the regex literal is
   // re-evaluated per call; lastIndex never leaks between documents.
   for (const match of value.matchAll(WIKILINK_PATTERN)) {
-    const parsed = parseWikiLink(match[1], match[0]);
+    const parsed = parseWikiLink(match[2], match[0], match[1] === '!');
     if (!parsed) continue;
 
     const start = match.index ?? 0;
@@ -98,7 +174,7 @@ function splitText(node: Text, resolve: WikiLinkResolver): PhrasingContent[] | n
       replacement.push({ type: 'text', value: value.slice(cursor, start) });
     }
 
-    replacement.push(toNode(parsed, resolve));
+    replacement.push(toNode(parsed, resolvers));
     cursor = start + match[0].length;
     matched = true;
   }
@@ -112,24 +188,135 @@ function splitText(node: Text, resolve: WikiLinkResolver): PhrasingContent[] | n
   return replacement;
 }
 
+/**
+ * Reads a paragraph that consists of nothing but one embed.
+ *
+ * Transclusion replaces a paragraph with whole blocks — headings, lists, code —
+ * which cannot sit inside one. So it applies only when the embed is alone in
+ * its paragraph, which is also how an author writes it. An embed with prose
+ * beside it stays inline and becomes a link.
+ *
+ * @param node - Paragraph to inspect
+ * @returns The embed, or null when the paragraph holds anything else
+ */
+function soleEmbed(node: Paragraph): WikiLink | null {
+  if (node.children.length !== 1) return null;
+
+  const [child] = node.children;
+  if (child.type !== 'text') return null;
+
+  const text = child.value.trim();
+  const match = /^(!?)\[\[([^\]\n]+)\]\]$/.exec(text);
+  if (!match || match[1] !== '!') return null;
+
+  return parseWikiLink(match[2], match[0], true);
+}
+
+/**
+ * Wraps included content so a reader can see where it came from.
+ *
+ * `blockquote` carries the block children — it is a known type that accepts
+ * them — while `hName` renders it as a plain division.
+ */
+function wrapTranscluded(target: TranscludeTarget, nodes: RootContent[]): RootContent {
+  return {
+    type: 'blockquote',
+    data: {
+      hName: 'div',
+      hProperties: { className: ['ezw-transclusion'] },
+    },
+    children: [
+      ...(nodes as BlockContent[]),
+      {
+        type: 'paragraph',
+        data: { hProperties: { className: ['ezw-transclusion__source'] } },
+        children: [
+          {
+            type: 'link',
+            url: target.url,
+            children: [{ type: 'text', value: target.title }],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+/**
+ * Marks headings that arrived by transclusion.
+ *
+ * The table of contents describes the page a reader is on. Headings pulled in
+ * from elsewhere would list sections that belong to another document, so they
+ * are flagged here and skipped when the contents are collected.
+ */
+function markTranscludedHeadings(tree: Root): void {
+  visit(tree, 'heading', (heading) => {
+    heading.data ??= {};
+    const properties = (heading.data.hProperties ??= {}) as Record<string, unknown>;
+    properties['data-transcluded'] = 'true';
+  });
+}
+
+/**
+ * Replaces sole-embed paragraphs with the content they name.
+ *
+ * @param tree - Tree to transform in place
+ * @param resolvers - Target resolvers
+ * @param stack - Paths already being included, innermost last
+ */
+function transclude(tree: Root, resolvers: WikiLinkResolvers, stack: string[]): void {
+  const resolve = resolvers.transclude;
+  if (!resolve) return;
+
+  visit(tree, 'paragraph', (node: Paragraph, index, parent) => {
+    if (!parent || index === undefined) return;
+
+    const embed = soleEmbed(node);
+    if (!embed || !embed.target) return;
+
+    const target = resolve(embed.target, embed.anchor);
+    if (!target) return;
+
+    // A page including itself, directly or through a chain, would never finish.
+    // Leaving the link is the honest outcome: the reference is real, it just
+    // cannot be shown here.
+    if (stack.includes(target.path) || stack.length >= MAX_TRANSCLUSION_DEPTH) return;
+
+    const inner: Root = { type: 'root', children: target.nodes };
+    transclude(inner, resolvers, [...stack, target.path]);
+    markTranscludedHeadings(inner);
+
+    parent.children.splice(index, 1, wrapTranscluded(target, inner.children));
+
+    return index + 1;
+  });
+}
+
 /**
  * Remark plugin factory.
  *
- * @param resolve - Resolves a target to its destination
+ * @param resolvers - Resolves a target to a document, and optionally to a file
  *
  * @example
  * ```typescript
- * unified().use(remarkParse).use(remarkWikiLinks, (target) =>
- *   target === 'intro' ? { url: '/intro', title: 'Introduction' } : null,
- * );
+ * unified().use(remarkParse).use(remarkWikiLinks, {
+ *   link: (target) =>
+ *     target === 'intro' ? { url: '/intro/', title: 'Introduction' } : null,
+ *   embed: (target) => (target === 'logo.svg' ? { url: '/images/logo.svg' } : null),
+ * });
  * ```
  */
-export function remarkWikiLinks(resolve: WikiLinkResolver) {
-  return (tree: Root) => {
+export function remarkWikiLinks(resolvers: WikiLinkResolvers) {
+  return (tree: Root, file: { data: Record<string, unknown> }) => {
+    // Transclusion first: it works on whole paragraphs, and the inline pass
+    // below would otherwise have already turned the embed into a link.
+    const docPath = file?.data?.docPath;
+    transclude(tree, resolvers, typeof docPath === 'string' ? [docPath] : []);
+
     visit(tree, 'text', (node: Text, index, parent) => {
       if (!parent || index === undefined) return;
 
-      const replacement = splitText(node, resolve);
+      const replacement = splitText(node, resolvers);
       if (!replacement) return;
 
       (parent as Parent).children.splice(index, 1, ...replacement);