create-eziwiki 0.1.0

package/template/lib/markdown/render.ts

@@ -0,0 +1,175 @@
+import { unified, type Processor } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import remarkMath from 'remark-math';
+import remarkRehype from 'remark-rehype';
+import rehypeRaw from 'rehype-raw';
+import rehypeSlug from 'rehype-slug';
+import rehypeKatex from 'rehype-katex';
+import rehypeShiki from '@shikijs/rehype';
+import rehypeStringify from 'rehype-stringify';
+import {
+  rehypeBasePath,
+  rehypeCodeShell,
+  rehypeCollectHeadings,
+  rehypeImages,
+  rehypeInternalLinks,
+  type Heading,
+} from './rehype-plugins';
+import { remarkWikiLinks, type WikiLinkTarget } 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 { docPathToUrl } from '../navigation/url';
+
+/**
+ * Build-time Markdown rendering.
+ *
+ * Markdown is compiled to HTML once, during the build, instead of being parsed
+ * in the browser on every page view. The browser receives finished markup, so
+ * neither the Markdown parser nor the syntax highlighter ships to the client.
+ *
+ * Server-only: this module reads the content registry and the URL map.
+ */
+
+/** A rendered document: finished markup plus everything derived along the way. */
+export interface RenderedMarkdown {
+  /** Serialised HTML, ready for `dangerouslySetInnerHTML` */
+  html: string;
+  /** Headings collected for the table of contents */
+  headings: Heading[];
+}
+
+/** Syntax highlighting themes, applied as CSS variables for light and dark. */
+const SHIKI_THEMES = { light: 'github-light', dark: 'github-dark' } as const;
+
+let processor: Processor | null = null;
+
+/**
+ * Resolves a wiki-link target to a destination in this site.
+ *
+ * @param target - Raw target text from inside the brackets
+ * @returns The destination, or null when the target does not resolve
+ */
+function resolveWikiLink(target: string): WikiLinkTarget | null {
+  const { doc } = resolveTarget(target);
+  if (!doc) return null;
+
+  const url = docPathToUrl(getUrlMap(), doc.path);
+  return url ? { url: `/${url}`, title: doc.title } : null;
+}
+
+/**
+ * Builds the shared unified processor.
+ *
+ * Plugin order is load-bearing:
+ * - `remarkWikiLinks` must run while the tree is still Markdown, so the links
+ *   it produces are processed like any other link downstream.
+ * - `rehype-raw` must follow `remark-rehype` with `allowDangerousHtml`, so that
+ *   inline HTML in Markdown is parsed rather than escaped.
+ * - `rehype-slug` must precede heading collection, which reads the ids it adds.
+ * - `rehypeCodeShell` must precede the highlighter, since it reads the
+ *   `language-*` class that highlighting replaces.
+ * - `rehypeBasePath` runs last among the link plugins, so it prefixes the
+ *   already-resolved internal hrefs rather than the authored ones.
+ */
+function createProcessor(): Processor {
+  return unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkMath)
+    .use(remarkWikiLinks, resolveWikiLink)
+    .use(remarkRehype, { allowDangerousHtml: true })
+    .use(rehypeRaw)
+    .use(rehypeSlug)
+    .use(rehypeCollectHeadings)
+    .use(rehypeKatex)
+    .use(rehypeInternalLinks, getUrlMap())
+    .use(rehypeImages)
+    .use(rehypeCodeShell)
+    .use(rehypeShiki, {
+      themes: SHIKI_THEMES,
+      defaultColor: false,
+      cssVariablePrefix: '--shiki-',
+      fallbackLanguage: 'text',
+      // Without this Shiki loads every bundled grammar, which costs tens of
+      // seconds before the first page renders.
+      langs: getUsedLanguages(),
+    })
+    .use(rehypeBasePath, BASE_PATH)
+    .use(rehypeStringify, { allowDangerousHtml: true }) as unknown as Processor;
+}
+
+/** Language set the current processor was built with. */
+let processorLangs = '';
+
+/**
+ * Returns the shared processor, creating it on first use.
+ *
+ * Shiki loads its grammars and themes when the plugin is first applied; a
+ * per-page processor would repeat that work for every document in the site.
+ *
+ * The grammar list is fixed when the processor is constructed, so it is
+ * rebuilt if the set of languages the content uses changes — otherwise adding
+ * a code block in a new language during `next dev` would render unhighlighted
+ * until the server was restarted.
+ */
+function getProcessor(): Processor {
+  const langs = getUsedLanguages().join(',');
+
+  if (!processor || langs !== processorLangs) {
+    processor = createProcessor();
+    processorLangs = langs;
+  }
+
+  return processor;
+}
+
+/**
+ * Compiles a Markdown string to HTML and extracts its headings.
+ *
+ * @param markdown - Markdown source, with frontmatter already stripped
+ * @returns The rendered HTML and the headings found in it
+ *
+ * @example
+ * ```typescript
+ * const { html, headings } = await renderMarkdown('## Setup\n\nRun `npm i`.');
+ * headings; // [{ id: 'setup', text: 'Setup', depth: 2 }]
+ * ```
+ */
+export async function renderMarkdown(markdown: string): Promise<RenderedMarkdown> {
+  const file = await getProcessor().process(markdown);
+
+  return {
+    html: String(file),
+    headings: (file.data.headings as Heading[] | undefined) ?? [],
+  };
+}
+
+const cache = new Map<string, RenderedMarkdown>();
+
+/**
+ * Renders a document from the content registry, memoised by path.
+ *
+ * A page's metadata, its body, and its table of contents are produced by
+ * separate calls in the Next.js render lifecycle; caching keeps a document from
+ * being compiled several times per build.
+ *
+ * @param docPath - Content-relative path without extension
+ * @returns The rendered document, or null if no such document exists
+ */
+export async function renderDoc(docPath: string): Promise<RenderedMarkdown | null> {
+  const hit = cached(cache.get(docPath) ?? null);
+  if (hit) return hit;
+
+  const doc = getDoc(docPath);
+  if (!doc) return null;
+
+  const rendered = await renderMarkdown(doc.content);
+  cache.set(docPath, rendered);
+
+  return rendered;
+}

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

@@ -0,0 +1,91 @@
+import { describe, it, expect } from 'vitest';
+import { findWikiLinks, parseWikiLink } from './wikilink';
+
+describe('parseWikiLink', () => {
+  const parse = (inner: string) => parseWikiLink(inner, `[[${inner}]]`);
+
+  it('parses a bare target', () => {
+    expect(parse('guides/setup')).toMatchObject({
+      target: 'guides/setup',
+      anchor: undefined,
+      label: undefined,
+    });
+  });
+
+  it('parses a label after a pipe', () => {
+    expect(parse('guides/setup|Setup Guide')).toMatchObject({
+      target: 'guides/setup',
+      label: 'Setup Guide',
+    });
+  });
+
+  it('parses an anchor', () => {
+    expect(parse('guides/setup#step-1')).toMatchObject({
+      target: 'guides/setup',
+      anchor: 'step-1',
+    });
+  });
+
+  it('parses an anchor and a label together', () => {
+    expect(parse('guides/setup#step-1|Step one')).toMatchObject({
+      target: 'guides/setup',
+      anchor: 'step-1',
+      label: 'Step one',
+    });
+  });
+
+  it('treats a hash in the label as part of the label', () => {
+    expect(parse('setup|Step #1')).toMatchObject({
+      target: 'setup',
+      anchor: undefined,
+      label: 'Step #1',
+    });
+  });
+
+  it('keeps a pipe inside the label', () => {
+    expect(parse('setup|a | b')).toMatchObject({ target: 'setup', label: 'a | b' });
+  });
+
+  it('trims surrounding whitespace', () => {
+    expect(parse('  setup  |  Label  ')).toMatchObject({ target: 'setup', label: 'Label' });
+  });
+
+  it('allows an anchor-only link with no target', () => {
+    expect(parse('#section')).toMatchObject({ target: '', anchor: 'section' });
+  });
+
+  it('returns null when there is neither target nor anchor', () => {
+    expect(parse('')).toBeNull();
+    expect(parse('   ')).toBeNull();
+    expect(parse('|only a label')).toBeNull();
+  });
+
+  it('treats an empty label as absent', () => {
+    expect(parse('setup|')).toMatchObject({ target: 'setup', label: undefined });
+  });
+});
+
+describe('findWikiLinks', () => {
+  it('finds every link in a string', () => {
+    const links = findWikiLinks('See [[a]] and [[b|Bee]] today.');
+
+    expect(links.map((link) => link.target)).toEqual(['a', 'b']);
+    expect(links[1].label).toBe('Bee');
+  });
+
+  it('returns nothing when there are no links', () => {
+    expect(findWikiLinks('plain text')).toEqual([]);
+  });
+
+  it('does not match across a newline', () => {
+    expect(findWikiLinks('[[broken\nlink]]')).toEqual([]);
+  });
+
+  it('does not let an unterminated bracket swallow the rest', () => {
+    expect(findWikiLinks('[[unclosed and then some text')).toEqual([]);
+  });
+
+  it('captures the raw source of each match', () => {
+    expect(findWikiLinks('x [[a|B]] y')[0].raw).toBe('[[a|B]]');
+  });
+});

package/template/lib/markdown/wikilink.ts

@@ -0,0 +1,85 @@
+/**
+ * Parsing for `[[wiki link]]` syntax.
+ *
+ * Kept free of any filesystem or registry access so it can be unit-tested and
+ * reused by both the renderer and the link-graph scanner.
+ */
+
+/**
+ * Matches a wiki link and captures its contents.
+ *
+ * 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;
+
+/** The parts of a wiki link. */
+export interface WikiLink {
+  /** Document being linked to, before the anchor */
+  target: string;
+  /** In-page anchor, without the leading '#' */
+  anchor?: string;
+  /** Display text, when the author supplied one after '|' */
+  label?: string;
+  /** The full matched source, e.g. '[[guide#setup|Setup]]' */
+  raw: string;
+}
+
+/**
+ * Parses the inside of a wiki link.
+ *
+ * Supported forms:
+ * - `[[target]]`
+ * - `[[target|label]]`
+ * - `[[target#anchor]]`
+ * - `[[target#anchor|label]]`
+ *
+ * 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
+ * @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: '...' }
+ * ```
+ */
+export function parseWikiLink(inner: string, raw: string): 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();
+
+  const hash = locator.indexOf('#');
+  const target = (hash === -1 ? locator : locator.slice(0, hash)).trim();
+  const anchor = hash === -1 ? undefined : locator.slice(hash + 1).trim() || undefined;
+
+  // An anchor-only link such as [[#section]] refers within the current page.
+  if (!target && !anchor) return null;
+
+  return {
+    target,
+    anchor,
+    label: label || undefined,
+    raw,
+  };
+}
+
+/**
+ * Finds every wiki link in a string.
+ *
+ * @param text - Text to scan
+ * @returns Parsed links, in order of appearance
+ */
+export function findWikiLinks(text: string): WikiLink[] {
+  const links: WikiLink[] = [];
+
+  for (const match of text.matchAll(WIKILINK_PATTERN)) {
+    const parsed = parseWikiLink(match[1], match[0]);
+    if (parsed) links.push(parsed);
+  }
+
+  return links;
+}

package/template/lib/navigation/auto.ts

@@ -0,0 +1,227 @@
+import { NavigationItem } from '../payload/types';
+import { getContentRegistry, titleize, type ContentDoc, type DirMeta } from '../content/registry';
+import { extractAllPaths } from './builder';
+import { cached } from '../cache';
+
+/**
+ * Filesystem-derived navigation.
+ *
+ * The curated tree in `payload/config.ts` stays authoritative for naming and
+ * ordering, but it no longer has to be exhaustive: any document under
+ * `content/` that the curated tree does not mention is discovered here and
+ * appended to the section matching its directory. Adding a Markdown file is
+ * therefore enough to publish it.
+ *
+ * This module reads the content registry and must only run on the server.
+ */
+
+/** Sort weight applied to directories without an explicit `order`. */
+const DEFAULT_DIR_ORDER = Number.MAX_SAFE_INTEGER;
+
+/**
+ * Returns the parent directory of a content directory path.
+ *
+ * @param dir - Directory path relative to `content/`
+ * @returns The parent directory, or '' for a top-level directory
+ */
+function parentDir(dir: string): string {
+  const index = dir.lastIndexOf('/');
+  return index === -1 ? '' : dir.slice(0, index);
+}
+
+/**
+ * Deep-clones a navigation tree so merging never mutates the payload config.
+ *
+ * The payload is a module-level constant shared across every rendered page;
+ * appending discovered documents to it in place would compound the tree on
+ * each render during a dev session.
+ */
+function cloneTree(items: NavigationItem[]): NavigationItem[] {
+  return items.map((item) => ({
+    ...item,
+    children: item.children ? cloneTree(item.children) : undefined,
+  }));
+}
+
+/**
+ * Maps content directories to the curated section that already represents them.
+ *
+ * A curated section does not declare which directory it covers, so ownership is
+ * inferred from its descendants: a section whose documents all live under
+ * `getting-started/` is taken to own that directory. Sections spanning several
+ * directories are left unmapped, since appending to them would be a guess.
+ *
+ * @param items - Curated navigation tree
+ * @returns Directory path to the owning navigation node
+ */
+function indexSectionsByDir(items: NavigationItem[]): Map<string, NavigationItem> {
+  const sections = new Map<string, NavigationItem>();
+
+  function visit(node: NavigationItem): Set<string> {
+    const dirs = new Set<string>();
+
+    if (node.path) {
+      const index = node.path.lastIndexOf('/');
+      dirs.add(index === -1 ? '' : node.path.slice(0, index));
+    }
+
+    for (const child of node.children ?? []) {
+      for (const dir of visit(child)) dirs.add(dir);
+    }
+
+    // Only claim ownership when the section is unambiguous.
+    if (node.children && dirs.size === 1) {
+      const [dir] = Array.from(dirs);
+      if (dir && !sections.has(dir)) {
+        sections.set(dir, node);
+      }
+    }
+
+    return dirs;
+  }
+
+  for (const item of items) visit(item);
+  return sections;
+}
+
+/**
+ * The sort weight a document contributes to its position at the top level.
+ *
+ * For a document inside a folder this is the folder's `_meta.json` order, since
+ * the document's own order only ranks it among its siblings. For a root-level
+ * document there is no folder, so its own `order` serves — which is what lets a
+ * single sequence of numbers interleave root pages and sections, rather than
+ * root pages always landing after every folder.
+ */
+function sectionOrder(doc: ContentDoc, dirOrder: (dir: string) => number): number {
+  return doc.dir === '' ? doc.order : dirOrder(doc.dir);
+}
+
+/**
+ * Orders discovered documents so that appended entries land predictably.
+ *
+ * Documents are grouped by the section they belong to and those sections
+ * ordered first, so that a section is created at the right position the moment
+ * its first document is appended. Within a section, documents follow their own
+ * frontmatter order.
+ */
+function compareOrphans(a: ContentDoc, b: ContentDoc, dirOrder: (dir: string) => number): number {
+  const aSection = sectionOrder(a, dirOrder);
+  const bSection = sectionOrder(b, dirOrder);
+  if (aSection !== bSection) return aSection - bSection;
+
+  if (a.dir !== b.dir) return a.dir.localeCompare(b.dir);
+  if (a.order !== b.order) return a.order - b.order;
+  return a.title.localeCompare(b.title);
+}
+
+/**
+ * Builds a navigation node for a discovered document.
+ */
+function docToNavItem(doc: ContentDoc): NavigationItem {
+  const item: NavigationItem = {
+    name: doc.title,
+    path: doc.path,
+  };
+
+  if (typeof doc.frontmatter.icon === 'string') item.icon = doc.frontmatter.icon;
+  if (typeof doc.frontmatter.color === 'string') item.color = doc.frontmatter.color;
+
+  return item;
+}
+
+/**
+ * Builds a navigation section node for a content directory.
+ */
+function dirToNavItem(dir: string, meta: DirMeta): NavigationItem {
+  const name = meta.name ?? titleize(dir.slice(dir.lastIndexOf('/') + 1));
+  const item: NavigationItem = { name, children: [] };
+
+  if (meta.icon) item.icon = meta.icon;
+  if (meta.color) item.color = meta.color;
+  if (meta.hidden) item.hidden = true;
+
+  return item;
+}
+
+/**
+ * Merges curated navigation with documents discovered under `content/`.
+ *
+ * Curated entries are preserved exactly as written. Every document not already
+ * referenced — and not marked `hidden` in its frontmatter — is appended to the
+ * section covering its directory, creating that section (and any missing
+ * ancestors) when necessary.
+ *
+ * @param curated - Navigation from the payload config; may be empty
+ * @returns The merged navigation tree
+ *
+ * @example
+ * ```typescript
+ * // content/guides/advanced.md exists but is absent from the payload
+ * const nav = mergeDiscoveredDocs(payload.navigation ?? []);
+ * // The 'Guides' section now includes an 'Advanced' entry.
+ * ```
+ */
+export function mergeDiscoveredDocs(curated: NavigationItem[]): NavigationItem[] {
+  const { docs, dirMeta } = getContentRegistry();
+  const root = cloneTree(curated);
+
+  const referenced = new Set(extractAllPaths(root));
+  const orphans = docs.filter((doc) => !referenced.has(doc.path) && !doc.hidden);
+
+  if (orphans.length === 0) return root;
+
+  const sections = indexSectionsByDir(root);
+  const dirOrder = (dir: string) => dirMeta.get(dir)?.order ?? DEFAULT_DIR_ORDER;
+
+  /**
+   * Returns the children array that documents in `dir` should be appended to,
+   * creating the section chain if it does not exist yet.
+   */
+  function childrenFor(dir: string): NavigationItem[] {
+    if (!dir) return root;
+
+    const existing = sections.get(dir);
+    if (existing) {
+      existing.children ??= [];
+      return existing.children;
+    }
+
+    const node = dirToNavItem(dir, dirMeta.get(dir) ?? {});
+    childrenFor(parentDir(dir)).push(node);
+    sections.set(dir, node);
+
+    return node.children!;
+  }
+
+  for (const doc of [...orphans].sort((a, b) => compareOrphans(a, b, dirOrder))) {
+    childrenFor(doc.dir).push(docToNavItem(doc));
+  }
+
+  return root;
+}
+
+let memo: NavigationItem[] | null = null;
+
+/**
+ * Returns the site navigation, memoised per process.
+ *
+ * When `autoNavigation` is disabled in the payload, the curated tree is
+ * returned untouched; otherwise discovered documents are merged in.
+ *
+ * @param curated - Navigation from the payload config
+ * @param autoNavigation - Whether to append discovered documents (default true)
+ * @returns The navigation tree to render
+ */
+export function getNavigation(
+  curated: NavigationItem[] | undefined,
+  autoNavigation = true,
+): NavigationItem[] {
+  const hit = cached(memo);
+  if (hit) return hit;
+
+  const base = curated ?? [];
+  memo = autoNavigation ? mergeDiscoveredDocs(base) : cloneTree(base);
+
+  return memo;
+}