create-eziwiki 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-eziwiki",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Scaffold a new eziwiki documentation site",
   "type": "module",
   "bin": {

package/template/app/[...slug]/page.tsx

@@ -3,7 +3,13 @@ import { PageTransition } from '@/components/markdown/PageTransition';
 import { TableOfContents } from '@/components/layout/TableOfContents';
 import { Backlinks } from '@/components/layout/Backlinks';
 import { LocalGraph } from '@/components/layout/LocalGraph';
+import { PageNavigation } from '@/components/layout/PageNavigation';
+import { PageTags } from '@/components/layout/PageTags';
+import { MovedPage } from '@/components/layout/MovedPage';
 import { getBacklinks, getLocalGraph } from '@/lib/graph/build';
+import { getAdjacentPages } from '@/lib/navigation/sequence';
+import { getAliasMap, aliasUrl, resolveAliasUrl } from '@/lib/content/aliases';
+import { getTagsFor } from '@/lib/content/tags';
 import { renderDoc } from '@/lib/markdown/render';
 import { getDoc, type ContentDoc } from '@/lib/content/registry';
 import { docPathToUrl, urlToDocPath } from '@/lib/navigation/url';
@@ -36,6 +42,25 @@ function resolveSlug(slug: string[]): { path: string; url: string } | null {
   return path ? { path, url } : null;
 }
 
+/**
+ * Resolves a slug that names a page's former address.
+ *
+ * Checked only after the live map misses, so a real page always wins over an
+ * alias — an alias shadowing a page is refused when the index is built, but
+ * order here makes the intent explicit.
+ *
+ * @param slug - Route segments captured by the catch-all route
+ * @returns The document that superseded the address, and its URL, or null
+ */
+function resolveMoved(slug: string[]): { path: string; url: string } | null {
+  const { urlMap } = getSite();
+  const path = resolveAliasUrl(slug.join('/'), urlMap.strategy);
+  if (!path) return null;
+
+  const url = docPathToUrl(urlMap, path);
+  return url ? { path, url } : null;
+}
+
 /**
  * Generates per-page metadata from the document's frontmatter.
  */
@@ -45,6 +70,21 @@ export async function generateMetadata({ params }: PageProps): Promise<Metadata>
   const doc = resolved ? getDoc(resolved.path) : undefined;
 
   if (!resolved || !doc) {
+    const moved = resolveMoved(params.slug);
+    const target = moved ? getDoc(moved.path) : undefined;
+
+    // A former address should not compete with the page it forwards to: it is
+    // kept out of the index, and points its canonical at the destination so any
+    // ranking the old URL earned transfers rather than being split.
+    if (moved && target) {
+      return {
+        title: target.title,
+        description: target.description || global.description,
+        alternates: { canonical: pageUrl(moved.url, global.baseUrl) },
+        robots: { index: false, follow: true },
+      };
+    }
+
     return { title: global.title, description: global.description };
   }
 
@@ -90,10 +130,18 @@ export async function generateMetadata({ params }: PageProps): Promise<Metadata>
 export async function generateStaticParams() {
   const { urlMap, docPaths } = getSite();
 
-  return docPaths.flatMap((path) => {
+  const pages = docPaths.flatMap((path) => {
     const url = docPathToUrl(urlMap, path);
     return url ? [{ slug: url.split('/') }] : [];
   });
+
+  // Former addresses are built too, each as a page that forwards. Without this
+  // there is nothing at the old URL for a static host to serve.
+  const moved = [...getAliasMap().keys()].map((alias) => ({
+    slug: aliasUrl(alias, urlMap.strategy).split('/'),
+  }));
+
+  return [...pages, ...moved];
 }
 
 /**
@@ -136,7 +184,14 @@ function ArticleSchema({ doc, url }: { doc: ContentDoc; url: string }) {
 export default async function ContentPage({ params }: PageProps) {
   const resolved = resolveSlug(params.slug);
 
-  if (!resolved) notFound();
+  if (!resolved) {
+    const moved = resolveMoved(params.slug);
+    const target = moved ? getDoc(moved.path) : undefined;
+
+    if (moved && target) return <MovedPage url={`/${moved.url}/`} title={target.title} />;
+
+    notFound();
+  }
 
   const doc = getDoc(resolved.path);
   const rendered = await renderDoc(resolved.path);
@@ -148,7 +203,9 @@ export default async function ContentPage({ params }: PageProps) {
       <div className="flex gap-8">
         <article className="prose prose-slate min-w-0 max-w-none flex-1 dark:prose-invert">
           <ArticleSchema doc={doc} url={resolved.url} />
+          <PageTags tags={getTagsFor(resolved.path)} />
           <MarkdownContent html={rendered.html} />
+          <PageNavigation adjacent={getAdjacentPages(resolved.path)} />
           <Backlinks links={getBacklinks(resolved.path)} />
           <LocalGraph graph={getLocalGraph(resolved.path)} path={resolved.path} />
         </article>

package/template/app/layout.tsx

@@ -130,12 +130,15 @@ const fontFaceCss = FONT_FACES.map(
     `unicode-range:${RANGES[font.subset]}}`,
 ).join('');
 
+/** Language announced when the payload names none. */
+const DEFAULT_LANG = 'en';
+
 export default function RootLayout({ children }: { children: React.ReactNode }) {
   const site = getSite();
   const homeUrl = pageUrl('', site.global.baseUrl);
 
   return (
-    <html lang="en">
+    <html lang={site.global.lang ?? DEFAULT_LANG}>
       <head>
         {FONT_FACES.filter((font) => font.preload).map((font) => (
           <link

package/template/app/sitemap.ts

@@ -2,6 +2,7 @@ import { MetadataRoute } from 'next';
 import { getSite } from '@/lib/site';
 import { docPathToUrl } from '@/lib/navigation/url';
 import { pageUrl } from '@/lib/basePath';
+import { getTags } from '@/lib/content/tags';
 
 /**
  * Generates the sitemap for every published page.
@@ -44,5 +45,24 @@ export default function sitemap(): MetadataRoute.Sitemap {
     ];
   });
 
-  return [homeEntry, ...contentEntries];
+  // Tag pages are indexable and canonical, so leaving them out of the sitemap
+  // said one thing to a crawler following links and another to one reading
+  // this. The index is listed even when empty; a tag page only exists when
+  // something carries it.
+  const tagEntries: MetadataRoute.Sitemap = [
+    {
+      url: pageUrl('tags', global.baseUrl),
+      lastModified,
+      changeFrequency: 'weekly',
+      priority: 0.4,
+    },
+    ...getTags().map((tag) => ({
+      url: pageUrl(`tags/${tag.slug}`, global.baseUrl),
+      lastModified,
+      changeFrequency: 'weekly' as const,
+      priority: 0.4,
+    })),
+  ];
+
+  return [homeEntry, ...contentEntries, ...tagEntries];
 }

package/template/app/tags/[[...tag]]/page.tsx

@@ -0,0 +1,139 @@
+import Link from 'next/link';
+import { notFound } from 'next/navigation';
+import type { Metadata } from 'next';
+import { getTag, getTags, type Tag } from '@/lib/content/tags';
+import { getSite } from '@/lib/site';
+import { pageUrl } from '@/lib/basePath';
+
+interface PageProps {
+  params: { tag?: string[] };
+}
+
+/**
+ * The tag index and every tag, served by one route.
+ *
+ * An optional catch-all rather than two routes because a static export refuses
+ * a dynamic segment whose `generateStaticParams` comes back empty — which is
+ * exactly what a new wiki has, before anyone has written a tag. Folded together,
+ * the index is always one of the params and the build has something to make.
+ */
+export async function generateStaticParams() {
+  return [{ tag: [] as string[] }, ...getTags().map((tag) => ({ tag: [tag.slug] }))];
+}
+
+/** The tag a route names, or null when the route is the index. */
+function resolveTag(params: PageProps['params']): Tag | null {
+  const [slug] = params.tag ?? [];
+  return slug ? getTag(slug) : null;
+}
+
+export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
+  const { global } = getSite();
+  const [slug] = params.tag ?? [];
+
+  if (!slug) {
+    return {
+      title: 'Tags',
+      description: 'Subjects across the wiki',
+      alternates: { canonical: pageUrl('tags', global.baseUrl) },
+    };
+  }
+
+  const tag = getTag(slug);
+  if (!tag) return { title: 'Tag', description: global.description };
+
+  return {
+    title: tag.name,
+    description: `Pages about ${tag.name}`,
+    alternates: { canonical: pageUrl(`tags/${tag.slug}`, global.baseUrl) },
+  };
+}
+
+/**
+ * Lists every subject, or the pages about one.
+ *
+ * The sidebar shows one arrangement — the folder tree — and this shows the
+ * other. A page belongs to one section and to as many subjects as it touches,
+ * and only this view can say so.
+ */
+export default function TagsPage({ params }: PageProps) {
+  const [slug] = params.tag ?? [];
+
+  if (slug) {
+    const tag = resolveTag(params);
+    if (!tag) notFound();
+
+    return (
+      <div className="mx-auto max-w-3xl px-6 py-10">
+        <Link
+          href="/tags/"
+          className="text-xs uppercase tracking-wide text-gray-500 no-underline hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-200"
+        >
+          Tags
+        </Link>
+
+        <h1 className="mt-2 text-2xl font-semibold text-gray-900 dark:text-gray-100">{tag.name}</h1>
+
+        <p className="mt-2 text-sm text-gray-600 dark:text-gray-400">
+          {tag.pages.length} {tag.pages.length === 1 ? 'page' : 'pages'}
+        </p>
+
+        <ul className="mt-6 space-y-3">
+          {tag.pages.map((page) => (
+            <li key={page.path}>
+              <Link
+                href={page.url}
+                className="block rounded-lg border border-gray-200 p-4 no-underline transition-colors hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:hover:border-gray-700 dark:hover:bg-gray-800/50"
+              >
+                <span className="block text-sm font-medium text-gray-900 dark:text-gray-100">
+                  {page.title}
+                </span>
+                {page.description && (
+                  <span className="mt-1 block text-sm text-gray-600 dark:text-gray-400">
+                    {page.description}
+                  </span>
+                )}
+              </Link>
+            </li>
+          ))}
+        </ul>
+      </div>
+    );
+  }
+
+  const tags = getTags();
+
+  return (
+    <div className="mx-auto max-w-3xl px-6 py-10">
+      <h1 className="text-2xl font-semibold text-gray-900 dark:text-gray-100">Tags</h1>
+
+      {tags.length === 0 ? (
+        <p className="mt-4 text-sm text-gray-600 dark:text-gray-400">
+          No tags yet. Add <code>tags</code> to a page&rsquo;s frontmatter and it will appear here.
+        </p>
+      ) : (
+        <>
+          <p className="mt-2 text-sm text-gray-600 dark:text-gray-400">
+            {tags.length} {tags.length === 1 ? 'subject' : 'subjects'} across the wiki.
+          </p>
+
+          <ul className="mt-6 flex flex-wrap gap-2">
+            {tags.map((tag) => (
+              <li key={tag.slug}>
+                <Link
+                  href={`/tags/${encodeURIComponent(tag.slug)}/`}
+                  className="inline-flex items-baseline gap-1.5 rounded-md border border-gray-200 px-3 py-1.5 text-sm text-gray-700 no-underline transition-colors hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:text-gray-300 dark:hover:border-gray-700 dark:hover:bg-gray-800/50"
+                >
+                  {tag.name}
+                  <span className="text-xs text-gray-500 dark:text-gray-400">
+                    {tag.pages.length}
+                  </span>
+                </Link>
+              </li>
+            ))}
+          </ul>
+        </>
+      )}
+    </div>
+  );
+}

package/template/components/layout/MovedPage.tsx

@@ -0,0 +1,45 @@
+import Link from 'next/link';
+import { asset } from '@/lib/basePath';
+
+/**
+ * Stands in for a page that has moved, and sends the reader on.
+ *
+ * A static export has no server to answer with a 301, so the redirect is a
+ * `meta refresh` in the document itself. Search engines treat that as a
+ * permanent move when the delay is zero, and the canonical link says the same
+ * thing again for anything that reads markup rather than following it.
+ *
+ * The visible text is not decoration. A reader whose browser blocks the refresh
+ * — or who arrives with scripting and meta refresh disabled — still needs a way
+ * through, so the link is real and focusable rather than a spinner.
+ *
+ * @param props - Component props
+ * @param props.url - Href of the page that superseded this address
+ * @param props.title - Title of that page
+ */
+export function MovedPage({ url, title }: { url: string; title: string }) {
+  return (
+    <>
+      <meta httpEquiv="refresh" content={`0; url=${asset(url)}`} />
+
+      <div className="mx-auto max-w-lg px-6 py-24 text-center">
+        <p className="text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-400">
+          This page moved
+        </p>
+
+        <h1 className="mt-3 text-2xl font-semibold text-gray-900 dark:text-gray-100">{title}</h1>
+
+        <p className="mt-4 text-sm text-gray-600 dark:text-gray-400">
+          You are being taken there now. If nothing happens, follow the link.
+        </p>
+
+        <Link
+          href={url}
+          className="mt-6 inline-block rounded-md border border-gray-300 px-4 py-2 text-sm font-medium text-gray-900 no-underline transition-colors hover:bg-gray-50 dark:border-gray-700 dark:text-gray-100 dark:hover:bg-gray-800"
+        >
+          Continue to {title}
+        </Link>
+      </div>
+    </>
+  );
+}

package/template/components/layout/PageNavigation.tsx

@@ -0,0 +1,73 @@
+import Link from 'next/link';
+import { ChevronLeft, ChevronRight } from 'lucide-react';
+import type { Adjacent } from '@/lib/navigation/sequence';
+
+/**
+ * Links to the pages either side of this one in reading order.
+ *
+ * A guide is written to be read through, and until now the only way onwards was
+ * back to the sidebar to find where you had got to. The order is the sidebar's
+ * own, flattened, so the two cannot drift apart.
+ *
+ * `rel="prev"` and `rel="next"` say the same thing to a crawler, which is how a
+ * sequence of pages is declared to be one.
+ *
+ * @param props - Component props
+ * @param props.adjacent - Neighbours from `getAdjacentPages()`
+ */
+export function PageNavigation({ adjacent }: { adjacent: Adjacent }) {
+  const { previous, next } = adjacent;
+
+  // The first and last pages have one neighbour; a page outside the sequence
+  // has none, and gets nothing rather than an empty bar.
+  if (!previous && !next) return null;
+
+  return (
+    <nav
+      aria-label="Page navigation"
+      className="mt-12 flex items-stretch gap-4 border-t border-gray-200 pt-6 dark:border-gray-800"
+    >
+      {previous ? (
+        <Link
+          href={previous.url}
+          rel="prev"
+          className="group flex flex-1 items-center gap-3 rounded-lg border border-gray-200 p-4 no-underline transition-colors hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:hover:border-gray-700 dark:hover:bg-gray-800/50"
+        >
+          <ChevronLeft className="h-4 w-4 flex-shrink-0 text-gray-400 transition-transform group-hover:-translate-x-0.5" />
+          <span className="min-w-0">
+            <span className="block text-xs uppercase tracking-wide text-gray-500 dark:text-gray-400">
+              Previous
+            </span>
+            <span className="block truncate text-sm font-medium text-gray-900 dark:text-gray-100">
+              {previous.title}
+            </span>
+          </span>
+        </Link>
+      ) : (
+        // Holds the column so a lone "next" stays on the right, where it is
+        // when there is a pair.
+        <div className="flex-1" />
+      )}
+
+      {next ? (
+        <Link
+          href={next.url}
+          rel="next"
+          className="group flex flex-1 items-center justify-end gap-3 rounded-lg border border-gray-200 p-4 text-right no-underline transition-colors hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:hover:border-gray-700 dark:hover:bg-gray-800/50"
+        >
+          <span className="min-w-0">
+            <span className="block text-xs uppercase tracking-wide text-gray-500 dark:text-gray-400">
+              Next
+            </span>
+            <span className="block truncate text-sm font-medium text-gray-900 dark:text-gray-100">
+              {next.title}
+            </span>
+          </span>
+          <ChevronRight className="h-4 w-4 flex-shrink-0 text-gray-400 transition-transform group-hover:translate-x-0.5" />
+        </Link>
+      ) : (
+        <div className="flex-1" />
+      )}
+    </nav>
+  );
+}

package/template/components/layout/PageTags.tsx

@@ -0,0 +1,32 @@
+import Link from 'next/link';
+import { Tag as TagIcon } from 'lucide-react';
+import type { Tag } from '@/lib/content/tags';
+
+/**
+ * Shows the subjects a page belongs to.
+ *
+ * Placed at the top of the article rather than the foot: knowing what a page is
+ * about is useful before reading it, and it is the one piece of navigation the
+ * sidebar cannot express, since a file sits in exactly one folder.
+ *
+ * @param props - Component props
+ * @param props.tags - Tags on the page, from `getTagsFor()`
+ */
+export function PageTags({ tags }: { tags: Tag[] }) {
+  if (tags.length === 0) return null;
+
+  return (
+    <nav aria-label="Tags" className="mb-6 flex flex-wrap items-center gap-2">
+      <TagIcon className="h-3.5 w-3.5 flex-shrink-0 text-gray-400" aria-hidden="true" />
+      {tags.map((tag) => (
+        <Link
+          key={tag.slug}
+          href={`/tags/${encodeURIComponent(tag.slug)}/`}
+          className="rounded-md bg-gray-100 px-2 py-0.5 text-xs text-gray-700 no-underline transition-colors hover:bg-gray-200 dark:bg-gray-800 dark:text-gray-300 dark:hover:bg-gray-700"
+        >
+          {tag.name}
+        </Link>
+      ))}
+    </nav>
+  );
+}

package/template/components/layout/TabBar.tsx

@@ -210,7 +210,7 @@ export function TabBar() {
               <button
                 onClick={(e) => handleTabClose(e, tab.id)}
                 className={`
-                  flex-shrink-0 w-5 h-5 min-w-[20px] min-h-[20px] flex items-center justify-center rounded hover:bg-gray-200 dark:hover:bg-gray-600
+                  flex-shrink-0 w-5 h-5 min-w-[20px] min-h-[20px] max-md:w-6 max-md:h-6 max-md:min-w-[24px] max-md:min-h-[24px] flex items-center justify-center rounded hover:bg-gray-200 dark:hover:bg-gray-600
                   transition-opacity
                   ${isActive ? 'opacity-100' : 'opacity-0 group-hover:opacity-100'}
                 `}

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

@@ -0,0 +1,76 @@
+import { describe, it, expect } from 'vitest';
+import { getAliasMap, resolveAlias, aliasUrl, resolveAliasUrl } from './aliases';
+import { getContentRegistry } from './registry';
+
+describe('alias parsing', () => {
+  // An author moving one page writes one path; requiring a list would be a
+  // rule to remember for no gain.
+  it('accepts a single alias or a list', () => {
+    const { docs } = getContentRegistry();
+
+    for (const doc of docs) {
+      expect(Array.isArray(doc.aliases)).toBe(true);
+    }
+  });
+
+  it('leaves documents without aliases empty', () => {
+    const { byPath } = getContentRegistry();
+
+    expect(byPath.get('intro')?.aliases).toEqual([]);
+  });
+});
+
+describe('getAliasMap', () => {
+  it('maps a former path to the document that superseded it', () => {
+    const map = getAliasMap();
+
+    for (const [alias, target] of map) {
+      expect(alias).not.toBe(target);
+      expect(getContentRegistry().byPath.has(target)).toBe(true);
+    }
+  });
+
+  // An alias shadowing a live page would make that page unreachable, so it is
+  // a build error rather than something resolved by precedence.
+  it('never claims a path a page occupies', () => {
+    const { byPath } = getContentRegistry();
+
+    for (const alias of getAliasMap().keys()) {
+      expect(byPath.has(alias)).toBe(false);
+    }
+  });
+});
+
+describe('aliasUrl', () => {
+  it('is the path itself under the path strategy', () => {
+    expect(aliasUrl('guides/setup', 'path')).toBe('guides/setup');
+  });
+
+  // The old URL under `hash` was the digest of the old path, so reproducing it
+  // is what makes the address a reader still has keep working.
+  it('is the digest of the path under the hash strategy', () => {
+    const url = aliasUrl('guides/setup', 'hash');
+
+    expect(url).toMatch(/^[0-9a-f]{8}-[0-9a-f]{8}-[0-9a-f]{8}$/);
+    expect(aliasUrl('guides/setup', 'hash')).toBe(url);
+    expect(aliasUrl('guides/other', 'hash')).not.toBe(url);
+  });
+
+  it('tolerates surrounding slashes', () => {
+    expect(aliasUrl('/guides/setup/', 'path')).toBe('guides/setup');
+  });
+});
+
+describe('resolveAliasUrl', () => {
+  it('resolves a former URL back to the current document under both strategies', () => {
+    for (const [alias, target] of getAliasMap()) {
+      expect(resolveAliasUrl(aliasUrl(alias, 'path'), 'path')).toBe(target);
+      expect(resolveAliasUrl(aliasUrl(alias, 'hash'), 'hash')).toBe(target);
+    }
+  });
+
+  it('resolves nothing for an address no page ever had', () => {
+    expect(resolveAliasUrl('never/existed', 'path')).toBeNull();
+    expect(resolveAlias('never/existed')).toBeNull();
+  });
+});

package/template/lib/content/aliases.ts

@@ -0,0 +1,114 @@
+import { getContentRegistry } from './registry';
+import { cached } from '../cache';
+import { normalizeSlug, type UrlStrategy } from '../navigation/url';
+import { generatePathHash } from '../navigation/hash';
+
+/**
+ * Former locations of documents, and where they now live.
+ *
+ * URLs are derived from content paths, so moving `guides/setup.md` to
+ * `getting-started/setup.md` changes the published URL and every link, bookmark
+ * and search result pointing at the old one stops working. Wiki links survive
+ * the move — they resolve by name — but nothing arriving from outside does.
+ * Declaring the old path in frontmatter keeps it answering.
+ *
+ * Server-only: reads the content registry.
+ */
+
+/** Alias content path mapped to the document that superseded it. */
+export type AliasMap = Map<string, string>;
+
+let memo: AliasMap | null = null;
+
+/**
+ * Builds the alias index.
+ *
+ * Two kinds of clash are refused rather than resolved. An alias naming a real
+ * page would shadow it, making a live document unreachable; an alias claimed by
+ * two documents has no answer, and picking either would send readers somewhere
+ * arbitrary. Both are mistakes in the content, and both are cheaper to find at
+ * build time than as a wrong page in production.
+ *
+ * @returns Old path to current path
+ * @throws Error when an alias shadows a page or is claimed twice
+ *
+ * @example
+ * ```typescript
+ * getAliasMap().get('guides/setup'); // 'getting-started/setup'
+ * ```
+ */
+export function getAliasMap(): AliasMap {
+  const hit = cached(memo);
+  if (hit) return hit;
+
+  const { docs, byPath } = getContentRegistry();
+  const map: AliasMap = new Map();
+
+  for (const doc of docs) {
+    for (const alias of doc.aliases) {
+      if (byPath.has(alias)) {
+        throw new Error(
+          `Alias collision: '${alias}' in content/${doc.path}.md is also a page ` +
+            `(content/${alias}.md). An alias may only name a path no page occupies.`,
+        );
+      }
+
+      const claimed = map.get(alias);
+      if (claimed && claimed !== doc.path) {
+        throw new Error(
+          `Alias collision: '${alias}' is claimed by both content/${claimed}.md ` +
+            `and content/${doc.path}.md. Remove it from one of them.`,
+        );
+      }
+
+      map.set(alias, doc.path);
+    }
+  }
+
+  memo = map;
+  return memo;
+}
+
+/**
+ * Finds the document an old path now points to.
+ *
+ * @param path - Content path as it used to be written
+ * @returns The current content path, or null when nothing claims it
+ */
+export function resolveAlias(path: string): string | null {
+  return getAliasMap().get(path) ?? null;
+}
+
+/**
+ * The URL segment an alias answers on.
+ *
+ * Built with the same rule the live map uses, so the address a reader has
+ * really is the one that is served: under `path` the old content path, under
+ * `hash` the digest of it, which is exactly what the old URL was before the
+ * page moved.
+ *
+ * @param alias - Alias content path
+ * @param strategy - URL strategy in force
+ * @returns The segment, without leading or trailing slashes
+ */
+export function aliasUrl(alias: string, strategy: UrlStrategy): string {
+  const normalized = normalizeSlug(alias);
+  return strategy === 'hash' ? generatePathHash(normalized) : normalized;
+}
+
+/**
+ * Resolves a URL segment to the document that superseded it.
+ *
+ * @param url - URL segment as requested
+ * @param strategy - URL strategy in force
+ * @returns The current content path, or null when the segment is not an alias
+ */
+export function resolveAliasUrl(url: string, strategy: UrlStrategy): string | null {
+  const wanted = normalizeSlug(url);
+
+  for (const [alias, target] of getAliasMap()) {
+    if (aliasUrl(alias, strategy) === wanted) return target;
+  }
+
+  return null;
+}