create-eziwiki 0.1.0 → 0.2.0

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);

package/template/lib/markdown/render.ts

@@ -1,4 +1,6 @@
 import { unified, type Processor } from 'unified';
+import { VFile } from 'vfile';
+import type { Root, RootContent } from 'mdast';
 import remarkParse from 'remark-parse';
 import remarkGfm from 'remark-gfm';
 import remarkMath from 'remark-math';
@@ -16,13 +18,17 @@ import {
   rehypeInternalLinks,
   type Heading,
 } from './rehype-plugins';
-import { remarkWikiLinks, type WikiLinkTarget } from './remark-wikilink';
+import { remarkWikiLinks, type WikiLinkTarget, type TranscludeTarget } from './remark-wikilink';
 import { getUsedLanguages } from './languages';
 import { cached } from '../cache';
 import { BASE_PATH } from '../basePath';
 import { getUrlMap } from '../navigation/urlMap';
 import { getDoc } from '../content/registry';
 import { resolveTarget } from '../content/resolver';
+import { resolveAsset } from '../content/assets';
+import { getExcerpt } from '../content/excerpt';
+import GithubSlugger from 'github-slugger';
+import { toString as mdastToString } from 'mdast-util-to-string';
 import { docPathToUrl } from '../navigation/url';
 
 /**
@@ -43,14 +49,32 @@ export interface RenderedMarkdown {
   headings: Heading[];
 }
 
-/** Syntax highlighting themes, applied as CSS variables for light and dark. */
-const SHIKI_THEMES = { light: 'github-light', dark: 'github-dark' } as const;
+/**
+ * Syntax highlighting themes, applied as CSS variables for light and dark.
+ *
+ * The high-contrast variants, because the plain ones are tuned for GitHub's
+ * near-white code background: against the slightly darker grey used here their
+ * strings, keywords and comments land between 4.15:1 and 4.37:1, under the
+ * 4.5:1 that body-sized text needs. Lightening the background would fix the
+ * ratios too, but a code block that matches the page around it stops reading
+ * as a code block.
+ */
+const SHIKI_THEMES = {
+  light: 'github-light-high-contrast',
+  dark: 'github-dark-high-contrast',
+} as const;
 
 let processor: Processor | null = null;
 
 /**
  * Resolves a wiki-link target to a destination in this site.
  *
+ * The trailing slash is applied here rather than downstream. Under the `path`
+ * strategy `rehypeInternalLinks` sees a content path it can resolve and adds
+ * one, but under `hash` the URL is already a digest, which does not map back
+ * to a document — so the link was left without it and every wiki link cost a
+ * redirect.
+ *
  * @param target - Raw target text from inside the brackets
  * @returns The destination, or null when the target does not resolve
  */
@@ -59,7 +83,88 @@ function resolveWikiLink(target: string): WikiLinkTarget | null {
   if (!doc) return null;
 
   const url = docPathToUrl(getUrlMap(), doc.path);
-  return url ? { url: `/${url}`, title: doc.title } : null;
+  if (!url) return null;
+
+  return {
+    url: `/${url}/`,
+    title: doc.title,
+    excerpt: getExcerpt(doc.path),
+  };
+}
+
+/**
+ * Resolves an embed target to a file under `public/`.
+ *
+ * @param target - Raw target text from inside the brackets
+ * @returns The file's URL, or null when nothing matches
+ */
+function resolveWikiEmbed(target: string): { url: string } | null {
+  const asset = resolveAsset(target);
+  return asset ? { url: asset.url } : null;
+}
+
+/** Parser for included documents; no rendering plugins, so it stays cheap. */
+const transclusionParser = unified().use(remarkParse).use(remarkGfm).use(remarkMath);
+
+/**
+ * Narrows a document's nodes to the section a heading names.
+ *
+ * The section runs from the matching heading to the next one at the same level
+ * or above, which is what a reader means by "that part of the page". The
+ * heading itself is kept: dropping it would leave the included text with no
+ * indication of what it is.
+ *
+ * @param nodes - The whole document's nodes
+ * @param anchor - Heading slug from after the `#`
+ * @returns The section's nodes, or null when no heading matches
+ */
+function sliceSection(nodes: RootContent[], anchor: string): RootContent[] | null {
+  const slugger = new GithubSlugger();
+  const wanted = anchor.toLowerCase();
+
+  let start = -1;
+  let depth = 0;
+
+  for (let i = 0; i < nodes.length; i++) {
+    const node = nodes[i];
+    if (node.type !== 'heading') continue;
+
+    // Slugs are assigned in document order, and repeats are numbered, so every
+    // heading has to pass through the slugger even before the match is found.
+    const slug = slugger.slug(mdastToString(node));
+
+    if (start === -1) {
+      if (slug !== wanted) continue;
+      start = i;
+      depth = node.depth;
+      continue;
+    }
+
+    if (node.depth <= depth) return nodes.slice(start, i);
+  }
+
+  return start === -1 ? null : nodes.slice(start);
+}
+
+/**
+ * Resolves an embed target to the document content it names.
+ *
+ * @param target - Raw target text from inside the brackets
+ * @param anchor - Heading slug, when the embed named a section
+ * @returns The document's nodes and identity, or null when it does not resolve
+ */
+function resolveWikiTransclusion(target: string, anchor?: string): TranscludeTarget | null {
+  const { doc } = resolveTarget(target);
+  if (!doc) return null;
+
+  const url = docPathToUrl(getUrlMap(), doc.path);
+  if (!url) return null;
+
+  const tree = transclusionParser.parse(doc.content) as Root;
+  const nodes = anchor ? sliceSection(tree.children, anchor) : tree.children;
+  if (!nodes || nodes.length === 0) return null;
+
+  return { path: doc.path, url: `/${url}/`, title: doc.title, nodes };
 }
 
 /**
@@ -81,7 +186,11 @@ function createProcessor(): Processor {
     .use(remarkParse)
     .use(remarkGfm)
     .use(remarkMath)
-    .use(remarkWikiLinks, resolveWikiLink)
+    .use(remarkWikiLinks, {
+      link: resolveWikiLink,
+      embed: resolveWikiEmbed,
+      transclude: resolveWikiTransclusion,
+    })
     .use(remarkRehype, { allowDangerousHtml: true })
     .use(rehypeRaw)
     .use(rehypeSlug)
@@ -132,6 +241,9 @@ function getProcessor(): Processor {
  * Compiles a Markdown string to HTML and extracts its headings.
  *
  * @param markdown - Markdown source, with frontmatter already stripped
+ * @param docPath - Path of the document being rendered, when it has one; a
+ *   transclusion naming it is refused rather than nesting a copy of the page
+ *   inside itself
  * @returns The rendered HTML and the headings found in it
  *
  * @example
@@ -140,12 +252,20 @@ function getProcessor(): Processor {
  * headings; // [{ id: 'setup', text: 'Setup', depth: 2 }]
  * ```
  */
-export async function renderMarkdown(markdown: string): Promise<RenderedMarkdown> {
-  const file = await getProcessor().process(markdown);
+export async function renderMarkdown(
+  markdown: string,
+  docPath?: string,
+): Promise<RenderedMarkdown> {
+  const file = new VFile(markdown);
+  // Seeds the transclusion stack, so a document that includes itself is caught
+  // at the first step rather than after rendering one copy of itself.
+  if (docPath) file.data.docPath = docPath;
+
+  const processed = await getProcessor().process(file);
 
   return {
-    html: String(file),
-    headings: (file.data.headings as Heading[] | undefined) ?? [],
+    html: String(processed),
+    headings: (processed.data.headings as Heading[] | undefined) ?? [],
   };
 }
 
@@ -168,7 +288,7 @@ export async function renderDoc(docPath: string): Promise<RenderedMarkdown | nul
   const doc = getDoc(docPath);
   if (!doc) return null;
 
-  const rendered = await renderMarkdown(doc.content);
+  const rendered = await renderMarkdown(doc.content, doc.path);
   cache.set(docPath, rendered);
 
   return rendered;

package/template/lib/markdown/wikilink.test.ts

@@ -89,3 +89,33 @@ describe('findWikiLinks', () => {
     expect(findWikiLinks('x [[a|B]] y')[0].raw).toBe('[[a|B]]');
   });
 });
+
+describe('embeds', () => {
+  it('marks a leading ! as an embed', () => {
+    const [link] = findWikiLinks('![[diagram.png]]');
+
+    expect(link.embed).toBe(true);
+    expect(link.target).toBe('diagram.png');
+    expect(link.raw).toBe('![[diagram.png]]');
+  });
+
+  it('leaves a plain link unmarked', () => {
+    const [link] = findWikiLinks('[[diagram.png]]');
+
+    expect(link.embed).toBe(false);
+  });
+
+  // The `!` has to be part of the match. Matching only the brackets would
+  // leave it behind as literal text in front of the rendered node.
+  it('consumes the ! rather than leaving it in the text', () => {
+    const [link] = findWikiLinks('before ![[a]] after');
+
+    expect(link.raw.startsWith('!')).toBe(true);
+  });
+
+  it('accepts a label on an embed', () => {
+    const [link] = findWikiLinks('![[diagram.png|Architecture]]');
+
+    expect(link).toMatchObject({ target: 'diagram.png', label: 'Architecture', embed: true });
+  });
+});

package/template/lib/markdown/wikilink.ts

@@ -8,10 +8,13 @@
 /**
  * Matches a wiki link and captures its contents.
  *
+ * The leading `!` is part of the match so that `![[diagram.png]]` is recognised
+ * as an embed rather than leaving a stray `!` in the text ahead of a link.
+ *
  * Deliberately refuses `]` and newlines inside the brackets: an unterminated
  * `[[` should stay literal text rather than swallowing the rest of a paragraph.
  */
-export const WIKILINK_PATTERN = /\[\[([^\]\n]+)\]\]/g;
+export const WIKILINK_PATTERN = /(!?)\[\[([^\]\n]+)\]\]/g;
 
 /** The parts of a wiki link. */
 export interface WikiLink {
@@ -21,6 +24,8 @@ export interface WikiLink {
   anchor?: string;
   /** Display text, when the author supplied one after '|' */
   label?: string;
+  /** Written as `![[…]]`, asking for the target to be shown rather than linked */
+  embed: boolean;
   /** The full matched source, e.g. '[[guide#setup|Setup]]' */
   raw: string;
 }
@@ -33,21 +38,23 @@ export interface WikiLink {
  * - `[[target|label]]`
  * - `[[target#anchor]]`
  * - `[[target#anchor|label]]`
+ * - any of the above prefixed with `!`, to embed rather than link
  *
  * The label is split off first, so a `|` inside it is preserved and a `#` in
  * the label is not mistaken for an anchor.
  *
  * @param inner - Text between the brackets
  * @param raw - The full matched source, stored on the result
+ * @param embed - Whether the source carried a leading `!`
  * @returns The parsed link, or null when the target is empty
  *
  * @example
  * ```typescript
  * parseWikiLink('guides/setup#step-1|Step one', '[[guides/setup#step-1|Step one]]');
- * // { target: 'guides/setup', anchor: 'step-1', label: 'Step one', raw: '...' }
+ * // { target: 'guides/setup', anchor: 'step-1', label: 'Step one', embed: false, raw: '...' }
  * ```
  */
-export function parseWikiLink(inner: string, raw: string): WikiLink | null {
+export function parseWikiLink(inner: string, raw: string, embed = false): WikiLink | null {
   const pipe = inner.indexOf('|');
   const label = pipe === -1 ? undefined : inner.slice(pipe + 1).trim();
   const locator = (pipe === -1 ? inner : inner.slice(0, pipe)).trim();
@@ -63,6 +70,7 @@ export function parseWikiLink(inner: string, raw: string): WikiLink | null {
     target,
     anchor,
     label: label || undefined,
+    embed,
     raw,
   };
 }
@@ -77,7 +85,7 @@ export function findWikiLinks(text: string): WikiLink[] {
   const links: WikiLink[] = [];
 
   for (const match of text.matchAll(WIKILINK_PATTERN)) {
-    const parsed = parseWikiLink(match[1], match[0]);
+    const parsed = parseWikiLink(match[2], match[0], match[1] === '!');
     if (parsed) links.push(parsed);
   }
 

package/template/lib/payload/schema.ts

@@ -14,6 +14,7 @@ export const payloadSchema = {
         description: { type: 'string', minLength: 1 },
         favicon: { type: 'string' },
         baseUrl: { type: 'string', format: 'uri' },
+        repoUrl: { type: 'string', format: 'uri' },
         urlStrategy: { type: 'string', enum: ['path', 'hash'] },
         autoNavigation: { type: 'boolean' },
         seo: {

package/template/lib/payload/types.ts

@@ -30,6 +30,13 @@ export interface GlobalConfig {
   favicon?: string;
   /** Base URL for the site */
   baseUrl?: string;
+  /**
+   * Source repository for this site.
+   *
+   * Shown as a link in the sidebar when set, and omitted entirely when not, so
+   * a private or unpublished wiki does not advertise one.
+   */
+  repoUrl?: string;
   /**
    * How content paths are expressed in URLs.
    *