@softure-ai/blog 0.1.6 → 0.1.8

package/src/db/articles.ts

@@ -1,10 +1,11 @@
-// The article store (FIRE_TRACKER `src/db/blog.ts`): the one write, `publishArticle`, called by the
-// publish run, and the reads the blog pages use. Withdrawing is the same write with the status
-// `withdrawn`; rows are never deleted, because a withdrawn address answers 410, not 404.
+// The article store: the one write, `publishArticle`, called by the publish run, and the reads the
+// blog pages use. Withdrawing is the same write with the status `withdrawn`; rows are never deleted,
+// because a withdrawn address answers 410, not 404.
 import type { ModuleContext } from "@softure-ai/core";
 import type { Queryable } from "@softure-ai/db";
-import { and, asc, desc, eq, ne, type SQL } from "drizzle-orm";
+import { and, asc, desc, eq, ne, sql, type SQL } from "drizzle-orm";
 import type { BlogArticle, BlogArticleInput, BlogArticleKind, BlogArticleState, BlogPublishResult } from "../contract.js";
+import type { ArticleHistory } from "./history.js";
 import { articles, slugHistory } from "./schema.js";
 
 export type BlogContext = ModuleContext<Queryable>;
@@ -18,10 +19,14 @@ export type BlogContext = ModuleContext<Queryable>;
  *   text first becomes `published`. A draft gets none.
  * - `updated_at` moves only when the content hash of a text that already has `published_at` changes.
  *
+ * With `history` (an app moving its blog in, see history.ts), an article that has no row yet takes its
+ * `published_at` (unless the file sets one) and `updated_at` from it, and its old slugs enter the slug
+ * history; the result says `imported: true`. For an existing row the history is ignored.
+ *
  * Runs in a transaction that locks the row (`FOR UPDATE`), so two publishes of one article never
  * overwrite each other silently; inside an open transaction it becomes a savepoint.
  */
-export async function publishArticle(ctx: BlogContext, input: BlogArticleInput): Promise<BlogPublishResult> {
+export async function publishArticle(ctx: BlogContext, input: BlogArticleInput, options: PublishArticleOptions = {}): Promise<BlogPublishResult> {
   return ctx.db.transaction(async (tx) => {
     const [existing] = await tx.select().from(articles).where(eq(articles.id, input.id)).for("update");
 
@@ -61,12 +66,25 @@ export async function publishArticle(ctx: BlogContext, input: BlogArticleInput):
     };
 
     if (existing === undefined) {
-      const publishedAt = input.publishedAt ?? (input.status === "published" ? now : null);
+      const history = options.history;
+      const publishedAt = input.publishedAt ?? history?.publishedAt ?? (input.status === "published" ? now : null);
+      const updatedAt = publishedAt === null ? null : (history?.updatedAt ?? null);
+      if (history !== undefined) {
+        const taken = await findTakenOldSlug(tx, input, history);
+        if (taken !== null) return taken;
+      }
       const [inserted] = await tx
         .insert(articles)
-        .values({ id: input.id, ...content, publishedAt, updatedAt: null, createdAt: now })
+        .values({ id: input.id, ...content, publishedAt: toTimestamp(publishedAt), updatedAt: toTimestamp(updatedAt), createdAt: now })
         .returning();
-      return { ok: true, action: "added", before: null, after: readState(requireRow(inserted, input.id)), previousSlug: null };
+      const oldSlugs = history?.oldSlugs.filter((old) => old.slug !== input.slug) ?? [];
+      if (oldSlugs.length > 0) {
+        await tx.insert(slugHistory).values(oldSlugs.map((old) => ({ oldSlug: old.slug, articleId: input.id, changedAt: toTimestamp(old.changedAt) ?? now })));
+      }
+      const after = readState(requireRow(inserted, input.id));
+      return history === undefined
+        ? { ok: true, action: "added", before: null, after, previousSlug: null }
+        : { ok: true, action: "added", before: null, after, previousSlug: null, imported: true };
     }
 
     const before = readState(existing);
@@ -103,6 +121,28 @@ export async function publishArticle(ctx: BlogContext, input: BlogArticleInput):
   });
 }
 
+/** A history timestamp goes in as text, so Postgres keeps its microseconds; a `Date` goes in as is. */
+function toTimestamp(value: Date | string | null): Date | SQL | null {
+  return typeof value === "string" ? sql`${value}::timestamptz` : value;
+}
+
+export interface PublishArticleOptions {
+  /** The article's earlier life, applied only when it has no row yet. */
+  readonly history?: ArticleHistory;
+}
+
+/** The refusal for the first old slug of `history` another article holds, current or old; `null` when all are free. */
+async function findTakenOldSlug(db: Queryable, input: BlogArticleInput, history: ArticleHistory): Promise<Extract<BlogPublishResult, { ok: false }> | null> {
+  for (const { slug } of history.oldSlugs) {
+    if (slug === input.slug) continue;
+    const [owner] = await db.select({ id: articles.id }).from(articles).where(and(eq(articles.slug, slug), ne(articles.id, input.id)));
+    if (owner !== undefined) return { ok: false, error: "blog.slug_taken", otherArticleId: owner.id, slug };
+    const [historyOwner] = await db.select({ articleId: slugHistory.articleId }).from(slugHistory).where(eq(slugHistory.oldSlug, slug));
+    if (historyOwner !== undefined) return { ok: false, error: "blog.slug_in_history", otherArticleId: historyOwner.articleId, slug };
+  }
+  return null;
+}
+
 /** The article under its current slug, in any status: a page tells 200 from 410 by it. */
 export async function findArticleBySlug(ctx: BlogContext, slug: string): Promise<BlogArticle | null> {
   const [row] = await ctx.db.select().from(articles).where(eq(articles.slug, slug));

package/src/db/history.ts

@@ -0,0 +1,90 @@
+// The history of articles an app published before it moved to this module: when each text first went
+// public, when it last changed, and the slugs it had before. A first publish into `blog.*` would
+// otherwise date every text today and lose the old addresses' 301s.
+//
+// The app exports it once from its own tables as JSON (README, "Moving an existing blog") and passes it
+// to `softure-blog publish --history <file>`. It applies only to an article that has no row yet, so a
+// re-run with the same file changes nothing, and the article file's own `published_at` still wins.
+//
+// Timestamps stay the text they were given and go into Postgres as text, so `…:12.421579Z` (what a
+// `timestamptz` holds) is stored to the microsecond; a `Date` would keep only milliseconds. Digits past
+// the sixth are rounded by Postgres.
+import { z } from "zod";
+
+const SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+const timestamp = z.iso.datetime({
+  offset: true,
+  error: (issue) =>
+    issue.input === undefined
+      ? "is required: an ISO 8601 timestamp, or null for a text that was never published"
+      : "must be an ISO 8601 timestamp with a time zone, e.g. 2026-09-01T08:00:00Z",
+});
+
+const oldSlugSchema = z.strictObject({
+  slug: z.string().max(100).regex(SLUG, "must be a kebab-case slug"),
+  changed_at: timestamp.optional(),
+});
+
+const entrySchema = z
+  .strictObject({
+    id: z.string().max(100).regex(SLUG, "must be a kebab-case article id"),
+    published_at: timestamp.nullable(),
+    updated_at: timestamp.nullable().optional(),
+    old_slugs: z.array(oldSlugSchema).default([]),
+  })
+  .refine((entry) => entry.updated_at === undefined || entry.updated_at === null || entry.published_at !== null, {
+    message: "updated_at needs published_at: a text is updated only after it was published",
+    path: ["updated_at"],
+  });
+
+export const articleHistorySchema = z
+  .strictObject({ articles: z.array(entrySchema) })
+  .superRefine((history, context) => {
+    const ids = new Set<string>();
+    const slugs = new Set<string>();
+    history.articles.forEach((entry, index) => {
+      if (ids.has(entry.id)) context.addIssue({ code: "custom", path: ["articles", index, "id"], message: `"${entry.id}" is listed twice` });
+      ids.add(entry.id);
+      entry.old_slugs.forEach((old, slugIndex) => {
+        if (slugs.has(old.slug)) context.addIssue({ code: "custom", path: ["articles", index, "old_slugs", slugIndex, "slug"], message: `"${old.slug}" is an old slug twice` });
+        slugs.add(old.slug);
+      });
+    });
+  });
+
+/**
+ * What the module keeps from an article's earlier life. Timestamps are ISO 8601 text with a time zone,
+ * as the history gives them, so their full precision reaches the database.
+ */
+export interface ArticleHistory {
+  readonly publishedAt: string | null;
+  /** Kept only with `publishedAt`. */
+  readonly updatedAt: string | null;
+  readonly oldSlugs: readonly { readonly slug: string; readonly changedAt: string | null }[];
+}
+
+/** History by article id. */
+export type ArticleHistoryMap = ReadonlyMap<string, ArticleHistory>;
+
+/** The parsed history, or the problems that name the field (`articles.3.published_at: …`). */
+export function parseArticleHistory(input: unknown): { readonly ok: true; readonly history: ArticleHistoryMap } | { readonly ok: false; readonly errors: readonly string[] } {
+  const parsed = articleHistorySchema.safeParse(input);
+  if (!parsed.success) {
+    return { ok: false, errors: parsed.error.issues.map((issue) => `${issue.path.join(".") || "history"}: ${issue.message}`) };
+  }
+  const orNull = (value: string | null | undefined) => value ?? null;
+  return {
+    ok: true,
+    history: new Map(
+      parsed.data.articles.map((entry) => [
+        entry.id,
+        {
+          publishedAt: orNull(entry.published_at),
+          updatedAt: orNull(entry.updated_at),
+          oldSlugs: entry.old_slugs.map((old) => ({ slug: old.slug, changedAt: orNull(old.changed_at) })),
+        },
+      ]),
+    ),
+  };
+}

package/src/db/publish-run.ts

@@ -12,6 +12,7 @@ import type { Queryable } from "@softure-ai/db";
 import { eq } from "drizzle-orm";
 import { findTermFormConflicts, toGlossary } from "../render/glossary.js";
 import { listArticles, publishArticle, type BlogContext } from "./articles.js";
+import type { ArticleHistory, ArticleHistoryMap } from "./history.js";
 import { articles } from "./schema.js";
 
 export interface ArticleFile {
@@ -33,6 +34,11 @@ export interface RunBlogPublishOptions extends ParseArticleFileOptions {
   /** Publish the files as `withdrawn`, whatever their status (taking a text down at once). */
   readonly withdraw?: boolean;
   readonly gate?: PublishGate;
+  /**
+   * The earlier life of articles an app moves in (history.ts), by id: applied to an article of the run
+   * that has no row yet. An entry for an id outside the run is a warning.
+   */
+  readonly history?: ArticleHistoryMap;
 }
 
 /** A problem that stops the run; `subject` is a file name, an article id or a cluster. */
@@ -52,6 +58,11 @@ export interface PublishedChange {
   readonly slug: string;
   /** The slug that entered the slug history in this run. */
   readonly previousSlug: string | null;
+  /** Set when the run applied the article's history (`history`): its dates and old slugs. */
+  readonly imported?: {
+    readonly publishedAt: Date | null;
+    readonly oldSlugs: number;
+  };
 }
 
 export type BlogPublishRun =
@@ -100,15 +111,21 @@ export async function runBlogPublish(ctx: BlogContext, files: readonly ArticleFi
 
   problems.push(...findDuplicateIds(inputs), ...findPillarProblems(inputs));
   if (problems.length > 0) return { status: "refused", problems, warnings };
+  const runIds = new Set(inputs.map((input) => input.id));
+  for (const id of options.history?.keys() ?? []) {
+    if (!runIds.has(id)) warnings.push({ subject: id, message: "the history names an article that is not in this run; it is applied when its file is published" });
+  }
 
   const changes: PublishedChange[] = [];
   try {
     await ctx.db.transaction(async (tx) => {
       for (const input of inputs) {
-        const result = await publishArticleOrRefuse({ ...ctx, db: tx }, input);
+        const history = options.history?.get(input.id);
+        const result = await publishArticleOrRefuse({ ...ctx, db: tx }, input, history);
         if (!result.ok) {
           const reason = result.error === "blog.slug_taken" ? "is the slug of" : "redirects to";
-          throw new PublishRefused([{ subject: input.id, message: `slug ${input.slug} ${reason} article ${result.otherArticleId} (${result.error})` }]);
+          const slug = result.slug === undefined ? `slug ${input.slug}` : `old slug ${result.slug} (history)`;
+          throw new PublishRefused([{ subject: input.id, message: `${slug} ${reason} article ${result.otherArticleId} (${result.error})` }]);
         }
         changes.push({
           id: input.id,
@@ -119,6 +136,9 @@ export async function runBlogPublish(ctx: BlogContext, files: readonly ArticleFi
           slugBefore: result.before?.slug ?? null,
           slug: result.after.slug,
           previousSlug: result.previousSlug,
+          ...(result.imported === true && history !== undefined
+            ? { imported: { publishedAt: result.after.publishedAt, oldSlugs: history.oldSlugs.filter((old) => old.slug !== input.slug).length } }
+            : {}),
         });
       }
       const glossary = await checkGlossaryForms({ ...ctx, db: tx }, inputs);
@@ -192,9 +212,9 @@ async function checkGlossaryForms(ctx: BlogContext, inputs: readonly BlogArticle
  * for that run and fail with 23505. The savepoint is rolled back, so the transaction still reads
  * (at read committed, the winner's row is visible now) and names the article that took the slug.
  */
-async function publishArticleOrRefuse(ctx: BlogContext, input: BlogArticleInput): ReturnType<typeof publishArticle> {
+async function publishArticleOrRefuse(ctx: BlogContext, input: BlogArticleInput, history: ArticleHistory | undefined): ReturnType<typeof publishArticle> {
   try {
-    return await publishArticle(ctx, input);
+    return await publishArticle(ctx, input, history === undefined ? {} : { history });
   } catch (error) {
     const driverError = findDriverError(error);
     if (driverError?.code !== UNIQUE_VIOLATION || driverError.constraint !== SLUG_CONSTRAINT) throw error;

package/src/index.ts

@@ -29,7 +29,7 @@ export const BLOG_RATE_LIMIT_BUCKETS = {
 export const blog = defineModule({
   manifest: {
     id: MODULE_ID,
-    version: "0.1.6",
+    version: "0.1.8",
     // seo is optional: with it the sitemap lists the texts and a publish pings IndexNow. security is
     // optional too: only the cache refresh route needs it, for its rate limit.
     dependsOn: { seo: "^0.1.0?", security: "^0.1.0?" },

package/src/next/index.ts

@@ -2,6 +2,15 @@
 // feed, the cache refresh route and the cached reads (docs/02-module-standard.md §8).
 export { getBlogContext, getPageContext } from "./context.js";
 export { serveBlogRss } from "./discovery.js";
+export { buildArticleJsonLd, buildGlossaryJsonLd, buildTermJsonLd, getCrumbLabels } from "./json-ld.js";
+export {
+  buildArticleMetadata,
+  buildBlogIndexMetadata,
+  buildGlossaryIndexMetadata,
+  buildMethodMetadata,
+  buildTermMetadata,
+  type ListingMetadataInput,
+} from "./metadata.js";
 export { refreshBlogCache } from "./refresh.js";
 export { BLOG_CACHE_TAG, getPublishedArticles, getPublishedTerms, getTextBySlug } from "./data.js";
 export { createOgFontLoader, loadBrandOgFonts, type OgFontLoaderOptions, type OgFontsResult } from "./og-fonts.js";

package/src/next/json-ld.ts

@@ -0,0 +1,47 @@
+// The structured data of the blog's pages, ready for `<script type="application/ld+json">`: built from
+// what the caller already holds (no database read, no request scope) and serialized so no text can
+// close the tag. The ready-made pages use these; an app with its own page components mounts them as
+//
+//   <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: buildArticleJsonLd(config, article) }} />
+import { getSiteUrls, type SoftureConfig } from "@softure-ai/core";
+import type { BlogArticle } from "../contract.js";
+import { getArticleJsonLd, getGlossaryJsonLd, getTermJsonLd, serializeJsonLd, type JsonLdContext } from "../pages/json-ld.js";
+import { getArticleCrumbs, getClusterLabel, getTermCrumbs, sortTerms, type CrumbLabels } from "../pages/listing.js";
+import { getBlogOptions } from "../server/options.js";
+import type { BlogPageContext } from "../ui/page-context.js";
+import { getPageContext } from "./context.js";
+
+/** The breadcrumb names the pages show: the blog, the glossary and the clusters' display names. */
+export function getCrumbLabels(config: SoftureConfig, context: BlogPageContext = getPageContext(config)): CrumbLabels {
+  const clusters = getBlogOptions(config).clusters;
+  return {
+    blog: context.messages.pages.blogTitle,
+    glossary: context.messages.glossary.title,
+    cluster: (cluster) => getClusterLabel(cluster, clusters, config.locale),
+  };
+}
+
+function getJsonLdContext(config: SoftureConfig, context: BlogPageContext): JsonLdContext {
+  return { urls: getSiteUrls(config), routes: context.routes, locale: config.locale, timezone: config.timezone, brand: context.brand };
+}
+
+/** An article's `BlogPosting`, breadcrumbs and FAQ, serialized. */
+export function buildArticleJsonLd(config: SoftureConfig, article: BlogArticle): string {
+  const context = getPageContext(config);
+  const crumbs = getArticleCrumbs(article, context.routes, getCrumbLabels(config, context));
+  return serializeJsonLd(getArticleJsonLd(article, crumbs, getJsonLdContext(config, context)));
+}
+
+/** A glossary term's `DefinedTerm` and breadcrumbs, serialized. */
+export function buildTermJsonLd(config: SoftureConfig, term: BlogArticle): string {
+  const context = getPageContext(config);
+  const crumbs = getTermCrumbs(term, context.routes, getCrumbLabels(config, context));
+  return serializeJsonLd(getTermJsonLd(term, crumbs, getJsonLdContext(config, context), context.messages.glossary.title));
+}
+
+/** The glossary's `DefinedTermSet` over the published terms, in the index's order, serialized; `null` without terms. */
+export function buildGlossaryJsonLd(config: SoftureConfig, terms: readonly BlogArticle[]): string | null {
+  if (terms.length === 0) return null;
+  const context = getPageContext(config);
+  return serializeJsonLd(getGlossaryJsonLd(sortTerms(terms, config.locale), getJsonLdContext(config, context), context.messages.glossary.title));
+}

package/src/next/metadata.ts

@@ -0,0 +1,103 @@
+// The metadata of the blog's pages (`<title>`, description, robots, canonical, feed link, Open Graph),
+// built from what the caller already holds: no database read, no request scope. The ready-made pages'
+// `generate*Metadata` read the text and call these; an app with its own page components calls them
+// with the text it read, and can extend the result:
+//
+//   export async function generateMetadata({ params }) {
+//     const config = getSoftureConfig();
+//     const article = await getTextBySlug(config, (await params).slug);
+//     if (article?.status !== "published" || article.kind !== "article") return {};
+//     return { ...buildArticleMetadata(config, article), keywords: [...] };
+//   }
+import { formatMessage, getSiteUrls, type SoftureConfig } from "@softure-ai/core";
+// `next/types.js`, not `next`: the root entry adds Next's globals (a read-only NODE_ENV) to every
+// program that includes this file.
+import type { Metadata } from "next/types.js";
+import type { BlogArticle } from "../contract.js";
+import { getArticleDates } from "../pages/dates.js";
+import { getArticlePath, getTermPath } from "../pages/paths.js";
+import type { BlogPageContext } from "../ui/page-context.js";
+import { getPageContext } from "./context.js";
+
+/** Whether a listing has no entry: an empty listing stays out of the index (thin content). */
+export interface ListingMetadataInput {
+  readonly isEmpty: boolean;
+}
+
+function withBrand(title: string, context: BlogPageContext): string {
+  return context.brand === null ? title : formatMessage(context.messages.pages.titleWithBrand, { title, brand: context.brand });
+}
+
+/** A page's canonical URL: seo's host and trailing-slash rule when the app lists seo, else on `appOrigin`. */
+function getCanonicalUrl(config: SoftureConfig, path: string): string {
+  return getSiteUrls(config).getCanonicalUrl(path);
+}
+
+/** The feed link a reader finds in `<head>` (`<link rel="alternate" type="application/rss+xml">`); a file, so no trailing-slash rule. */
+function getFeedAlternates(config: SoftureConfig, context: BlogPageContext): NonNullable<Metadata["alternates"]>["types"] {
+  return { "application/rss+xml": [{ url: `${getSiteUrls(config).origin}${context.routes.rss}`, title: withBrand(context.messages.pages.blogTitle, context) }] };
+}
+
+function getStaticMetadata(config: SoftureConfig, context: BlogPageContext, page: { title: string; description: string; path: string; isEmpty?: boolean; hasFeed?: boolean }): Metadata {
+  return {
+    title: withBrand(page.title, context),
+    description: page.description,
+    robots: { index: page.isEmpty !== true, follow: true },
+    alternates: { canonical: getCanonicalUrl(config, page.path), ...(page.hasFeed === true ? { types: getFeedAlternates(config, context) } : {}) },
+    openGraph: { type: "website", title: page.title, description: page.description, url: getCanonicalUrl(config, page.path), ...(context.brand === null ? {} : { siteName: context.brand }) },
+  };
+}
+
+function getTextMetadata(config: SoftureConfig, context: BlogPageContext, text: BlogArticle, path: string, options: { hasFeed?: boolean } = {}): Metadata {
+  const dates = getArticleDates(text, config.timezone);
+  const url = getCanonicalUrl(config, path);
+  return {
+    title: withBrand(text.title, context),
+    description: text.description,
+    robots: { index: true, follow: true },
+    alternates: { canonical: url, ...(options.hasFeed === true ? { types: getFeedAlternates(config, context) } : {}) },
+    openGraph: {
+      type: "article",
+      title: text.title,
+      description: text.description,
+      url,
+      locale: config.locale,
+      publishedTime: dates.published,
+      modifiedTime: dates.updated ?? dates.published,
+      ...(context.brand === null ? {} : { siteName: context.brand }),
+    },
+  };
+}
+
+/** The listing's metadata, with the feed link. */
+export function buildBlogIndexMetadata(config: SoftureConfig, { isEmpty }: ListingMetadataInput): Metadata {
+  const context = getPageContext(config);
+  const copy = context.messages.pages;
+  return getStaticMetadata(config, context, { title: copy.blogTitle, description: copy.blogDescription, path: context.routes.index, isEmpty, hasFeed: true });
+}
+
+/** An article's metadata, with the feed link. The caller checks the text is a published article. */
+export function buildArticleMetadata(config: SoftureConfig, article: BlogArticle): Metadata {
+  const context = getPageContext(config);
+  return getTextMetadata(config, context, article, getArticlePath(context.routes, article.slug), { hasFeed: true });
+}
+
+/** The glossary index's metadata. */
+export function buildGlossaryIndexMetadata(config: SoftureConfig, { isEmpty }: ListingMetadataInput): Metadata {
+  const context = getPageContext(config);
+  const copy = context.messages.glossary;
+  return getStaticMetadata(config, context, { title: copy.title, description: copy.description, path: context.routes.glossary, isEmpty });
+}
+
+/** A glossary term's metadata. The caller checks the text is a published term. */
+export function buildTermMetadata(config: SoftureConfig, term: BlogArticle): Metadata {
+  const context = getPageContext(config);
+  return getTextMetadata(config, context, term, getTermPath(context.routes, term.slug));
+}
+
+/** The method page's metadata. */
+export function buildMethodMetadata(config: SoftureConfig): Metadata {
+  const context = getPageContext(config);
+  const copy = context.messages.method;
+  return getStaticMetadata(config, context, { title: copy.title, description: copy.description, path: context.routes.method });
+}

package/src/next/pages.tsx

@@ -14,7 +14,11 @@
 // articles and terms render on their first request and are kept for `revalidate` seconds (ISR).
 // 301 and 410 are answered before the page by `@softure-ai/blog/proxy`; anything else that is not a
 // published text of the page's kind is a 404 here.
-import { formatMessage, getSiteUrls, type SoftureConfig } from "@softure-ai/core";
+//
+// An app with its own page components keeps the rest: `generate*Metadata` and `BlogArticleOgImage`
+// mount next to its own page, and `build*Metadata` (metadata.ts) and `build*JsonLd` (json-ld.ts) take
+// a text it already read.
+import { getSiteUrls, type SoftureConfig } from "@softure-ai/core";
 import { getSoftureConfig } from "@softure-ai/core/next";
 // `next/types.js`, not `next`: the root entry adds Next's globals (a read-only NODE_ENV) to every
 // program that includes this file.
@@ -25,9 +29,7 @@ import type { BlogArticle } from "../contract.js";
 import { getRelatedArticles } from "../discovery/related.js";
 import { findArticlesLinkingTerm, renderPageBody, type RenderPageBodyOptions } from "../pages/body.js";
 import { getArticleDates } from "../pages/dates.js";
-import { getArticleJsonLd, getGlossaryJsonLd, getTermJsonLd, serializeJsonLd, type JsonLdContext } from "../pages/json-ld.js";
-import { getArticleCrumbs, getClusterLabel, getTermCrumbs, groupByCluster, sortTerms, type CrumbLabels } from "../pages/listing.js";
-import { getArticlePath, getTermPath } from "../pages/paths.js";
+import { getArticleCrumbs, groupByCluster, getTermCrumbs, sortTerms } from "../pages/listing.js";
 import { toGlossary } from "../render/glossary.js";
 import { getBlogOptions } from "../server/options.js";
 import { BlogArticleView } from "../ui/blog-article.js";
@@ -37,6 +39,8 @@ import { BlogMethodView } from "../ui/blog-method.js";
 import type { BlogPageContext } from "../ui/page-context.js";
 import { getPageContext } from "./context.js";
 import { getPublishedArticles, getPublishedTerms, getTextBySlug } from "./data.js";
+import { buildArticleJsonLd, buildGlossaryJsonLd, buildTermJsonLd, getCrumbLabels } from "./json-ld.js";
+import { buildArticleMetadata, buildBlogIndexMetadata, buildGlossaryIndexMetadata, buildMethodMetadata, buildTermMetadata } from "./metadata.js";
 
 type SlugParams = Promise<{ readonly slug: string }>;
 
@@ -67,76 +71,15 @@ function isPublished(text: BlogArticle | null, kind: BlogArticle["kind"]): text
   return text !== null && text.status === "published" && text.kind === kind;
 }
 
-function getCrumbLabels(config: SoftureConfig, context: BlogPageContext): CrumbLabels {
-  const clusters = getBlogOptions(config).clusters;
-  return {
-    blog: context.messages.pages.blogTitle,
-    glossary: context.messages.glossary.title,
-    cluster: (cluster) => getClusterLabel(cluster, clusters, config.locale),
-  };
-}
-
-function getJsonLdContext(config: SoftureConfig, context: BlogPageContext): JsonLdContext {
-  return { urls: getSiteUrls(config), routes: context.routes, locale: config.locale, timezone: config.timezone, brand: context.brand };
-}
-
 function getBodyOptions(config: SoftureConfig, context: BlogPageContext, terms: readonly BlogArticle[]): RenderPageBodyOptions {
   const origins = [config.appOrigin, getSiteUrls(config).origin];
   return { glossary: toGlossary(terms), routes: context.routes, options: getBlogOptions(config), origins, messages: context.messages };
 }
 
-function withBrand(title: string, context: BlogPageContext): string {
-  return context.brand === null ? title : formatMessage(context.messages.pages.titleWithBrand, { title, brand: context.brand });
-}
-
-/** A page's canonical URL: seo's host and trailing-slash rule when the app lists seo, else on `appOrigin`. */
-function getCanonicalUrl(config: SoftureConfig, path: string): string {
-  return getSiteUrls(config).getCanonicalUrl(path);
-}
-
-/** The feed link a reader finds in `<head>` (`<link rel="alternate" type="application/rss+xml">`); a file, so no trailing-slash rule. */
-function getFeedAlternates(config: SoftureConfig, context: BlogPageContext): NonNullable<Metadata["alternates"]>["types"] {
-  return { "application/rss+xml": [{ url: `${getSiteUrls(config).origin}${context.routes.rss}`, title: withBrand(context.messages.pages.blogTitle, context) }] };
-}
-
-/** Metadata of a page with a fixed path; an empty listing stays out of the index (thin content). */
-function getStaticMetadata(config: SoftureConfig, context: BlogPageContext, page: { title: string; description: string; path: string; isEmpty?: boolean; hasFeed?: boolean }): Metadata {
-  return {
-    title: withBrand(page.title, context),
-    description: page.description,
-    robots: { index: page.isEmpty !== true, follow: true },
-    alternates: { canonical: getCanonicalUrl(config, page.path), ...(page.hasFeed === true ? { types: getFeedAlternates(config, context) } : {}) },
-    openGraph: { type: "website", title: page.title, description: page.description, url: getCanonicalUrl(config, page.path), ...(context.brand === null ? {} : { siteName: context.brand }) },
-  };
-}
-
-function getTextMetadata(config: SoftureConfig, context: BlogPageContext, text: BlogArticle, path: string, options: { hasFeed?: boolean } = {}): Metadata {
-  const dates = getArticleDates(text, config.timezone);
-  const url = getCanonicalUrl(config, path);
-  return {
-    title: withBrand(text.title, context),
-    description: text.description,
-    robots: { index: true, follow: true },
-    alternates: { canonical: url, ...(options.hasFeed === true ? { types: getFeedAlternates(config, context) } : {}) },
-    openGraph: {
-      type: "article",
-      title: text.title,
-      description: text.description,
-      url,
-      locale: config.locale,
-      publishedTime: dates.published,
-      modifiedTime: dates.updated ?? dates.published,
-      ...(context.brand === null ? {} : { siteName: context.brand }),
-    },
-  };
-}
-
 export async function generateBlogIndexMetadata(): Promise<Metadata> {
   const config = getSoftureConfig();
-  const context = getPageContext(config);
   const articles = await getPublishedArticles(config);
-  const copy = context.messages.pages;
-  return getStaticMetadata(config, context, { title: copy.blogTitle, description: copy.blogDescription, path: context.routes.index, isEmpty: articles.length === 0, hasFeed: true });
+  return buildBlogIndexMetadata(config, { isEmpty: articles.length === 0 });
 }
 
 /** The listing: cards grouped by cluster, the pillar first. Mount with `dynamic = "force-dynamic"`. */
@@ -153,9 +96,7 @@ export async function generateArticleMetadata({ params }: { readonly params: Slu
   const config = getSoftureConfig();
   const { slug } = await params;
   const article = await getTextBySlug(config, slug);
-  if (!isPublished(article, "article")) return {};
-  const context = getPageContext(config);
-  return getTextMetadata(config, context, article, getArticlePath(context.routes, article.slug), { hasFeed: true });
+  return isPublished(article, "article") ? buildArticleMetadata(config, article) : {};
 }
 
 /** An article with "read next" under it. Mount with `revalidate` and `generateBlogStaticParams`. */
@@ -168,7 +109,7 @@ export async function BlogArticlePage({ params, cta, afterArticle }: BlogArticle
   const [terms, published] = await Promise.all([getPublishedTerms(config), getPublishedArticles(config)]);
   const body = renderPageBody<ReactNode>(article, getBodyOptions(config, context, terms));
   const crumbs = getArticleCrumbs(article, context.routes, getCrumbLabels(config, context));
-  const jsonLd = serializeJsonLd(getArticleJsonLd(article, crumbs, getJsonLdContext(config, context)));
+  const jsonLd = buildArticleJsonLd(config, article);
   return (
     <BlogArticleView
       context={context}
@@ -186,10 +127,8 @@ export async function BlogArticlePage({ params, cta, afterArticle }: BlogArticle
 
 export async function generateGlossaryIndexMetadata(): Promise<Metadata> {
   const config = getSoftureConfig();
-  const context = getPageContext(config);
   const terms = await getPublishedTerms(config);
-  const copy = context.messages.glossary;
-  return getStaticMetadata(config, context, { title: copy.title, description: copy.description, path: context.routes.glossary, isEmpty: terms.length === 0 });
+  return buildGlossaryIndexMetadata(config, { isEmpty: terms.length === 0 });
 }
 
 /** The glossary index. Mount with `dynamic = "force-dynamic"`. */
@@ -197,7 +136,7 @@ export async function GlossaryIndexPage() {
   const config = getSoftureConfig();
   const context = getPageContext(config);
   const terms = sortTerms(await getPublishedTerms(config), config.locale);
-  const jsonLd = terms.length === 0 ? null : serializeJsonLd(getGlossaryJsonLd(terms, getJsonLdContext(config, context), context.messages.glossary.title));
+  const jsonLd = buildGlossaryJsonLd(config, terms);
   return <GlossaryIndexView context={context} terms={terms} jsonLd={jsonLd} />;
 }
 
@@ -205,9 +144,7 @@ export async function generateTermMetadata({ params }: { readonly params: SlugPa
   const config = getSoftureConfig();
   const { slug } = await params;
   const term = await getTextBySlug(config, slug);
-  if (!isPublished(term, "term")) return {};
-  const context = getPageContext(config);
-  return getTextMetadata(config, context, term, getTermPath(context.routes, term.slug));
+  return isPublished(term, "term") ? buildTermMetadata(config, term) : {};
 }
 
 /** A glossary term with the articles that expand on it. Mount with `revalidate` and `generateBlogStaticParams`. */
@@ -220,7 +157,7 @@ export async function GlossaryTermPage({ params, cta }: GlossaryTermPageProps) {
   const [terms, articles] = await Promise.all([getPublishedTerms(config), getPublishedArticles(config)]);
   const bodyOptions = getBodyOptions(config, context, terms);
   const crumbs = getTermCrumbs(term, context.routes, getCrumbLabels(config, context));
-  const jsonLd = serializeJsonLd(getTermJsonLd(term, crumbs, getJsonLdContext(config, context), context.messages.glossary.title));
+  const jsonLd = buildTermJsonLd(config, term);
   return (
     <GlossaryTermView
       context={context}
@@ -236,10 +173,7 @@ export async function GlossaryTermPage({ params, cta }: GlossaryTermPageProps) {
 }
 
 export function generateMethodMetadata(): Metadata {
-  const config = getSoftureConfig();
-  const context = getPageContext(config);
-  const copy = context.messages.method;
-  return getStaticMetadata(config, context, { title: copy.title, description: copy.description, path: context.routes.method });
+  return buildMethodMetadata(getSoftureConfig());
 }
 
 /** "How our texts are made". Mount it with `blog({ methodPage: true })`; without that it is a 404. */