create-eziwiki 0.1.0

package/template/lib/basePath.ts

@@ -0,0 +1,108 @@
+/**
+ * Base path the site is served from, empty when served from the root.
+ *
+ * Set by the deploy workflow, and read here rather than inferred from CI so
+ * that tests, forks, and local builds are unaffected. `next.config.js` reads
+ * the same variable to configure Next itself; everything on this side of the
+ * build reads it through this module.
+ */
+export const BASE_PATH = process.env.NEXT_PUBLIC_BASE_PATH || '';
+
+/**
+ * Prefixes a path served from `public/` with the deployment base path.
+ *
+ * Next rewrites the links and assets it generates itself, but not a `href` or
+ * a `url()` written by hand — those keep pointing at the domain root and 404
+ * once the site moves into a subdirectory. Anything referencing `public/`
+ * outside of Next's own output has to go through here.
+ *
+ * Absolute and protocol-relative URLs are returned untouched, so a favicon or
+ * an image hosted elsewhere keeps working.
+ *
+ * @param path - Root-relative public path, such as `/favicon.svg`
+ * @returns The path as the browser should request it
+ *
+ * @example
+ * ```typescript
+ * asset('/favicon.svg'); // '/eziwiki/favicon.svg' when deployed to /eziwiki
+ * asset('https://cdn.example.com/logo.svg'); // unchanged
+ * ```
+ */
+export function asset(path: string): string {
+  if (!BASE_PATH) return path;
+  if (!path.startsWith('/') || path.startsWith('//')) return path;
+  return `${BASE_PATH}${path}`;
+}
+
+/**
+ * Origin the site is published under, without a trailing slash.
+ *
+ * Separate from the payload's `baseUrl`, and overriding it when set, because
+ * the origin is a property of the deployment rather than of the project: the
+ * same content is published to GitHub Pages, a preview host, and a custom
+ * domain, and each needs its own canonical URLs. The deploy workflow sets this
+ * alongside the base path.
+ */
+const SITE_ORIGIN = (process.env.NEXT_PUBLIC_SITE_URL || '').replace(/\/+$/, '');
+
+/**
+ * Resolves the root that absolute URLs are built from.
+ *
+ * The base path is part of it only when this deployment declared its own
+ * origin, because only then do the two describe the same site. A deployment
+ * that leaves the origin unset is publishing a copy of somewhere else — a
+ * GitHub Pages mirror of a site hosted elsewhere, say — and its canonical URLs
+ * have to name that other site, whose layout its own subdirectory says nothing
+ * about. Applying both would produce a URL that exists in neither place.
+ *
+ * @param payloadBaseUrl - `global.baseUrl` from the payload, used when the
+ *   deployment does not declare an origin of its own
+ * @returns Root without a trailing slash
+ */
+function canonicalRoot(payloadBaseUrl?: string): string {
+  if (SITE_ORIGIN) return `${SITE_ORIGIN}${BASE_PATH}`;
+  return (payloadBaseUrl || 'https://example.com').replace(/\/+$/, '');
+}
+
+/**
+ * Builds the absolute URL of a file, such as the sitemap or an OG image.
+ *
+ * Canonical tags, sitemap entries and social-preview metadata are read off the
+ * site by other machines, so they have to be absolute and they have to agree
+ * with each other. Composing them here is what keeps the origin and the base
+ * path from being applied in one place and forgotten in another — a canonical
+ * tag that omits the subdirectory points at a URL that does not exist.
+ *
+ * @param path - Root-relative path, such as `/sitemap.xml`
+ * @param payloadBaseUrl - Fallback origin from the payload
+ * @returns Absolute URL
+ *
+ * @example
+ * ```typescript
+ * fileUrl('/og-image.svg', 'https://example.com');
+ * // 'https://example.com/eziwiki/og-image.svg' when deployed to /eziwiki
+ * ```
+ */
+export function fileUrl(path: string, payloadBaseUrl?: string): string {
+  if (/^https?:\/\//.test(path)) return path;
+  const trimmed = path.replace(/^\/+/, '');
+  return `${canonicalRoot(payloadBaseUrl)}/${trimmed}`;
+}
+
+/**
+ * Builds the absolute URL of a page, with the trailing slash Next emits.
+ *
+ * `trailingSlash` is on, so every page is served from `…/name/` and a link to
+ * `…/name` is a redirect. Sitemap entries and canonical tags that disagree on
+ * the slash advertise a URL that is not the one the page answers on, so the
+ * form is applied here rather than at each call site.
+ *
+ * @param urlSegment - Page URL segment, without leading or trailing slash
+ * @param payloadBaseUrl - Fallback origin from the payload
+ * @returns Absolute URL ending in a slash
+ */
+export function pageUrl(urlSegment: string, payloadBaseUrl?: string): string {
+  const trimmed = urlSegment.replace(/^\/+|\/+$/g, '');
+  const base = canonicalRoot(payloadBaseUrl);
+  return trimmed ? `${base}/${trimmed}/` : `${base}/`;
+}

package/template/lib/cache.ts

@@ -0,0 +1,36 @@
+/**
+ * Whether derived data may be memoised for the lifetime of the process.
+ *
+ * Everything the site renders is derived from files under `content/`. During a
+ * build those files never change, so scanning and rendering them once and
+ * reusing the result is pure win. During `next dev` they change constantly —
+ * that is the entire point — and a process-lifetime cache would serve stale
+ * pages until the server was restarted.
+ *
+ * Test runs keep caching on: content is fixed there too, and the memoisation
+ * behaviour is itself something the tests assert.
+ */
+export const CACHE_DERIVED_CONTENT = process.env.NODE_ENV !== 'development';
+
+/**
+ * Returns the cached value when caching is enabled, otherwise nothing.
+ *
+ * Reads as a guard at the top of a memoised getter:
+ *
+ * @example
+ * ```typescript
+ * export function getThing(): Thing {
+ *   const hit = cached(memo);
+ *   if (hit) return hit;
+ *
+ *   memo = buildThing();
+ *   return memo;
+ * }
+ * ```
+ *
+ * @param value - The memoised value, or null when nothing is stored yet
+ * @returns The value in production and test, null in development
+ */
+export function cached<T>(value: T | null): T | null {
+  return CACHE_DERIVED_CONTENT ? value : null;
+}

package/template/lib/content/registry.ts

@@ -0,0 +1,311 @@
+import fs from 'fs';
+import path from 'path';
+import matter from 'gray-matter';
+import { cached } from '../cache';
+
+/**
+ * A single Markdown document discovered under the content directory.
+ *
+ * Every downstream feature — navigation, URL resolution, search indexing,
+ * backlinks — is derived from this shape rather than from hand-written
+ * configuration, so adding a file to `content/` is enough to publish a page.
+ */
+export interface ContentDoc {
+  /** Content-relative path without extension (e.g. 'guides/quick-start') */
+  path: string;
+  /** Path split on '/', useful for grouping by directory */
+  segments: string[];
+  /** Directory portion of the path, '' for root-level documents */
+  dir: string;
+  /** Display title, from frontmatter or derived from the filename */
+  title: string;
+  /** Short summary from frontmatter, if provided */
+  description?: string;
+  /** Sort weight within its directory; unset values sort last */
+  order: number;
+  /** Excluded from navigation, but still reachable by direct URL */
+  hidden: boolean;
+  /** Full parsed frontmatter, for consumers that need custom fields */
+  frontmatter: Record<string, unknown>;
+  /** Markdown body with frontmatter stripped */
+  content: string;
+  /** Absolute path on disk */
+  filePath: string;
+}
+
+/**
+ * Optional per-directory metadata, read from `_meta.json` inside a
+ * content subdirectory. Lets a folder control how its section is presented
+ * without pushing that concern into the global config.
+ */
+export interface DirMeta {
+  /** Section label shown in navigation */
+  name?: string;
+  /** Sort weight among sibling sections */
+  order?: number;
+  /** Background colour applied to the section header */
+  color?: string;
+  /** Icon identifier for the section */
+  icon?: string;
+  /** Hide the whole section from navigation */
+  hidden?: boolean;
+}
+
+/** Directory holding all Markdown content, resolved from the project root. */
+export const CONTENT_DIR = path.join(process.cwd(), 'content');
+
+/** Sort weight applied to documents that do not declare `order`. */
+const DEFAULT_ORDER = Number.MAX_SAFE_INTEGER;
+
+/**
+ * Converts a file or directory name into a human-readable title.
+ *
+ * Used as the fallback when a document has no `title` in its frontmatter
+ * and when a directory has no `_meta.json`.
+ *
+ * @param name - Raw file or directory name (without extension)
+ * @returns Title-cased label with separators replaced by spaces
+ *
+ * @example
+ * ```typescript
+ * titleize('quick-start'); // 'Quick Start'
+ * titleize('api_reference'); // 'Api Reference'
+ * ```
+ */
+export function titleize(name: string): string {
+  return name
+    .replace(/[-_]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/**
+ * Reads a numeric frontmatter field, tolerating string values.
+ *
+ * @param value - Raw frontmatter value
+ * @returns The parsed number, or DEFAULT_ORDER when absent or unparseable
+ */
+function readOrder(value: unknown): number {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string') {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return DEFAULT_ORDER;
+}
+
+/**
+ * Reads a boolean frontmatter field, tolerating string values.
+ *
+ * @param value - Raw frontmatter value
+ * @returns True when the value represents an affirmative
+ */
+function readBoolean(value: unknown): boolean {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') return value.toLowerCase() === 'true';
+  return false;
+}
+
+/**
+ * Reads the optional `_meta.json` for a content subdirectory.
+ *
+ * A malformed or unreadable file is treated as absent rather than fatal, so a
+ * typo in an optional presentation file never breaks the build.
+ *
+ * @param dirPath - Absolute path to the directory
+ * @returns Parsed directory metadata, or an empty object
+ */
+function readDirMeta(dirPath: string): DirMeta {
+  const metaPath = path.join(dirPath, '_meta.json');
+
+  try {
+    const raw = fs.readFileSync(metaPath, 'utf-8');
+    const parsed = JSON.parse(raw) as unknown;
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as DirMeta;
+    }
+    return {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Recursively collects every Markdown file beneath a directory.
+ *
+ * Files and directories whose names begin with `_` or `.` are skipped, which
+ * keeps `_meta.json`, drafts, and editor cruft out of the published site.
+ *
+ * @param dir - Absolute directory to walk
+ * @param baseDir - Absolute root of the content tree, used to derive relative paths
+ * @returns Absolute paths of every discovered `.md` file
+ */
+function walkMarkdown(dir: string, baseDir: string): string[] {
+  let entries: fs.Dirent[];
+
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const files: string[] = [];
+
+  for (const entry of entries) {
+    if (entry.name.startsWith('_') || entry.name.startsWith('.')) continue;
+
+    const fullPath = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push(...walkMarkdown(fullPath, baseDir));
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Parses a single Markdown file into a ContentDoc.
+ *
+ * @param filePath - Absolute path to the Markdown file
+ * @returns The parsed document, or null if the file could not be read
+ */
+function readDoc(filePath: string): ContentDoc | null {
+  let raw: string;
+
+  try {
+    raw = fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+
+  const { data, content } = matter(raw);
+  const frontmatter = data as Record<string, unknown>;
+
+  const relative = path.relative(CONTENT_DIR, filePath).replace(/\\/g, '/');
+  const docPath = relative.replace(/\.md$/, '');
+  const segments = docPath.split('/');
+  const fileName = segments[segments.length - 1];
+
+  return {
+    path: docPath,
+    segments,
+    dir: segments.slice(0, -1).join('/'),
+    title: typeof frontmatter.title === 'string' ? frontmatter.title : titleize(fileName),
+    description: typeof frontmatter.description === 'string' ? frontmatter.description : undefined,
+    order: readOrder(frontmatter.order),
+    hidden: readBoolean(frontmatter.hidden) || frontmatter.nav === false,
+    frontmatter,
+    content,
+    filePath,
+  };
+}
+
+/**
+ * Orders documents by explicit weight first, then alphabetically by title.
+ *
+ * Documents without an `order` fall back to title ordering, so a partially
+ * annotated directory still produces a stable, sensible sequence.
+ */
+function compareDocs(a: ContentDoc, b: ContentDoc): number {
+  if (a.order !== b.order) return a.order - b.order;
+  return a.title.localeCompare(b.title);
+}
+
+/**
+ * The full content registry: every document plus the directory metadata
+ * needed to render sections around them.
+ */
+export interface ContentRegistry {
+  /** All discovered documents, sorted by order then title */
+  docs: ContentDoc[];
+  /** Documents keyed by their content-relative path */
+  byPath: Map<string, ContentDoc>;
+  /** Directory metadata keyed by directory path relative to `content/` */
+  dirMeta: Map<string, DirMeta>;
+}
+
+let memo: ContentRegistry | null = null;
+
+/**
+ * Scans the content directory and builds the document registry.
+ *
+ * The result is memoised for the lifetime of the process. A build renders many
+ * pages from the same content tree, and rescanning the filesystem for each one
+ * is pure waste; call {@link clearRegistryCache} if the tree changes in-process.
+ *
+ * @returns The populated registry
+ *
+ * @example
+ * ```typescript
+ * const { docs, byPath } = getContentRegistry();
+ *
+ * console.log(docs.length); // 21
+ * console.log(byPath.get('getting-started/quick-start')?.title); // 'Quick Start'
+ * ```
+ */
+export function getContentRegistry(): ContentRegistry {
+  const hit = cached(memo);
+  if (hit) return hit;
+
+  const files = walkMarkdown(CONTENT_DIR, CONTENT_DIR);
+  const docs = files
+    .map(readDoc)
+    .filter((doc): doc is ContentDoc => doc !== null)
+    .sort(compareDocs);
+
+  const byPath = new Map(docs.map((doc) => [doc.path, doc]));
+
+  // Collect metadata for every directory that actually contains documents.
+  const dirMeta = new Map<string, DirMeta>();
+  const dirs = new Set<string>();
+
+  for (const doc of docs) {
+    // Register the document's directory and each of its ancestors, so that a
+    // nested section such as 'api/v2' contributes both 'api' and 'api/v2'.
+    for (let i = 1; i < doc.segments.length; i++) {
+      dirs.add(doc.segments.slice(0, i).join('/'));
+    }
+  }
+
+  for (const dir of dirs) {
+    dirMeta.set(dir, readDirMeta(path.join(CONTENT_DIR, dir)));
+  }
+
+  memo = { docs, byPath, dirMeta };
+  return memo;
+}
+
+/**
+ * Discards the memoised registry so the next call rescans the filesystem.
+ *
+ * Primarily useful in tests, and for tooling that mutates content between reads.
+ */
+export function clearRegistryCache(): void {
+  memo = null;
+}
+
+/**
+ * Looks up a single document by its content-relative path.
+ *
+ * @param docPath - Path without extension (e.g. 'guides/quick-start')
+ * @returns The document, or undefined if no such file exists
+ */
+export function getDoc(docPath: string): ContentDoc | undefined {
+  return getContentRegistry().byPath.get(docPath);
+}
+
+/**
+ * Returns every document path in the content tree.
+ *
+ * Unlike navigation-derived path lists, this includes documents that are
+ * hidden or absent from the sidebar — they still need to be built.
+ *
+ * @returns Content-relative paths, sorted
+ */
+export function getAllDocPaths(): string[] {
+  return getContentRegistry().docs.map((doc) => doc.path);
+}

package/template/lib/content/resolver.ts

@@ -0,0 +1,109 @@
+import { getContentRegistry, type ContentDoc } from './registry';
+import { cached } from '../cache';
+
+/**
+ * Resolves the loose targets people write in wiki links to actual documents.
+ *
+ * Obsidian-style linking lets an author write `[[quick-start]]` without knowing
+ * where the file sits in the tree. That convenience only holds if the shorthand
+ * resolves predictably, so lookups run in a fixed order and ambiguous shorthand
+ * is refused rather than guessed at.
+ */
+
+/** How a target was matched, for diagnostics. */
+export type ResolutionKind = 'path' | 'basename' | 'title' | 'ambiguous' | 'missing';
+
+/** Outcome of resolving a link target. */
+export interface Resolution {
+  /** The matched document, if exactly one was found */
+  doc?: ContentDoc;
+  /** How the match was made, or why it failed */
+  kind: ResolutionKind;
+  /** Candidate paths, when the target was ambiguous */
+  candidates?: string[];
+}
+
+interface ResolverIndex {
+  byPath: Map<string, ContentDoc>;
+  byBasename: Map<string, ContentDoc[]>;
+  byTitle: Map<string, ContentDoc[]>;
+}
+
+let memo: ResolverIndex | null = null;
+
+/**
+ * Normalises a target for comparison: trimmed, lower-cased, extension removed.
+ */
+function normalize(target: string): string {
+  return target.trim().replace(/^\/+/, '').replace(/\/+$/, '').replace(/\.md$/i, '').toLowerCase();
+}
+
+/**
+ * Builds the lookup tables, memoised per process.
+ */
+function getIndex(): ResolverIndex {
+  const hit = cached(memo);
+  if (hit) return hit;
+
+  const byPath = new Map<string, ContentDoc>();
+  const byBasename = new Map<string, ContentDoc[]>();
+  const byTitle = new Map<string, ContentDoc[]>();
+
+  const push = (map: Map<string, ContentDoc[]>, key: string, doc: ContentDoc) => {
+    const existing = map.get(key);
+    if (existing) existing.push(doc);
+    else map.set(key, [doc]);
+  };
+
+  for (const doc of getContentRegistry().docs) {
+    byPath.set(normalize(doc.path), doc);
+    push(byBasename, normalize(doc.segments[doc.segments.length - 1]), doc);
+    push(byTitle, normalize(doc.title), doc);
+  }
+
+  memo = { byPath, byBasename, byTitle };
+  return memo;
+}
+
+/**
+ * Resolves a wiki-link target to a document.
+ *
+ * Order is full path, then file name, then page title. A shorthand matching
+ * several documents resolves to none of them: silently picking the first would
+ * make the link's destination depend on directory scan order, which is exactly
+ * the kind of bug nobody finds until the wrong page ships.
+ *
+ * @param target - Raw target text from inside the brackets
+ * @returns The resolution, including why it failed when it did
+ *
+ * @example
+ * ```typescript
+ * resolveTarget('getting-started/quick-start').kind; // 'path'
+ * resolveTarget('quick-start').kind; // 'basename'
+ * resolveTarget('Quick Start').kind; // 'title'
+ * resolveTarget('nope').kind; // 'missing'
+ * ```
+ */
+export function resolveTarget(target: string): Resolution {
+  const key = normalize(target);
+  if (!key) return { kind: 'missing' };
+
+  const { byPath, byBasename, byTitle } = getIndex();
+
+  const exact = byPath.get(key);
+  if (exact) return { doc: exact, kind: 'path' };
+
+  for (const [map, kind] of [
+    [byBasename, 'basename'],
+    [byTitle, 'title'],
+  ] as const) {
+    const matches = map.get(key);
+    if (!matches || matches.length === 0) continue;
+
+    if (matches.length === 1) return { doc: matches[0], kind };
+
+    return { kind: 'ambiguous', candidates: matches.map((doc) => doc.path) };
+  }
+
+  return { kind: 'missing' };
+}