@softure-ai/blog 0.1.7 → 0.1.8

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. */

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) => {
@@ -204,11 +222,18 @@ 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 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

@@ -34,4 +34,7 @@ export {
   type BlogPathLookup,
   type CachedDeciderOptions,
   type GonePageCopy,
+  type GonePageLink,
+  type GonePageOptions,
+  type GonePageRenderInput,
 } from "./redirects.js";

package/src/pages/redirects.ts

@@ -92,15 +92,38 @@ export interface GonePageCopy {
   readonly link: string;
 }
 
+/** A further way on from the 410 page, after the link to the listing; the label in the app's locale. */
+export interface GonePageLink {
+  readonly href: string;
+  readonly label: string;
+}
+
+/** What `blog({ gonePage: { render } })` receives to write the whole 410 body. */
+export interface GonePageRenderInput {
+  readonly copy: GonePageCopy;
+  readonly lang: string;
+  readonly indexPath: string;
+  readonly links: readonly GonePageLink[];
+}
+
+export interface GonePageOptions {
+  readonly lang: string;
+  readonly indexPath: string;
+  /** Links listed under the way to the listing (a calculator, a sign-up). */
+  readonly links?: readonly GonePageLink[];
+}
+
 function escapeHtml(text: string): string {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
 
 /**
- * The body of a 410: a short page with the way on. No React (the proxy renders no components), no
- * script, no external resource; `noindex`. Every value is escaped: copy comes from the app's overrides.
+ * The body of a 410: a short page with the way on to the listing and the app's further `links`. No
+ * React (the proxy renders no components), no script, no external resource; `noindex`. Every value is
+ * escaped: copy and links come from the app's options.
  */
-export function buildGonePage(copy: GonePageCopy, options: { readonly lang: string; readonly indexPath: string }): string {
+export function buildGonePage(copy: GonePageCopy, options: GonePageOptions): string {
+  const links = options.links ?? [];
   return [
     "<!doctype html>",
     `<html lang="${escapeHtml(options.lang)}">`,
@@ -113,6 +136,7 @@ export function buildGonePage(copy: GonePageCopy, options: { readonly lang: stri
     '<body style="font-family:system-ui,sans-serif;max-width:40rem;margin:4rem auto;padding:0 1rem;line-height:1.5">',
     `<h1>${escapeHtml(copy.heading)}</h1>`,
     `<p>${escapeHtml(copy.body)} <a href="${escapeHtml(options.indexPath)}">${escapeHtml(copy.link)}</a></p>`,
+    ...(links.length === 0 ? [] : ["<ul>", ...links.map((link) => `<li><a href="${escapeHtml(link.href)}">${escapeHtml(link.label)}</a></li>`), "</ul>"]),
     "</body>",
     "</html>",
     "",

package/src/proxy/index.ts

@@ -53,7 +53,7 @@ export function createBlogRedirects(config: SoftureConfig, options: BlogRedirect
     findRedirect: async (oldSlug) => findSlugRedirect(await getContext(), oldSlug),
   };
   const decide = createCachedBlogPathDecider(routes, lookup, options);
-  const gonePage = buildGonePage(getBlogMessages(config).gone, { lang: config.locale, indexPath: routes.index });
+  const gonePage = renderGonePage(config, routes.index);
 
   return async (request) => {
     if (request.method !== "GET" && request.method !== "HEAD") return null;
@@ -74,6 +74,14 @@ export function createBlogRedirects(config: SoftureConfig, options: BlogRedirect
   };
 }
 
+/** The 410 body: the app's `gonePage.render` when given, else the module's page with the app's links. */
+function renderGonePage(config: SoftureConfig, indexPath: string): string {
+  const { gonePage } = getBlogOptions(config);
+  const links = gonePage.links.map((link) => ({ href: link.href, label: link.label[config.locale] ?? link.label.en }));
+  const input = { copy: getBlogMessages(config).gone, lang: config.locale, indexPath, links };
+  return gonePage.render === undefined ? buildGonePage(input.copy, input) : gonePage.render(input);
+}
+
 export type BlogMarkdown = (request: Request) => Promise<Response | null>;
 
 export interface BlogMarkdownOptions {

package/src/quality/index.ts

@@ -11,7 +11,7 @@ export { qualityOptionsSchema, type QualityLimits, type QualityOptions, type Qua
 export { isQualityPlugin, type QualityPlugin, type QualityPluginContext, type QualityRuleInfo } from "./plugin.js";
 export { collectLinks, type InternalLinkResolver, type LinkSummary } from "./rules/links.js";
 export { enRuleset, plRuleset, QUALITY_LANGUAGES, QUALITY_RULESETS, type LanguageRuleset, type QualityLanguage, type StylePattern } from "./rulesets/index.js";
-export { getLocalDate, resolveQualitySettings, type QualitySettings } from "./settings.js";
+export { getLocalDate, resolveQualitySettings, type QualityPaths, type QualitySettings } from "./settings.js";
 export {
   countWords,
   findBareUrls,

package/src/quality/link-targets.ts

@@ -1,8 +1,9 @@
-// Internal link targets from the file system (FIRE_TRACKER `src/lib/blog/quality/link-targets.ts`),
-// for `softure-blog check`. A route exists when the Next.js app folder has a `page.*` or `route.*` for
-// it (route groups vanish from the path; private segments and `_folders` are skipped). An article or
-// a glossary term exists when the content folder has its published file of that kind, under
-// `quality.paths`; a static page under the same path wins over the dynamic article route.
+// Internal link targets from the file system, for `softure-blog check`. A route exists when the
+// Next.js app folder has a `page.*` or `route.*` for it (route groups vanish from the path; private
+// segments and `_folders` are skipped). An article or a glossary term exists when the content folder
+// has its published file of that kind, under `QualitySettings.paths` (the blog's routes unless
+// `quality.paths` overrides them); a static page under the same path wins over the dynamic article
+// route.
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { parseArticleFile, type ParseArticleFileOptions } from "../content/article-file.js";

package/src/quality/options.ts

@@ -26,7 +26,7 @@ const range = (min: number, max: number) =>
 const byKind = (article: number, term: number) =>
   z.strictObject({ article: z.number().int().min(0).default(article), term: z.number().int().min(0).default(term) }).prefault({});
 
-/** Thresholds; the defaults are FIRE's, chosen for answer-first texts that AI assistants quote. */
+/** Thresholds; the defaults suit answer-first texts that AI assistants quote. */
 export const qualityLimitsSchema = z
   .strictObject({
     words: z.strictObject({ article: range(600, 4000), term: range(60, 700) }).prefault({}),
@@ -75,8 +75,11 @@ export const qualityOptionsSchema = z.strictObject({
   limits: qualityLimitsSchema,
   /** Per rule: another severity, or "off". */
   severity: z.record(z.string().regex(KEBAB), z.enum(["error", "warning", "off"])).default({}),
-  /** Where the pages live; BL-4 serves them there. */
-  paths: z.strictObject({ articles: sitePath.default("/blog"), terms: sitePath.default("/blog/glossary") }).prefault({}),
+  /**
+   * Where articles and terms live, only to override the blog's `routes` (`articles` defaults to
+   * `routes.index`, `terms` to `routes.glossary`). The resolved pair is `QualitySettings.paths`.
+   */
+  paths: z.strictObject({ articles: sitePath.optional(), terms: sitePath.optional() }).prefault({}),
   /** Absolute origins whose links count as internal, besides the config's `appOrigin` and the canonical site origin (`getSiteUrls`). */
   ownOrigins: z.array(z.url({ protocol: /^https?$/ })).default([]),
   /** The Next.js app folder `softure-blog check` reads routes from. Default: `src/app`, else `app`. */

package/src/quality/settings.ts

@@ -18,13 +18,25 @@ export interface QualitySettings {
   readonly timeZone: string;
   /** The app's image policy (`blog({ images })`); `null` when bodies may show no image. */
   readonly images: ArticleImagePolicy | null;
+  /** Where articles and terms live: `options.paths` where set, else the blog's routes. */
+  readonly paths: QualityPaths;
 }
 
+export interface QualityPaths {
+  readonly articles: string;
+  readonly terms: string;
+}
+
+/** The paths a caller without the blog's routes gets: the module's default routes. */
+const DEFAULT_PATHS: QualityPaths = { articles: "/blog", terms: "/blog/glossary" };
+
 export function resolveQualitySettings(
   options: QualityOptions,
   config: Pick<SoftureConfig, "appOrigin" | "timezone"> & {
     /** The canonical site origin (core's `getSiteUrls(config).origin`) when it is not `appOrigin`. */
     readonly siteOrigin?: string;
+    /** The blog's routes (`getBlogRoutes`), the source of `paths` unless `options.paths` overrides them. */
+    readonly routes?: { readonly index: string; readonly glossary: string };
   },
   images: ArticleImagePolicy | null = null,
 ): QualitySettings {
@@ -44,7 +56,11 @@ export function resolveQualitySettings(
     });
   }
   const origins = [config.appOrigin, ...(config.siteOrigin === undefined ? [] : [config.siteOrigin]), ...options.ownOrigins].map((origin) => new URL(origin).origin);
-  return { options, ruleset, voicePatterns, ownOrigins: [...new Set(origins)], timeZone: config.timezone, images };
+  const paths: QualityPaths = {
+    articles: options.paths.articles ?? config.routes?.index ?? DEFAULT_PATHS.articles,
+    terms: options.paths.terms ?? config.routes?.glossary ?? DEFAULT_PATHS.terms,
+  };
+  return { options, ruleset, voicePatterns, ownOrigins: [...new Set(origins)], timeZone: config.timezone, images, paths };
 }
 
 /** `YYYY-MM-DD` of a moment in a time zone. */

package/src/render/index.ts

@@ -17,6 +17,7 @@ export {
   findArticleBlocks,
   parseDirectiveAttributes,
   parseDirectiveLine,
+  EXTERNAL_LINK_MARKERS,
   renderArticle,
   replaceArticleBlocks,
   type ArticleBlock,
@@ -28,6 +29,7 @@ export {
   type BlockOutput,
   type BlockPlugin,
   type BlogRenderMessages,
+  type ExternalLinkMarker,
   type FoundBlock,
   type RenderArticleOptions,
   type RenderedArticle,

package/src/render/render-article.ts

@@ -17,7 +17,8 @@
 // ## Links
 //
 // A link that leaves the site (`siteHosts`, subdomains included) gets `rel="noopener noreferrer"`,
-// opens in a new tab and carries a visible marker plus a visually hidden "opens in a new tab".
+// opens in a new tab and carries a visible marker plus a visually hidden "opens in a new tab"
+// (`externalMarker`: both, the hidden words only, or neither; the `blog-external` class stays either way).
 //
 // ## Headings and the table of contents
 //
@@ -114,6 +115,11 @@ export type ArticleSegment<TNode = unknown> =
   | { readonly kind: "html"; readonly html: string }
   | { readonly kind: "node"; readonly type: string; readonly node: TNode };
 
+/** What the renderer appends to an external link (`RenderArticleOptions.externalMarker`). */
+export const EXTERNAL_LINK_MARKERS = ["icon-and-text", "text", "none"] as const;
+
+export type ExternalLinkMarker = (typeof EXTERNAL_LINK_MARKERS)[number];
+
 export interface RenderArticleOptions<TNode = unknown> {
   /** Terms for automatic links; without it no text is linked. */
   readonly glossary?: readonly GlossaryTerm[];
@@ -130,6 +136,11 @@ export interface RenderArticleOptions<TNode = unknown> {
   readonly article?: BlockArticle;
   /** Render a table of contents of `h2` down to `maxLevel` (3 by default). */
   readonly toc?: boolean | { readonly maxLevel: number };
+  /**
+   * What follows an external link: the visible arrow and the visually hidden "opens in a new tab"
+   * (`"icon-and-text"`, the default), the hidden words only (`"text"`), or nothing (`"none"`).
+   */
+  readonly externalMarker?: ExternalLinkMarker;
   /** Copy for footnotes, external links and the table of contents; English by default. */
   readonly messages?: BlogRenderMessages;
   readonly wordsPerMinute?: number;
@@ -297,7 +308,14 @@ function addFootnoteMarkup(md: Markdown, messages: BlogRenderMessages): void {
   };
 }
 
-function addExternalLinks(md: Markdown, siteHosts: readonly string[], messages: BlogRenderMessages): void {
+function getExternalMarkerHtml(md: Markdown, marker: ExternalLinkMarker, messages: BlogRenderMessages): string {
+  if (marker === "none") return "";
+  const hidden = `<span class="blog-visually-hidden"> ${md.utils.escapeHtml(messages.opensInNewTab)}</span>`;
+  return marker === "text" ? hidden : `<span class="blog-external-marker" aria-hidden="true">↗</span>${hidden}`;
+}
+
+function addExternalLinks(md: Markdown, siteHosts: readonly string[], messages: BlogRenderMessages, marker: ExternalLinkMarker): void {
+  const markerHtml = getExternalMarkerHtml(md, marker, messages);
   // Markdown links do not nest, but a stack keeps open and close paired whatever the token stream.
   const externalStack: boolean[] = [];
   md.renderer.rules.link_open = (tokens, index, options, _env, self) => {
@@ -312,10 +330,7 @@ function addExternalLinks(md: Markdown, siteHosts: readonly string[], messages:
     return self.renderToken(tokens, index, options);
   };
   md.renderer.rules.link_close = (tokens, index, options, _env, self) => {
-    const marker = externalStack.pop() === true
-      ? `<span class="blog-external-marker" aria-hidden="true">↗</span><span class="blog-visually-hidden"> ${md.utils.escapeHtml(messages.opensInNewTab)}</span>`
-      : "";
-    return marker + self.renderToken(tokens, index, options);
+    return (externalStack.pop() === true ? markerHtml : "") + self.renderToken(tokens, index, options);
   };
 }
 
@@ -513,7 +528,7 @@ function createMarkdown<TNode>(
   md.validateLink = isSafeLink;
   addImages(md, options.images);
   addFootnoteMarkup(md, messages);
-  addExternalLinks(md, options.siteHosts ?? [], messages);
+  addExternalLinks(md, options.siteHosts ?? [], messages, options.externalMarker ?? "icon-and-text");
   addBlockTokens(md, getTypes(plugins, "fence"));
   addDirectiveRule(md, getTypes(plugins, "directive"));
   addHeadingIds(md, state);

package/src/server/options.ts

@@ -57,6 +57,6 @@ export function getBlogReservedSlugs(config: SoftureConfig): string[] {
 export function getQualitySettings(config: SoftureConfig): QualitySettings | null {
   const { quality, images } = getBlogOptions(config);
   if (quality === false) return null;
-  const site = { appOrigin: config.appOrigin, siteOrigin: getSiteUrls(config).origin, timezone: config.timezone };
+  const site = { appOrigin: config.appOrigin, siteOrigin: getSiteUrls(config).origin, timezone: config.timezone, routes: getBlogRoutes(config) };
   return resolveQualitySettings(quality, site, images ?? null);
 }