@softure-ai/blog 0.1.7 → 0.1.9

package/src/next/json-ld.ts

@@ -0,0 +1,55 @@
+// 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 { getBlogLocaleTags, 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,
+    language: getBlogLocaleTags(config).bcp47,
+    ids: getBlogOptions(config).jsonLd.ids,
+    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), { clusterAnchorPrefix: context.clusterAnchorPrefix });
+  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,105 @@
+// 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 { getBlogLocaleTags } from "../server/options.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;
+}
+
+/** `pattern`: the page kind's title message (`pages.titleWithBrand`, or `glossary.termTitleWithBrand` for a term). */
+function withBrand(title: string, context: BlogPageContext, pattern: string = context.messages.pages.titleWithBrand): string {
+  return context.brand === null ? title : formatMessage(pattern, { 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; titlePattern?: string } = {}): Metadata {
+  const dates = getArticleDates(text, config.timezone);
+  const url = getCanonicalUrl(config, path);
+  return {
+    title: withBrand(text.title, context, options.titlePattern),
+    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: getBlogLocaleTags(config).openGraph,
+      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, titled by `glossary.termTitleWithBrand`. 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), { titlePattern: context.messages.glossary.termTitleWithBrand });
+}
+
+/** 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`. */
@@ -167,8 +108,8 @@ export async function BlogArticlePage({ params, cta, afterArticle }: BlogArticle
   const context = getPageContext(config);
   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 crumbs = getArticleCrumbs(article, context.routes, getCrumbLabels(config, context), { clusterAnchorPrefix: context.clusterAnchorPrefix });
+  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. */

package/src/options.ts

@@ -1,8 +1,9 @@
 // The options an app passes to `blog({ ... })` in softure.config.ts, parsed at startup.
 import { z } from "zod";
 import { qualitySettingSchema } from "./quality/options.js";
+import type { GonePageRenderInput } from "./pages/redirects.js";
 import type { ArticleImagePolicy } from "./render/images.js";
-import type { BlockPlugin } from "./render/render-article.js";
+import { EXTERNAL_LINK_MARKERS, type BlockPlugin } from "./render/render-article.js";
 
 /** Where the app keeps its article files unless a command names a path. */
 export const DEFAULT_CONTENT_DIR = "content/blog";
@@ -162,6 +163,23 @@ const skillSectionSchema = z.strictObject({
     .refine((body) => !hasTopHeading(body), "must not hold a # or ## heading; use ### and deeper (the title is the section's ## heading)"),
 });
 
+/** A 410 link: a path from the site root or an https URL, never another scheme. */
+const goneHrefSchema = z
+  .string()
+  .trim()
+  .refine((href) => (href.startsWith("/") && !href.startsWith("//")) || (href.startsWith("https://") && URL.canParse(href)), "must be a path from the site root or an https URL, e.g. /calculator");
+
+const gonePageSchema = z.strictObject({
+  /** Further ways on, listed under the link to the listing. */
+  links: z.array(z.strictObject({ href: goneHrefSchema, label: localizedTextSchema })).max(5).default([]),
+  /**
+   * `(input) => html`: the whole body of the 410, written by the app (its own HTML, trusted like a
+   * block plugin's; the proxy still answers 410 with `text/html`). `input.links` holds the labels in
+   * the app's locale.
+   */
+  render: z.custom<(input: GonePageRenderInput) => string>((value) => typeof value === "function", "must be a function: (input) => html").optional(),
+});
+
 const skillSchema = z.strictObject({
   /** The app's own sections (its numbers, block plugins, fields), written to `references/app.md` of the skill. */
   sections: z.array(skillSectionSchema).superRefine((sections, ctx) => {
@@ -182,6 +200,42 @@ const imagePolicySchema = z.strictObject({
   dimensions: z.custom<ArticleImagePolicy["dimensions"]>((value) => typeof value === "function", "must be a function: (src) => ({ width, height }) or null"),
 });
 
+/** A URL fragment or HTML id part, without `#`: a JSON-LD node id or the cluster anchor prefix. */
+const fragmentSchema = z
+  .string()
+  .max(40)
+  .regex(/^[A-Za-z][A-Za-z0-9_-]*$/, "must be a letter followed by letters, digits, - or _, without #, e.g. article");
+
+const jsonLdSchema = z.strictObject({
+  /** The `@id` fragments of the nodes: `<url>#<article>`, `<url>#<term>`, `<glossary url>#<glossary>`. */
+  ids: z
+    .strictObject({ article: fragmentSchema.default("article"), term: fragmentSchema.default("term"), glossary: fragmentSchema.default("glossary") })
+    .default({ article: "article", term: "term", glossary: "glossary" }),
+});
+
+const anchorsSchema = z.strictObject({
+  /** A cluster's section on the listing is `<cluster>-<key>`, the breadcrumb of its articles points there. */
+  cluster: fragmentSchema.default("cluster"),
+});
+
+/** The Open Graph locale of a language when the app sets none: `og:locale` is `language_TERRITORY`. */
+export const DEFAULT_OPEN_GRAPH_LOCALES = { en: "en_US", pl: "pl_PL" } as const;
+
+const localeTagsSchema = z.strictObject({
+  /** The content's language as a BCP-47 tag: JSON-LD `inLanguage` and the feed's `<language>`; the bare code by default. */
+  bcp47: z
+    .string()
+    .regex(/^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/, "must be a BCP-47 tag, e.g. pl-PL")
+    .optional(),
+  /** `og:locale` (`language_TERRITORY`); `en_US` or `pl_PL` by default. */
+  openGraph: z
+    .string()
+    .regex(/^[a-z]{2,3}_[A-Z]{2}$/, "must be an Open Graph locale (language_TERRITORY), e.g. pl_PL")
+    .optional(),
+});
+
+export type BlogLocaleTagsInput = z.output<typeof localeTagsSchema>;
+
 export const blogOptionsSchema = z
   .strictObject({
     /** The folder with the article files, relative to the app's root. */
@@ -204,11 +258,24 @@ export const blogOptionsSchema = z
     blocks: z.array(z.custom<BlockPlugin>(isBlockPlugin, "must be a block plugin: { type: \"chart\", render(block) }")).default([]),
     /** Hosts besides those of `appOrigin` and the canonical site origin (`getSiteUrls`) whose links are not marked external (subdomains included). */
     siteHosts: z.array(z.string().regex(HOSTNAME, "must be a host name, e.g. example.com")).default([]),
+    /**
+     * What the pages append to an external link (`renderArticle({ externalMarker })`): the arrow and a
+     * visually hidden "opens in a new tab", the hidden words only, or nothing.
+     */
+    externalLinkMarker: z.enum(EXTERNAL_LINK_MARKERS).default("icon-and-text"),
     /**
      * Which images article bodies may show (`renderArticle({ images })`), used by the pages and the
      * quality gate; without it every image renders as its alt text and the gate refuses it.
      */
     images: imagePolicySchema.optional(),
+    /** The JSON-LD node ids; an app that already published other fragments keeps them here. */
+    jsonLd: jsonLdSchema.default({ ids: { article: "article", term: "term", glossary: "glossary" } }),
+    /** The anchors the pages write; an app whose listing already used another prefix keeps it here. */
+    anchors: anchorsSchema.default({ cluster: "cluster" }),
+    /** The language tags per app locale: BCP-47 for the content, Open Graph for `og:locale`. */
+    locales: z.strictObject({ en: localeTagsSchema.optional(), pl: localeTagsSchema.optional() }).default({}),
+    /** The page a withdrawn text answers with (410): extra links, or the app's own body. */
+    gonePage: gonePageSchema.default({ links: [] }),
     /** How long the listing and glossary cache their reads; keep it equal to the pages' `revalidate`. */
     revalidateSeconds: z.number().int().min(1).default(DEFAULT_REVALIDATE_SECONDS),
     /** The text quality gate (`softure-blog check`, and every publish); `false` turns it off. */

package/src/pages/body.ts

@@ -11,7 +11,7 @@ import { getTermPath, type BlogRoutes } from "./paths.js";
 export interface RenderPageBodyOptions {
   readonly glossary: readonly GlossaryTerm[];
   readonly routes: BlogRoutes;
-  readonly options: Pick<BlogOptions, "blocks" | "images" | "siteHosts">;
+  readonly options: Pick<BlogOptions, "blocks" | "images" | "siteHosts"> & Partial<Pick<BlogOptions, "externalLinkMarker">>;
   /** The app's own origins (`appOrigin` and the canonical site origin); their hosts are the site's (links to them are not external). */
   readonly origins: readonly string[];
   readonly messages: BlogMessages;
@@ -28,6 +28,7 @@ export function renderPageBody<TNode = unknown>(text: BlogArticle, input: Render
     // app's plugins return.
     blocks: input.options.blocks as readonly BlockPlugin<TNode>[],
     article: { currentAsOf: text.currentAsOf, fields: text.fields },
+    ...(input.options.externalLinkMarker === undefined ? {} : { externalMarker: input.options.externalLinkMarker }),
     messages: input.messages.render,
   });
 }

package/src/pages/index.ts

@@ -2,8 +2,9 @@
 // 301/410 decisions. The components (`../ui/`) and the Next adapter (`../next/`) render what it returns.
 export { findArticlesLinkingTerm, renderPageBody, type RenderPageBodyOptions } from "./body.js";
 export { formatDay, getArticleDates, getDayInZone, type ArticleDates } from "./dates.js";
-export { getArticleImageUrl, getArticleJsonLd, getGlossaryJsonLd, getTermJsonLd, serializeJsonLd, type JsonLdContext } from "./json-ld.js";
+export { DEFAULT_JSON_LD_IDS, getArticleImageUrl, getArticleJsonLd, getGlossaryJsonLd, getTermJsonLd, serializeJsonLd, type JsonLdContext, type JsonLdIds } from "./json-ld.js";
 export {
+  DEFAULT_CLUSTER_ANCHOR_PREFIX,
   getArticleCrumbs,
   getClusterAnchor,
   getClusterLabel,
@@ -11,6 +12,7 @@ export {
   groupByCluster,
   sortTerms,
   splitClusterLead,
+  type ArticleCrumbOptions,
   type ClusterGroup,
   type Crumb,
   type CrumbLabels,
@@ -34,4 +36,7 @@ export {
   type BlogPathLookup,
   type CachedDeciderOptions,
   type GonePageCopy,
+  type GonePageLink,
+  type GonePageOptions,
+  type GonePageRenderInput,
 } from "./redirects.js";

package/src/pages/json-ld.ts

@@ -12,13 +12,34 @@ export interface JsonLdContext {
   readonly urls: SiteUrls;
   readonly routes: BlogRoutes;
   readonly locale: Locale;
+  /** The BCP-47 tag written as `inLanguage` (`getBlogLocaleTags`); `locale` when left out. */
+  readonly language?: string;
+  /** The `@id` fragments; `article`, `term` and `glossary` when left out. */
+  readonly ids?: JsonLdIds;
   readonly timezone: string;
   /** The brand as author and publisher; `null` leaves them out. */
   readonly brand: string | null;
 }
 
+/** The fragments after `#` in the nodes' `@id`s. */
+export interface JsonLdIds {
+  readonly article: string;
+  readonly term: string;
+  readonly glossary: string;
+}
+
+export const DEFAULT_JSON_LD_IDS: JsonLdIds = { article: "article", term: "term", glossary: "glossary" };
+
 type JsonLd = Record<string, unknown>;
 
+function getIds(ctx: Pick<JsonLdContext, "ids">): JsonLdIds {
+  return ctx.ids ?? DEFAULT_JSON_LD_IDS;
+}
+
+function getLanguage(ctx: Pick<JsonLdContext, "language" | "locale">): string {
+  return ctx.language ?? ctx.locale;
+}
+
 /** JSON for a `<script type="application/ld+json">`: no text in it can close the tag. */
 export function serializeJsonLd(data: unknown): string {
   return JSON.stringify(data).replace(/</g, "\\u003c");
@@ -57,12 +78,12 @@ export function getArticleJsonLd(article: BlogArticle, crumbs: readonly Crumb[],
   const graph: JsonLd[] = [
     {
       "@type": "BlogPosting",
-      "@id": `${url}#article`,
+      "@id": `${url}#${getIds(ctx).article}`,
       mainEntityOfPage: url,
       url,
       headline: article.title,
       description: article.description,
-      inLanguage: ctx.locale,
+      inLanguage: getLanguage(ctx),
       datePublished: dates.published,
       dateModified: dates.updated ?? dates.published,
       ...(brand === null ? {} : { author: brand, publisher: brand }),
@@ -80,8 +101,8 @@ export function getArticleJsonLd(article: BlogArticle, crumbs: readonly Crumb[],
   return { "@context": "https://schema.org", "@graph": graph };
 }
 
-function getTermSetReference(ctx: Pick<JsonLdContext, "urls" | "routes">, glossaryTitle: string): JsonLd {
-  return { "@type": "DefinedTermSet", "@id": `${ctx.urls.getCanonicalUrl(ctx.routes.glossary)}#glossary`, name: glossaryTitle };
+function getTermSetReference(ctx: Pick<JsonLdContext, "urls" | "routes" | "ids">, glossaryTitle: string): JsonLd {
+  return { "@type": "DefinedTermSet", "@id": `${ctx.urls.getCanonicalUrl(ctx.routes.glossary)}#${getIds(ctx).glossary}`, name: glossaryTitle };
 }
 
 /** A term: `DefinedTerm` in the glossary's `DefinedTermSet`, and its `BreadcrumbList`. */
@@ -92,11 +113,11 @@ export function getTermJsonLd(term: BlogArticle, crumbs: readonly Crumb[], ctx:
     "@graph": [
       {
         "@type": "DefinedTerm",
-        "@id": `${url}#term`,
+        "@id": `${url}#${getIds(ctx).term}`,
         url,
         name: term.title,
         description: term.description,
-        inLanguage: ctx.locale,
+        inLanguage: getLanguage(ctx),
         ...(term.termForms.length > 0 ? { alternateName: term.termForms } : {}),
         inDefinedTermSet: getTermSetReference(ctx, glossaryTitle),
       },
@@ -111,10 +132,10 @@ export function getGlossaryJsonLd(terms: readonly BlogArticle[], ctx: JsonLdCont
     "@context": "https://schema.org",
     ...getTermSetReference(ctx, glossaryTitle),
     url: ctx.urls.getCanonicalUrl(ctx.routes.glossary),
-    inLanguage: ctx.locale,
+    inLanguage: getLanguage(ctx),
     hasDefinedTerm: terms.map((term) => {
       const url = ctx.urls.getCanonicalUrl(getTermPath(ctx.routes, term.slug));
-      return { "@type": "DefinedTerm", "@id": `${url}#term`, name: term.title, description: term.description, url };
+      return { "@type": "DefinedTerm", "@id": `${url}#${getIds(ctx).term}`, name: term.title, description: term.description, url };
     }),
   };
 }

package/src/pages/listing.ts

@@ -23,9 +23,12 @@ export function getClusterLabel(cluster: string, labels: Readonly<Record<string,
   return words.charAt(0).toUpperCase() + words.slice(1);
 }
 
-/** The anchor of a cluster's section on the listing: the target of the article's middle crumb. */
-export function getClusterAnchor(cluster: string): string {
-  return `cluster-${cluster}`;
+/** The cluster anchor prefix when the app sets none (`blog({ anchors: { cluster } })`). */
+export const DEFAULT_CLUSTER_ANCHOR_PREFIX = "cluster";
+
+/** The anchor of a cluster's section on the listing (`<prefix>-<cluster>`): the target of the article's middle crumb. */
+export function getClusterAnchor(cluster: string, prefix: string = DEFAULT_CLUSTER_ANCHOR_PREFIX): string {
+  return `${prefix}-${cluster}`;
 }
 
 /** The pillar leads its group; the rest keep their order. Without a pillar there is no lead. */
@@ -75,11 +78,21 @@ export interface CrumbLabels {
   readonly cluster: (cluster: string) => string;
 }
 
+export interface ArticleCrumbOptions {
+  /** The listing's cluster anchor prefix; `cluster` when left out. */
+  readonly clusterAnchorPrefix?: string;
+}
+
 /** Blog › cluster › title; without a cluster, Blog › title. */
-export function getArticleCrumbs(article: Pick<BlogArticle, "slug" | "title" | "cluster">, routes: BlogRoutes, labels: CrumbLabels): Crumb[] {
+export function getArticleCrumbs(
+  article: Pick<BlogArticle, "slug" | "title" | "cluster">,
+  routes: BlogRoutes,
+  labels: CrumbLabels,
+  options: ArticleCrumbOptions = {},
+): Crumb[] {
   const crumbs: Crumb[] = [{ name: labels.blog, path: routes.index }];
   if (article.cluster !== null) {
-    crumbs.push({ name: labels.cluster(article.cluster), path: `${routes.index}#${getClusterAnchor(article.cluster)}` });
+    crumbs.push({ name: labels.cluster(article.cluster), path: `${routes.index}#${getClusterAnchor(article.cluster, options.clusterAnchorPrefix)}` });
   }
   crumbs.push({ name: article.title, path: getArticlePath(routes, article.slug) });
   return crumbs;