create-eziwiki 0.2.0 → 0.4.0

package/template/lib/content/registry.ts

@@ -25,6 +25,21 @@ export interface ContentDoc {
   order: number;
   /** Excluded from navigation, but still reachable by direct URL */
   hidden: boolean;
+  /**
+   * Labels grouping this document with others across the folder tree.
+   *
+   * A file sits in exactly one directory, so the sidebar can only express one
+   * way of organising a wiki. Tags are the second axis: a page belongs to one
+   * section and to as many subjects as it touches.
+   */
+  tags: string[];
+  /**
+   * Paths this document used to live at.
+   *
+   * A wiki moves pages; without these, every published link to the old
+   * location breaks silently the moment a file is renamed.
+   */
+  aliases: string[];
   /** Full parsed frontmatter, for consumers that need custom fields */
   frontmatter: Record<string, unknown>;
   /** Markdown body with frontmatter stripped */
@@ -107,6 +122,63 @@ function readBoolean(value: unknown): boolean {
   return false;
 }
 
+/**
+ * Reads the `tags` frontmatter.
+ *
+ * Accepts a single tag or a list, and a comma-separated string, because all
+ * three are how people write this and none of them is wrong. Tags are compared
+ * case-insensitively — `Setup` and `setup` are one subject, and treating them
+ * as two would split a wiki quietly — but the first spelling seen is the one
+ * displayed.
+ *
+ * @param value - The raw frontmatter value
+ * @returns Tags in the order written, without duplicates
+ */
+function readTags(value: unknown): string[] {
+  const raw = typeof value === 'string' ? value.split(',') : Array.isArray(value) ? value : [];
+
+  const seen = new Set<string>();
+  const tags: string[] = [];
+
+  for (const entry of raw) {
+    if (typeof entry !== 'string') continue;
+
+    const tag = entry.trim();
+    if (!tag) continue;
+
+    const key = tag.toLowerCase();
+    if (seen.has(key)) continue;
+
+    seen.add(key);
+    tags.push(tag);
+  }
+
+  return tags;
+}
+
+/**
+ * Reads the `aliases` frontmatter into a list of content paths.
+ *
+ * Accepts a single string or a list, since an author moving one page writes
+ * one path and should not have to remember which form is required. Leading and
+ * trailing slashes and a `.md` suffix are tolerated: the value looks like a
+ * path, and being strict about its punctuation would only produce silent
+ * misses.
+ *
+ * @param value - The raw frontmatter value
+ * @returns Normalised content paths, without duplicates
+ */
+function readAliases(value: unknown): string[] {
+  const raw = typeof value === 'string' ? [value] : Array.isArray(value) ? value : [];
+
+  const paths = raw
+    .filter((entry): entry is string => typeof entry === 'string')
+    .map((entry) => entry.trim().replace(/^\/+/, '').replace(/\.md$/i, '').replace(/\/+$/, ''))
+    .filter(Boolean);
+
+  return [...new Set(paths)];
+}
+
 /**
  * Reads the optional `_meta.json` for a content subdirectory.
  *
@@ -198,6 +270,8 @@ function readDoc(filePath: string): ContentDoc | null {
     description: typeof frontmatter.description === 'string' ? frontmatter.description : undefined,
     order: readOrder(frontmatter.order),
     hidden: readBoolean(frontmatter.hidden) || frontmatter.nav === false,
+    tags: readTags(frontmatter.tags),
+    aliases: readAliases(frontmatter.aliases),
     frontmatter,
     content,
     filePath,

package/template/lib/content/tags.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect } from 'vitest';
+import { getTags, getTag, getTagsFor, findTagRouteCollisions } from './tags';
+import { getContentRegistry } from './registry';
+import { getSite } from '../site';
+
+describe('getTags', () => {
+  it('gathers pages by subject across the folder tree', () => {
+    for (const tag of getTags()) {
+      expect(tag.pages.length).toBeGreaterThan(0);
+      expect(tag.slug).toBe(tag.name.toLowerCase());
+    }
+  });
+
+  it('sorts subjects by name', () => {
+    const names = getTags().map((tag) => tag.name);
+
+    expect(names).toEqual([...names].sort((a, b) => a.localeCompare(b)));
+  });
+
+  // A page kept off the sidebar on purpose should not reappear here, or the
+  // tag index becomes a way of enumerating exactly what was unlisted.
+  it('leaves hidden pages out', () => {
+    const { hiddenPaths } = getSite();
+    const listed = getTags().flatMap((tag) => tag.pages.map((page) => page.path));
+
+    for (const hidden of hiddenPaths) {
+      expect(listed).not.toContain(hidden);
+    }
+  });
+
+  it('emits URLs in the form the export serves', () => {
+    for (const tag of getTags()) {
+      for (const page of tag.pages) {
+        expect(page.url).toMatch(/^\/.*\/$/);
+      }
+    }
+  });
+
+  it('lists a page under each of its tags', () => {
+    const { docs } = getContentRegistry();
+    const { hiddenPaths } = getSite();
+
+    for (const doc of docs) {
+      if (hiddenPaths.has(doc.path) || doc.tags.length === 0) continue;
+
+      for (const name of doc.tags) {
+        const tag = getTag(name.toLowerCase());
+        expect(tag?.pages.some((page) => page.path === doc.path)).toBe(true);
+      }
+    }
+  });
+});
+
+describe('getTag', () => {
+  it('finds a subject however its name is cased', () => {
+    const [first] = getTags();
+    if (!first) return;
+
+    expect(getTag(first.slug)?.slug).toBe(first.slug);
+    expect(getTag(first.slug.toUpperCase())?.slug).toBe(first.slug);
+  });
+
+  it('finds nothing for a subject no page carries', () => {
+    expect(getTag('no-such-subject')).toBeNull();
+  });
+});
+
+describe('getTagsFor', () => {
+  it('returns the tags a page carries', () => {
+    const { docs } = getContentRegistry();
+    const { hiddenPaths } = getSite();
+    const tagged = docs.find((doc) => doc.tags.length > 0 && !hiddenPaths.has(doc.path));
+    if (!tagged) return;
+
+    expect(
+      getTagsFor(tagged.path)
+        .map((tag) => tag.slug)
+        .sort(),
+    ).toEqual(tagged.tags.map((tag) => tag.toLowerCase()).sort());
+  });
+
+  it('returns nothing for an untagged page', () => {
+    expect(getTagsFor('no/such/page')).toEqual([]);
+  });
+});
+
+// `/tags/…` is a route of its own and Next resolves it before the catch-all,
+// so a page published there would be unreachable.
+describe('findTagRouteCollisions', () => {
+  it('reports no collision in this wiki', () => {
+    expect(findTagRouteCollisions()).toEqual([]);
+  });
+});

package/template/lib/content/tags.ts

@@ -0,0 +1,139 @@
+import { getContentRegistry, type ContentDoc } from './registry';
+import { getSite } from '../site';
+import { docPathToUrl } from '../navigation/url';
+import { cached } from '../cache';
+
+/**
+ * Subjects, gathered across the folder tree.
+ *
+ * A file lives in one directory, so the sidebar can only ever show one way of
+ * organising a wiki. Tags are the other way: a page sits in one section and
+ * touches as many subjects as it touches. Where the graph says which pages
+ * mention each other, tags say which are about the same thing whether or not
+ * anyone thought to link them.
+ *
+ * Server-only: reads the content registry.
+ */
+
+/** Route segment the tag pages live under. */
+export const TAGS_SEGMENT = 'tags';
+
+/** A page carrying a tag. */
+export interface TaggedPage {
+  /** Content path */
+  path: string;
+  /** Display title */
+  title: string;
+  /** Href, in the site's configured URL form */
+  url: string;
+  /** Short summary, when the page has one */
+  description?: string;
+}
+
+/** A subject and the pages about it. */
+export interface Tag {
+  /** The tag as first written by an author */
+  name: string;
+  /** Lowercased form, used in URLs and for comparison */
+  slug: string;
+  /** Pages carrying it, in reading order */
+  pages: TaggedPage[];
+}
+
+let memo: Tag[] | null = null;
+
+/**
+ * Converts a page to the shape a listing needs.
+ */
+function toTaggedPage(doc: ContentDoc): TaggedPage | null {
+  const url = docPathToUrl(getSite().urlMap, doc.path);
+  if (!url) return null;
+
+  return { path: doc.path, title: doc.title, url: `/${url}/`, description: doc.description };
+}
+
+/**
+ * Collects every tag and the pages carrying it.
+ *
+ * Hidden pages are left out. A page kept off the sidebar on purpose should not
+ * reappear in a tag listing, which would make the tag index a way of
+ * enumerating exactly what was meant to stay unlisted.
+ *
+ * @returns Tags sorted by name, each with its pages
+ *
+ * @example
+ * ```typescript
+ * getTags().map((tag) => `${tag.name} (${tag.pages.length})`);
+ * ```
+ */
+export function getTags(): Tag[] {
+  const hit = cached(memo);
+  if (hit) return hit;
+
+  const { docs } = getContentRegistry();
+  const { hiddenPaths } = getSite();
+  const bySlug = new Map<string, Tag>();
+
+  for (const doc of docs) {
+    if (hiddenPaths.has(doc.path)) continue;
+
+    const page = toTaggedPage(doc);
+    if (!page) continue;
+
+    for (const name of doc.tags) {
+      const slug = name.toLowerCase();
+      const existing = bySlug.get(slug);
+
+      // The first spelling wins, so a wiki that writes `Setup` once and `setup`
+      // thereafter still shows one tag rather than two.
+      if (existing) existing.pages.push(page);
+      else bySlug.set(slug, { name, slug, pages: [page] });
+    }
+  }
+
+  memo = [...bySlug.values()].sort((a, b) => a.name.localeCompare(b.name));
+  return memo;
+}
+
+/**
+ * Finds one tag by its slug.
+ *
+ * @param slug - Lowercased tag name from the URL
+ * @returns The tag, or null when nothing carries it
+ */
+export function getTag(slug: string): Tag | null {
+  const wanted = decodeURIComponent(slug).toLowerCase();
+  return getTags().find((tag) => tag.slug === wanted) ?? null;
+}
+
+/**
+ * Returns the tags on one page, in the order they were written.
+ *
+ * @param path - Content path
+ * @returns The page's tags, empty when it has none
+ */
+export function getTagsFor(path: string): Tag[] {
+  return getTags().filter((tag) => tag.pages.some((page) => page.path === path));
+}
+
+/**
+ * Reports a content page whose URL the tag routes would shadow.
+ *
+ * `/tags/…` is a route of its own, and Next resolves it before the catch-all
+ * that serves content, so a page published at that address would become
+ * unreachable. Surfacing it is better than letting a page quietly disappear;
+ * the fix is to rename the file or the directory.
+ *
+ * @returns Paths that collide, empty when none do
+ */
+export function findTagRouteCollisions(): string[] {
+  const { docs } = getContentRegistry();
+  const { urlMap } = getSite();
+
+  return docs
+    .filter((doc) => {
+      const url = docPathToUrl(urlMap, doc.path);
+      return url === TAGS_SEGMENT || url?.startsWith(`${TAGS_SEGMENT}/`);
+    })
+    .map((doc) => doc.path);
+}

package/template/lib/graph/health.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from 'vitest';
+import { getWikiHealth } from './health';
+import { getLinkGraph } from './build';
+import { getReadingOrder } from '../navigation/sequence';
+
+describe('getWikiHealth', () => {
+  it('finds pages nothing links to', () => {
+    const graph = getLinkGraph();
+
+    for (const page of getWikiHealth().orphans) {
+      expect(graph.backlinks.get(page.path) ?? []).toHaveLength(0);
+    }
+  });
+
+  it('finds pages with no links out', () => {
+    const graph = getLinkGraph();
+
+    for (const page of getWikiHealth().deadEnds) {
+      expect(graph.outbound.get(page.path) ?? []).toHaveLength(0);
+    }
+  });
+
+  // Where a reader starts needs nothing pointing at it. Reporting it on every
+  // build would teach everyone to ignore the report.
+  it('never calls the entry page an orphan', () => {
+    const [entry] = getReadingOrder();
+
+    expect(getWikiHealth().orphans.map((page) => page.path)).not.toContain(entry);
+  });
+
+  it('reports only pages that are in the graph', () => {
+    const paths = new Set(getLinkGraph().nodes.map((node) => node.path));
+    const { orphans, deadEnds } = getWikiHealth();
+
+    for (const page of [...orphans, ...deadEnds]) {
+      expect(paths.has(page.path)).toBe(true);
+    }
+  });
+
+  // Hidden pages are absent from the graph entirely, so an unlisted page is
+  // not reported as disconnected — it is unlisted on purpose.
+  it('says nothing about hidden pages', () => {
+    const { orphans, deadEnds } = getWikiHealth();
+    const reported = [...orphans, ...deadEnds].map((page) => page.path);
+    const visible = new Set(getLinkGraph().nodes.map((node) => node.path));
+
+    for (const path of reported) {
+      expect(visible.has(path)).toBe(true);
+    }
+  });
+
+  it('gives every reported page a title and a link', () => {
+    const { orphans, deadEnds } = getWikiHealth();
+
+    for (const page of [...orphans, ...deadEnds]) {
+      expect(page.title).toBeTruthy();
+      expect(page.url).toBeTruthy();
+    }
+  });
+});

package/template/lib/graph/health.ts

@@ -0,0 +1,58 @@
+import { getLinkGraph, type GraphNode } from './build';
+import { getReadingOrder } from '../navigation/sequence';
+import { cached } from '../cache';
+
+/**
+ * What the link graph says about the state of the wiki.
+ *
+ * A broken link is an error and already reported. These are not errors — a
+ * wiki can be perfectly correct and still have them — but they are the shapes
+ * a collection of documents falls into when it stops being a wiki: pages
+ * nothing leads to, and pages nothing leads on from. Neither is visible from
+ * inside a single document, and neither shows up in a link check, which only
+ * asks whether the links that exist resolve.
+ *
+ * Server-only.
+ */
+
+/** Pages the graph flags as worth a second look. */
+export interface WikiHealth {
+  /** Pages nothing links to, so a reader can only arrive through the sidebar */
+  orphans: GraphNode[];
+  /** Pages with no links out, where a reader arrives and has nowhere to go */
+  deadEnds: GraphNode[];
+}
+
+let memo: WikiHealth | null = null;
+
+/**
+ * Finds pages that are disconnected from the rest of the wiki.
+ *
+ * The first page in reading order is never an orphan. It is where a reader
+ * starts, so nothing needs to point at it, and reporting it every build would
+ * teach everyone to ignore the report.
+ *
+ * @returns The pages worth looking at
+ *
+ * @example
+ * ```typescript
+ * const { orphans, deadEnds } = getWikiHealth();
+ * orphans.map((page) => page.path); // ['examples/api-docs', …]
+ * ```
+ */
+export function getWikiHealth(): WikiHealth {
+  const hit = cached(memo);
+  if (hit) return hit;
+
+  const graph = getLinkGraph();
+  const [entry] = getReadingOrder();
+
+  const orphans = graph.nodes.filter(
+    (node) => node.path !== entry && (graph.backlinks.get(node.path) ?? []).length === 0,
+  );
+
+  const deadEnds = graph.nodes.filter((node) => (graph.outbound.get(node.path) ?? []).length === 0);
+
+  memo = { orphans, deadEnds };
+  return memo;
+}

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

@@ -0,0 +1,87 @@
+import { describe, it, expect } from 'vitest';
+import { renderMarkdown } from './render';
+
+/** Renders a callout and reports what it became. */
+async function render(markdown: string) {
+  const { html } = await renderMarkdown(`${markdown}\n`);
+
+  return {
+    html,
+    kind: (html.match(/ezw-callout--(\w+)/) ?? [])[1] ?? null,
+    tag: (html.match(/<(details|div)[^>]*ezw-callout/) ?? [])[1] ?? null,
+    title: (html.match(/ezw-callout__title">([^<]*)/) ?? [])[1] ?? null,
+  };
+}
+
+describe('callouts', () => {
+  it('turns a marked blockquote into a callout', async () => {
+    const { kind, tag, title, html } = await render('> [!NOTE]\n> Useful information.');
+
+    expect(kind).toBe('note');
+    expect(tag).toBe('div');
+    expect(title).toBe('Note');
+    expect(html).toContain('Useful information.');
+  });
+
+  it('uses a title given on the marker line', async () => {
+    expect((await render('> [!WARNING] Mind the gap\n> Careful.')).title).toBe('Mind the gap');
+  });
+
+  it('recognises the kinds case-insensitively', async () => {
+    expect((await render('> [!note]\n> x')).kind).toBe('note');
+    expect((await render('> [!NoTe]\n> x')).kind).toBe('note');
+  });
+
+  // Obsidian defines more kinds than GitHub and vaults use them, so they map
+  // onto the nearest one instead of losing their formatting.
+  it('maps the extra Obsidian kinds onto the nearest one', async () => {
+    expect((await render('> [!danger]\n> x')).kind).toBe('caution');
+    expect((await render('> [!success]\n> x')).kind).toBe('tip');
+    expect((await render('> [!question]\n> x')).kind).toBe('important');
+  });
+
+  it('leaves an unknown kind as an ordinary quote', async () => {
+    const { kind, html } = await render('> [!nonsense]\n> x');
+
+    expect(kind).toBeNull();
+    expect(html).toContain('<blockquote>');
+  });
+
+  it('leaves a plain quote alone', async () => {
+    const { kind, html } = await render('> Just a quote.');
+
+    expect(kind).toBeNull();
+    expect(html).toContain('<blockquote>');
+  });
+
+  // `<details>` opens and closes without script, so a disclosure keeps working
+  // with JavaScript disabled.
+  it('folds with a trailing - or +', async () => {
+    const closed = await render('> [!TIP]- Optional\n> Hidden.');
+    const open = await render('> [!TIP]+ Shown\n> Visible.');
+
+    expect(closed.tag).toBe('details');
+    expect(closed.html).not.toMatch(/<details[^>]*\sopen/);
+    expect(open.tag).toBe('details');
+    expect(open.html).toMatch(/<details[^>]*\sopen/);
+  });
+
+  // The body passes through the rest of the pipeline, so nothing inside a
+  // callout behaves differently from the same text outside one.
+  it('renders links, wiki links and code inside the body', async () => {
+    // `intro` is the one page both this repository and a scaffolded project
+    // have, so the test travels with the engine.
+    const wiki = await render('> [!NOTE]\n> See [[intro]].');
+    const code = await render('> [!TIP]\n> Run `npm i`.');
+
+    expect(wiki.html).toContain('ezw-wikilink');
+    expect(code.html).toContain('<code');
+  });
+
+  it('keeps a multi-line body together', async () => {
+    const { html } = await render('> [!NOTE]\n> First line.\n> Second line.');
+
+    expect(html).toContain('First line.');
+    expect(html).toContain('Second line.');
+  });
+});

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

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest';
+import { renderMarkdown } from './render';
+
+/** Wraps a diagram in a fence tagged `mermaid`. */
+function fence(body: string): string {
+  return ['```mermaid', body, '```', ''].join('\n');
+}
+
+describe('mermaid diagrams', () => {
+  it('draws a fence as SVG during the build', async () => {
+    const { html } = await renderMarkdown(fence('flowchart TD\n  A[One] --> B[Two]'));
+
+    expect(html).toContain('class="ezw-mermaid"');
+    expect(html).toContain('<svg');
+    expect(html).toContain('One');
+  });
+
+  // The site self-hosts and subsets its fonts; the renderer inlines a Google
+  // Fonts import that would undo that on every page carrying a diagram.
+  it('carries no third-party request', async () => {
+    const { html } = await renderMarkdown(fence('flowchart TD\n  A --> B'));
+
+    expect(html).not.toContain('fonts.googleapis.com');
+    expect(html).not.toContain('@import');
+  });
+
+  // Fixed inline, the colours would survive a switch to dark; left to CSS, the
+  // diagram follows the theme like everything else.
+  it('leaves its colours to the stylesheet', async () => {
+    const { html } = await renderMarkdown(fence('flowchart TD\n  A --> B'));
+
+    expect(html).toMatch(/var\(--(bg|fg)\)/);
+    expect(html).not.toMatch(/<svg[^>]*style="[^"]*--bg/);
+  });
+
+  // Nothing is drawn in the browser, so a crawler and a reader without
+  // JavaScript see the same diagram everyone else does.
+  it('needs no script to appear', async () => {
+    const { html } = await renderMarkdown(fence('flowchart TD\n  A --> B'));
+
+    expect(html).not.toContain('<script');
+  });
+
+  it('draws the kinds a wiki actually uses', async () => {
+    const kinds = [
+      'sequenceDiagram\n  A->>B: hello',
+      'stateDiagram-v2\n  [*] --> Draft',
+      'classDiagram\n  class Page',
+      'erDiagram\n  PAGE ||--o{ LINK : has',
+    ];
+
+    for (const source of kinds) {
+      expect((await renderMarkdown(fence(source))).html).toContain('ezw-mermaid');
+    }
+  });
+
+  // A kind the renderer cannot draw leaves the reader exactly what they had
+  // before diagrams existed, rather than stopping the build.
+  it('falls back to a code block on an unsupported diagram', async () => {
+    const { html } = await renderMarkdown(fence('pie title X\n  "a" : 1'));
+
+    expect(html).not.toContain('ezw-mermaid');
+    expect(html).toContain('data-language="mermaid"');
+  });
+
+  it('leaves ordinary code fences alone', async () => {
+    const { html } = await renderMarkdown('```js\nconst a = 1;\n```\n');
+
+    expect(html).toContain('ezw-code');
+    expect(html).not.toContain('ezw-mermaid');
+  });
+});