create-eziwiki 0.1.1 → 0.3.0

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;
 
@@ -63,6 +68,51 @@ export function rehypeCollectHeadings() {
   };
 }
 
+/** Heading levels that get a link to themselves. */
+const ANCHORED_LEVELS = new Set(['h2', 'h3', 'h4', 'h5', 'h6']);
+
+/**
+ * Appends a link to each heading pointing at itself.
+ *
+ * A reader who wants to send someone to one section of a long page otherwise
+ * has to read the id out of the address bar, or link the whole page and say
+ * "scroll down". Every documentation site solves this the same way, and the
+ * anchor is a real link — focusable, copyable, and working without script.
+ *
+ * `h1` is skipped: it names the page, which the page URL already addresses.
+ * Transcluded headings are skipped too, since their `id` belongs to the
+ * document they came from and linking here would send a reader to a copy.
+ */
+export function rehypeHeadingAnchors() {
+  return (tree: Root) => {
+    visit(tree, 'element', (node: Element) => {
+      if (!ANCHORED_LEVELS.has(node.tagName)) return;
+      if (node.properties?.dataTranscluded) return;
+
+      const id = node.properties?.id;
+      if (typeof id !== 'string' || !id) return;
+
+      node.properties.className = [
+        ...(Array.isArray(node.properties.className) ? node.properties.className.map(String) : []),
+        'ezw-heading',
+      ];
+
+      node.children.push({
+        type: 'element',
+        tagName: 'a',
+        properties: {
+          href: `#${id}`,
+          className: ['ezw-heading__anchor'],
+          // The heading's own text already names the destination; without this
+          // a screen reader hears every heading followed by a stray "#".
+          'aria-label': `Link to this section: ${toString(node)}`,
+        },
+        children: [{ type: 'text', value: '#' }],
+      });
+    });
+  };
+}
+
 /**
  * Determines whether an href points outside the site.
  */

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

@@ -0,0 +1,173 @@
+import { visit } from 'unist-util-visit';
+import type { Root, Blockquote, PhrasingContent, BlockContent } from 'mdast';
+
+/**
+ * Turns `> [!NOTE]` blockquotes into callouts.
+ *
+ * The syntax is GitHub's and Obsidian's alike, which is the reason for
+ * choosing it: a document written for either renders here, and one written
+ * here still reads as an ordinary blockquote anywhere that does not know the
+ * convention. Nothing is invented.
+ *
+ * Runs on the Markdown AST so the body passes through the rest of the pipeline
+ * unchanged — links, code and wiki links inside a callout behave exactly as
+ * they do outside one.
+ */
+
+/**
+ * Marker opening a callout: the kind, an optional fold hint, and an optional
+ * title on the same line.
+ */
+const MARKER = /^\[!([A-Za-z]+)\]([-+])?\s*(.*)$/;
+
+/**
+ * Callout kinds, and the ones that are the same thing under another name.
+ *
+ * GitHub defines five; Obsidian defines more and its vaults use them, so the
+ * extra names map onto the nearest kind rather than falling back to a plain
+ * quote. A vault should not lose its formatting on the way in.
+ */
+const KINDS: Record<string, string> = {
+  note: 'note',
+  info: 'note',
+  abstract: 'note',
+  summary: 'note',
+  tip: 'tip',
+  hint: 'tip',
+  success: 'tip',
+  check: 'tip',
+  done: 'tip',
+  important: 'important',
+  example: 'important',
+  question: 'important',
+  help: 'important',
+  faq: 'important',
+  warning: 'warning',
+  attention: 'warning',
+  todo: 'warning',
+  caution: 'caution',
+  danger: 'caution',
+  error: 'caution',
+  failure: 'caution',
+  fail: 'caution',
+  bug: 'caution',
+};
+
+/** What a callout marker said. */
+interface Marker {
+  /** Normalised kind, one of the values in {@link KINDS} */
+  kind: string;
+  /** Heading text, defaulting to the kind when the author gave none */
+  title: PhrasingContent[];
+  /** Whether the body folds away, and whether it starts open */
+  fold: 'none' | 'open' | 'closed';
+}
+
+/**
+ * Reads the marker from the first line of a blockquote.
+ *
+ * @param node - The blockquote to inspect
+ * @returns The marker, or null when this is an ordinary quote
+ */
+function readMarker(node: Blockquote): Marker | null {
+  const [first] = node.children;
+  if (!first || first.type !== 'paragraph') return null;
+
+  const [lead] = first.children;
+  if (!lead || lead.type !== 'text') return null;
+
+  // Only the first line carries the marker; the rest of the paragraph is body.
+  const newline = lead.value.indexOf('\n');
+  const head = newline === -1 ? lead.value : lead.value.slice(0, newline);
+
+  const match = MARKER.exec(head.trim());
+  if (!match) return null;
+
+  const kind = KINDS[match[1].toLowerCase()];
+  if (!kind) return null;
+
+  const rest = newline === -1 ? '' : lead.value.slice(newline + 1);
+  const heading = match[3].trim();
+
+  // Everything after the marker line stays in the body, including any inline
+  // nodes that followed the opening text.
+  const body: PhrasingContent[] = [
+    ...(rest ? [{ type: 'text' as const, value: rest }] : []),
+    ...first.children.slice(1),
+  ];
+
+  node.children = [
+    ...(body.length ? [{ type: 'paragraph' as const, children: body }] : []),
+    ...node.children.slice(1),
+  ];
+
+  return {
+    kind,
+    title: [{ type: 'text', value: heading || titleFor(kind) }],
+    fold: match[2] === '-' ? 'closed' : match[2] === '+' ? 'open' : 'none',
+  };
+}
+
+/** Default heading for a kind, when the author supplied none. */
+function titleFor(kind: string): string {
+  return kind.charAt(0).toUpperCase() + kind.slice(1);
+}
+
+/**
+ * Builds the callout node.
+ *
+ * A foldable callout becomes `<details>`, which opens and closes without any
+ * script — the browser already knows how to do this, and a disclosure that
+ * depends on JavaScript is one that fails with it disabled.
+ */
+function toCallout(node: Blockquote, marker: Marker): Blockquote {
+  const foldable = marker.fold !== 'none';
+
+  const heading: BlockContent = {
+    type: 'paragraph',
+    data: {
+      hName: foldable ? 'summary' : 'p',
+      hProperties: { className: ['ezw-callout__title'] },
+    },
+    children: marker.title,
+  };
+
+  return {
+    type: 'blockquote',
+    data: {
+      hName: foldable ? 'details' : 'div',
+      hProperties: {
+        className: ['ezw-callout', `ezw-callout--${marker.kind}`],
+        ...(marker.fold === 'open' ? { open: true } : {}),
+      },
+    },
+    children: [heading, ...node.children],
+  };
+}
+
+/**
+ * Remark plugin factory.
+ *
+ * @example
+ * ```typescript
+ * unified().use(remarkParse).use(remarkCallouts);
+ * // > [!WARNING] Mind the gap
+ * // > Body text.
+ * ```
+ */
+export function remarkCallouts() {
+  return (tree: Root) => {
+    visit(tree, 'blockquote', (node: Blockquote, index, parent) => {
+      if (!parent || index === undefined) return;
+
+      const marker = readMarker(node);
+      if (!marker) return;
+
+      parent.children[index] = toCallout(node, marker);
+
+      // Skip the node just written: its children have already been read, and
+      // revisiting would look at a blockquote that is now a callout.
+      return index + 1;
+    });
+  };
+}

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