create-eziwiki 0.1.1 → 0.2.0

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';
 
 /**
@@ -77,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 };
 }
 
 /**
@@ -99,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)
@@ -150,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
@@ -158,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) ?? [],
   };
 }
 
@@ -186,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.
    *

package/template/package-lock.json

@@ -7,14 +7,17 @@
     "": {
       "name": "my-wiki",
       "version": "0.1.0",
+      "license": "MIT",
       "dependencies": {
         "@shikijs/rehype": "^4.3.1",
         "ajv": "^8.12.0",
         "ajv-formats": "^3.0.1",
+        "github-slugger": "^2.0.0",
         "gray-matter": "^4.0.3",
         "hast-util-to-string": "^3.0.1",
         "katex": "^0.16.47",
         "lucide-react": "^0.554.0",
+        "mdast-util-to-string": "^4.0.0",
         "minisearch": "^7.2.0",
         "next": "^14.2.0",
         "react": "^18.3.0",
@@ -1047,15 +1050,6 @@
         "url": "https://opencollective.com/pkgr"
       }
     },
-    "node_modules/@polka/url": {
-      "version": "1.0.0-next.29",
-      "resolved": "https://registry.npmjs.org/@polka/url/-/url-1.0.0-next.29.tgz",
-      "integrity": "sha512-wwQAWhWSuHaag8c4q/KN/vCoeOJYshAIvMQwD4GpSb3OiZklFfvAgmj0VCBBImRpuF/aFgIRzllXlVX93Jevww==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "peer": true
-    },
     "node_modules/@rollup/rollup-android-arm-eabi": {
       "version": "4.53.2",
       "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.53.2.tgz",
@@ -2222,30 +2216,6 @@
         "url": "https://opencollective.com/vitest"
       }
     },
-    "node_modules/@vitest/ui": {
-      "version": "4.0.9",
-      "resolved": "https://registry.npmjs.org/@vitest/ui/-/ui-4.0.9.tgz",
-      "integrity": "sha512-6HV2HHl9aRJ09TlYj/WAQxaa797Ezb5u0LpgabthlASAUAWKgw/W1DSPX7t848mMZmIUvzZgnUHGIylAoYHP0w==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "peer": true,
-      "dependencies": {
-        "@vitest/utils": "4.0.9",
-        "fflate": "^0.8.2",
-        "flatted": "^3.3.3",
-        "pathe": "^2.0.3",
-        "sirv": "^3.0.2",
-        "tinyglobby": "^0.2.15",
-        "tinyrainbow": "^3.0.3"
-      },
-      "funding": {
-        "url": "https://opencollective.com/vitest"
-      },
-      "peerDependencies": {
-        "vitest": "4.0.9"
-      }
-    },
     "node_modules/@vitest/utils": {
       "version": "4.0.9",
       "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.0.9.tgz",
@@ -4288,15 +4258,6 @@
         "reusify": "^1.0.4"
       }
     },
-    "node_modules/fflate": {
-      "version": "0.8.2",
-      "resolved": "https://registry.npmjs.org/fflate/-/fflate-0.8.2.tgz",
-      "integrity": "sha512-cPJU47OaAoCbg0pBvzsgpTPhmhqI5eJjh/JIu8tPj5q+T7iLvW/JAYUqmE7KOB4R1ZyEhzBaIQpQpardBF5z8A==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "peer": true
-    },
     "node_modules/file-entry-cache": {
       "version": "6.0.1",
       "resolved": "https://registry.npmjs.org/file-entry-cache/-/file-entry-cache-6.0.1.tgz",
@@ -6793,18 +6754,6 @@
       "integrity": "sha512-dqT2XBYUOZOiC5t2HRnwADjhNS2cecp9u+TJRiJ1Qp/f5qjkeT5APcGPjHw+bz89Ms8Jp+cG4AlE+QZ/QnDglg==",
       "license": "MIT"
     },
-    "node_modules/mrmime": {
-      "version": "2.0.1",
-      "resolved": "https://registry.npmjs.org/mrmime/-/mrmime-2.0.1.tgz",
-      "integrity": "sha512-Y3wQdFg2Va6etvQ5I82yUhGdsKrcYox6p7FfL1LbK2J4V01F9TGlepTIhnK24t7koZibmg82KGglhA1XK5IsLQ==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "peer": true,
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/ms": {
       "version": "2.1.3",
       "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
@@ -8349,23 +8298,6 @@
         "url": "https://github.com/sponsors/isaacs"
       }
     },
-    "node_modules/sirv": {
-      "version": "3.0.2",
-      "resolved": "https://registry.npmjs.org/sirv/-/sirv-3.0.2.tgz",
-      "integrity": "sha512-2wcC/oGxHis/BoHkkPwldgiPSYcpZK3JU28WoMVv55yHJgcZ8rlXvuG9iZggz+sU1d4bRgIGASwyWqjxu3FM0g==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "peer": true,
-      "dependencies": {
-        "@polka/url": "^1.0.0-next.24",
-        "mrmime": "^2.0.0",
-        "totalist": "^3.0.0"
-      },
-      "engines": {
-        "node": ">=18"
-      }
-    },
     "node_modules/slash": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz",
@@ -8955,18 +8887,6 @@
         "node": ">=8.0"
       }
     },
-    "node_modules/totalist": {
-      "version": "3.0.1",
-      "resolved": "https://registry.npmjs.org/totalist/-/totalist-3.0.1.tgz",
-      "integrity": "sha512-sf4i37nQ2LBx4m3wB74y+ubopq6W/dIzXg0FDGjsYnZHVa1Da8FH853wlL2gtUhg+xJXjfk3kUZS3BRoQeoQBQ==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "peer": true,
-      "engines": {
-        "node": ">=6"
-      }
-    },
     "node_modules/trim-lines": {
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/trim-lines/-/trim-lines-3.0.1.tgz",

package/template/package.json

@@ -24,10 +24,12 @@
     "@shikijs/rehype": "^4.3.1",
     "ajv": "^8.12.0",
     "ajv-formats": "^3.0.1",
+    "github-slugger": "^2.0.0",
     "gray-matter": "^4.0.3",
     "hast-util-to-string": "^3.0.1",
     "katex": "^0.16.47",
     "lucide-react": "^0.554.0",
+    "mdast-util-to-string": "^4.0.0",
     "minisearch": "^7.2.0",
     "next": "^14.2.0",
     "react": "^18.3.0",

package/template/styles/markdown.css

@@ -165,3 +165,77 @@ html.dark .ezw-broken-link {
     white-space: normal;
   }
 }
+
+/* Content pulled in from another page with `![[wiki link]]`.
+   Set apart so a reader can tell borrowed text from the page's own, and
+   attributed so they can follow it back to where it is maintained. */
+.ezw-transclusion {
+  margin: 1.5rem 0;
+  padding: 1rem 1.25rem;
+  border: 1px solid var(--color-border);
+  border-left: 3px solid var(--color-primary, #2563eb);
+  border-radius: 0.375rem;
+  background: var(--color-sidebar-bg);
+}
+
+.ezw-transclusion > :first-child {
+  margin-top: 0;
+}
+
+.ezw-transclusion__source {
+  margin: 0.75rem 0 0;
+  padding-top: 0.5rem;
+  border-top: 1px solid var(--color-border);
+  font-size: 0.8125rem;
+  color: var(--color-text-muted);
+}
+
+.ezw-transclusion__source::before {
+  content: 'From ';
+}
+
+/* Card shown when a reader hovers or focuses a wiki link. Its contents are
+   already on the anchor from the build, so it never waits on a request. */
+.ezw-link-preview {
+  position: fixed;
+  z-index: 60;
+  padding: 0.75rem 0.875rem;
+  border: 1px solid var(--color-border);
+  border-radius: 0.5rem;
+  background: var(--color-background);
+  box-shadow:
+    0 4px 6px -1px rgb(0 0 0 / 0.1),
+    0 2px 4px -2px rgb(0 0 0 / 0.1);
+  /* Purely informational, so it never intercepts the pointer heading for the
+     link underneath it. */
+  pointer-events: none;
+}
+
+.ezw-link-preview__title {
+  margin: 0;
+  font-size: 0.875rem;
+  font-weight: 600;
+  color: var(--color-text);
+}
+
+.ezw-link-preview__excerpt {
+  margin: 0.375rem 0 0;
+  font-size: 0.8125rem;
+  line-height: 1.5;
+  color: var(--color-text-muted);
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .ezw-link-preview {
+    animation: ezw-link-preview-in 120ms ease-out;
+  }
+
+  @keyframes ezw-link-preview-in {
+    from {
+      opacity: 0;
+    }
+    to {
+      opacity: 1;
+    }
+  }
+}