@softure-ai/blog 0.1.6 → 0.1.8

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";
@@ -50,8 +51,12 @@ function isFieldsSchema(value: unknown): value is BlogFieldsSchema {
 
 function isBlockPlugin(value: unknown): value is BlockPlugin {
   if (typeof value !== "object" || value === null) return false;
-  const candidate = value as { type?: unknown; render?: unknown };
-  return typeof candidate.type === "string" && KEBAB.test(candidate.type) && typeof candidate.render === "function";
+  const candidate = value as { type?: unknown; syntax?: unknown; render?: unknown; markdown?: unknown };
+  return (
+    typeof candidate.type === "string" && KEBAB.test(candidate.type) && typeof candidate.render === "function" &&
+    (candidate.syntax === undefined || candidate.syntax === "fence" || candidate.syntax === "directive") &&
+    (candidate.markdown === undefined || typeof candidate.markdown === "function")
+  );
 }
 
 /** How long the pages cache their reads by default, in seconds; the app's `revalidate` should match. */
@@ -158,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) => {
@@ -200,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/accept.ts

@@ -0,0 +1,39 @@
+// Content negotiation for the Markdown representation: which requests ask for Markdown.
+
+interface MediaRange {
+  readonly type: string;
+  readonly subtype: string;
+  readonly q: number;
+}
+
+function parseAccept(accept: string): MediaRange[] {
+  return accept.split(",").flatMap((part) => {
+    const [range = "", ...params] = part.trim().toLowerCase().split(";");
+    const [type, subtype] = range.trim().split("/");
+    if (type === undefined || type === "" || subtype === undefined || subtype === "") return [];
+    const qParam = params.map((param) => param.trim()).find((param) => param.startsWith("q="));
+    const q = qParam === undefined ? 1 : Number(qParam.slice(2));
+    return Number.isFinite(q) ? [{ type, subtype, q }] : [];
+  });
+}
+
+/** The weight of a type by the most specific matching range (RFC 9110 §12.5.1); 0 without a match. */
+function getQuality(ranges: readonly MediaRange[], type: string, subtype: string): number {
+  const exact = ranges.find((range) => range.type === type && range.subtype === subtype);
+  const group = ranges.find((range) => range.type === type && range.subtype === "*");
+  const any = ranges.find((range) => range.type === "*" && range.subtype === "*");
+  return (exact ?? group ?? any)?.q ?? 0;
+}
+
+/**
+ * Whether an `Accept` header asks for Markdown rather than HTML. `text/markdown` must be named: `*\/*`
+ * (curl, most crawlers, browser prefetches) matches Markdown as well as HTML, and they want the page.
+ * A tie goes to Markdown: a client that names it next to HTML with the same weight is an agent.
+ */
+export function prefersMarkdown(accept: string | null): boolean {
+  if (accept === null) return false;
+  const ranges = parseAccept(accept);
+  const markdown = ranges.find((range) => range.type === "text" && range.subtype === "markdown");
+  if (markdown === undefined || markdown.q <= 0) return false;
+  return markdown.q >= getQuality(ranges, "text", "html");
+}

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

@@ -8,12 +8,21 @@
 //   }
 //
 // Next 16 runs `proxy.ts` on Node.js, so the database handle is the process-wide one.
+//
+// `createBlogMarkdown` answers an article or term page asked for with `Accept: text/markdown` with the
+// text as Markdown; put it before the redirects so a moved or withdrawn text still answers as before:
+//
+//   return (await blogMarkdown(request)) ?? (await blogRedirects(request)) ?? …
 import { systemClock, type SoftureConfig } from "@softure-ai/core";
 import { getConfiguredDatabase } from "@softure-ai/db";
-import { findArticleBySlug, findSlugRedirect, type BlogContext } from "../db/articles.js";
+import { findArticleBySlug, findSlugRedirect, getPublishedArticle, type BlogContext } from "../db/articles.js";
+import { prefersMarkdown } from "../pages/accept.js";
+import { toArticleMarkdown } from "../render/article-markdown.js";
 import { matchBlogPath } from "../pages/paths.js";
 import { buildGonePage, createCachedBlogPathDecider, type BlogPathLookup, type CachedDeciderOptions } from "../pages/redirects.js";
-import { getBlogMessages, getBlogReservedSlugs, getBlogRoutes } from "../server/options.js";
+import { getBlogMessages, getBlogOptions, getBlogReservedSlugs, getBlogRoutes } from "../server/options.js";
+
+export { prefersMarkdown };
 
 export type BlogRedirects = (request: Request) => Promise<Response | null>;
 
@@ -44,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;
@@ -64,3 +73,60 @@ export function createBlogRedirects(config: SoftureConfig, options: BlogRedirect
     return null;
   };
 }
+
+/** 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 {
+  /** The store's context; the shared database handle of `config.database` by default (tests pass PGlite). */
+  readonly getContext?: () => Promise<BlogContext>;
+  /** Where a failed read is reported; `console.error` by default. The request then goes on to the page. */
+  readonly onError?: (message: string) => void;
+}
+
+const MARKDOWN_HEADERS = {
+  "content-type": "text/markdown; charset=utf-8",
+  // One address, two representations. `private`: a shared cache must not hand Markdown to a browser.
+  vary: "Accept",
+  "cache-control": "private, max-age=0, must-revalidate",
+};
+
+/**
+ * Answers a GET or HEAD of a published article or term whose `Accept` asks for Markdown
+ * (`prefersMarkdown`) with the text as Markdown (`toArticleMarkdown`, the app's block plugins giving
+ * their Markdown form). `null` for everything else, and when the read fails: the page answers then.
+ */
+export function createBlogMarkdown(config: SoftureConfig, options: BlogMarkdownOptions = {}): BlogMarkdown {
+  const routes = getBlogRoutes(config);
+  const reservedSlugs = getBlogReservedSlugs(config);
+  const getContext = options.getContext ?? createDefaultContext(config);
+  const onError = options.onError ?? ((message: string) => console.error(message));
+  const { blocks } = getBlogOptions(config);
+  const messages = getBlogMessages(config).pages;
+
+  return async (request) => {
+    if (request.method !== "GET" && request.method !== "HEAD") return null;
+    if (!prefersMarkdown(request.headers.get("accept"))) return null;
+    const url = new URL(request.url);
+    const match = matchBlogPath(url.pathname, routes, reservedSlugs);
+    if (match === null) return null;
+    let article;
+    try {
+      article = await getPublishedArticle(await getContext(), match.slug);
+    } catch (error) {
+      onError(`@softure-ai/blog: reading ${url.pathname} as Markdown failed: ${error instanceof Error ? error.message : String(error)}`);
+      return null;
+    }
+    if (article?.kind !== match.kind) return null;
+    const body = toArticleMarkdown(article, { blocks, messages });
+    const headers = { ...MARKDOWN_HEADERS, "x-markdown-tokens": String(Math.ceil(body.length / 4)) };
+    return new Response(request.method === "HEAD" ? null : body, { status: 200, headers });
+  };
+}

package/src/quality/catalog.ts

@@ -75,7 +75,10 @@ export function listQualityRules(settings: QualitySettings): QualityCatalogRule[
     ...ruleset.patterns.map((pattern) => rule("style", pattern.id, pattern.severity, pattern.message)),
     ...settings.voicePatterns.map((pattern) => rule("voice", pattern.id, pattern.severity, pattern.message)),
     ...(options.ymyl === null ? [] : YMYL_RULES),
-    ...(options.blocks.length === 0 ? [] : [rule("structure", "block-requires", "error", "a block plugin's fenced block has the frontmatter keys it requires")]),
+    ...(options.blocks.length === 0 ? [] : [rule("structure", "block-requires", "error", "a block plugin's block has the frontmatter keys it requires")]),
+    ...(options.blocks.some((plugin) => plugin.syntax === "directive")
+      ? [rule("structure", "block-directive", "error", "a ::directive line names a directive the blog renders, with readable key=\"value\" attributes")]
+      : []),
     ...(options.plugins.length === 0 ? [] : PLUGIN_RULES),
     ...options.plugins.flatMap((plugin) => plugin.rules.map((info) => rule("plugin", info.id, info.severity, info.description))),
   ];

package/src/quality/check-article.ts

@@ -8,7 +8,7 @@ import { parseArticleFile, type ParseArticleFileOptions } from "../content/artic
 import { splitArticleBody, splitBlocks } from "./blocks.js";
 import { sortFindings, type QualityFinding } from "./finding.js";
 import type { QualityPlugin } from "./plugin.js";
-import { checkBlockRequires } from "./rules/blocks.js";
+import { checkBlockRequires, checkDirectives } from "./rules/blocks.js";
 import { checkImages } from "./rules/images.js";
 import type { RuleInput } from "./rules/input.js";
 import { checkLinks, collectLinks, type InternalLinkResolver } from "./rules/links.js";
@@ -58,6 +58,7 @@ export function checkArticle(input: CheckArticleInput): QualityCheckResult {
     ...checkStyle(ruleInput),
     ...checkRhythm(ruleInput),
     ...checkBlockRequires(article, pluginBlocks),
+    ...checkDirectives(blocks, pluginBlocks, settings.options.blocks),
     ...checkImages(images, settings.images),
   ];
   const fromPlugins = settings.options.plugins.flatMap((plugin) => runPlugin(plugin, { article, blocks, pluginBlocks, today, ruleset: settings.ruleset }));

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

@@ -9,8 +9,12 @@ const KEBAB = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 
 function isBlockPlugin(value: unknown): value is BlockPlugin {
   if (typeof value !== "object" || value === null) return false;
-  const candidate = value as { type?: unknown; render?: unknown };
-  return typeof candidate.type === "string" && typeof candidate.render === "function";
+  const candidate = value as { type?: unknown; syntax?: unknown; render?: unknown; markdown?: unknown };
+  return (
+    typeof candidate.type === "string" && typeof candidate.render === "function" &&
+    (candidate.syntax === undefined || candidate.syntax === "fence" || candidate.syntax === "directive") &&
+    (candidate.markdown === undefined || typeof candidate.markdown === "function")
+  );
 }
 
 const range = (min: number, max: number) =>
@@ -22,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({}),
@@ -71,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/rules/blocks.ts

@@ -1,7 +1,8 @@
 // Block plugin needs (BL-3): a fenced block of a block plugin reads frontmatter keys (`requires`), and
 // an article that lacks one would render the block without its data.
 import type { BlogArticleInput } from "../../contract.js";
-import type { FoundBlock } from "../../render/render-article.js";
+import { parseDirectiveLine, type BlockPlugin, type FoundBlock } from "../../render/render-article.js";
+import type { Block } from "../blocks.js";
 import type { QualityFinding } from "../finding.js";
 
 export function checkBlockRequires(article: BlogArticleInput, pluginBlocks: readonly FoundBlock[]): QualityFinding[] {
@@ -41,3 +42,27 @@ function hasFrontmatterKey(article: BlogArticleInput, key: string): boolean {
       return article.fields[key] !== undefined;
   }
 }
+
+/**
+ * Directive lines the renderer would not turn into a block (BL-6 for directives): a name no directive
+ * plugin renders (it would show as a paragraph `::chrat{…}`), or attributes it cannot read. Checked
+ * only when the app registers a directive plugin; otherwise `::` lines are the app's own business.
+ */
+export function checkDirectives(blocks: readonly Block[], pluginBlocks: readonly FoundBlock[], plugins: readonly BlockPlugin[]): QualityFinding[] {
+  const names = plugins.filter((plugin) => plugin.syntax === "directive").map((plugin) => plugin.type);
+  if (names.length === 0) return [];
+  const unknown = blocks.flatMap((block) => {
+    if (block.kind !== "directive") return [];
+    const directive = parseDirectiveLine(block.text);
+    if (directive === null || names.includes(directive.name)) return [];
+    return [finding(`::${directive.name} is not a directive this blog renders; use one of: ${names.join(", ")}`, block.line)];
+  });
+  const unreadable = pluginBlocks
+    .filter((block) => block.syntax === "directive" && block.attributes === null)
+    .map((block) => finding(`the attributes of ::${block.type} cannot be read; write them as key="value" pairs, each key once`, block.line));
+  return [...unknown, ...unreadable].sort((a, b) => (a.line ?? 0) - (b.line ?? 0));
+}
+
+function finding(message: string, line: number): QualityFinding {
+  return { rule: "block-directive", severity: "error", message, line };
+}

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/article-markdown.ts

@@ -0,0 +1,34 @@
+// An article or term as Markdown for agents (`Accept: text/markdown`): the stored Markdown in a frame
+// that carries what the HTML page shows around it (title, description, the day the facts were checked,
+// the summary, sources and FAQ). Exact by construction: no HTML round trip.
+import type { BlogArticle } from "../contract.js";
+import { en } from "../messages/en.js";
+import { replaceArticleBlocks, type BlockPlugin } from "./render-article.js";
+
+export type ArticleMarkdownInput = Pick<BlogArticle, "title" | "description" | "summary" | "bodyMarkdown" | "sources" | "faq" | "currentAsOf" | "fields">;
+
+export interface ArticleMarkdownOptions {
+  /** The app's block plugins; a block whose plugin has `markdown` is replaced by its output. */
+  readonly blocks?: readonly BlockPlugin[];
+  /** The pages' copy for the frame's labels; English by default. */
+  readonly messages?: Pick<(typeof en)["pages"], "summary" | "sources" | "faq" | "currentAsOf">;
+}
+
+export function toArticleMarkdown(article: ArticleMarkdownInput, options: ArticleMarkdownOptions = {}): string {
+  const messages = options.messages ?? en.pages;
+  const body = replaceArticleBlocks(article.bodyMarkdown.trim(), options.blocks ?? [], { currentAsOf: article.currentAsOf, fields: article.fields });
+  const parts = [`# ${article.title}`, article.description, `${messages.currentAsOf}: ${article.currentAsOf}`];
+  if (article.summary !== null) parts.push(`> **${messages.summary}:** ${article.summary}`);
+  parts.push(body);
+  if (article.sources.length > 0) {
+    parts.push(`## ${messages.sources}`, article.sources.map((source) => `- [${escapeLinkText(source.name)}](${source.url})`).join("\n"));
+  }
+  if (article.faq.length > 0) {
+    parts.push(`## ${messages.faq}`, ...article.faq.flatMap((entry) => [`### ${entry.question}`, entry.answer]));
+  }
+  return `${parts.join("\n\n")}\n`;
+}
+
+function escapeLinkText(text: string): string {
+  return text.replace(/[[\]\\]/g, (char) => `\\${char}`);
+}

package/src/render/index.ts

@@ -11,17 +11,25 @@ export {
   type ImageProblem,
   type ImageVerdict,
 } from "./images.js";
+export { toArticleMarkdown, type ArticleMarkdownInput, type ArticleMarkdownOptions } from "./article-markdown.js";
 export { DEFAULT_WORDS_PER_MINUTE, getReadingMinutes } from "./reading-time.js";
 export {
   findArticleBlocks,
+  parseDirectiveAttributes,
+  parseDirectiveLine,
+  EXTERNAL_LINK_MARKERS,
   renderArticle,
+  replaceArticleBlocks,
   type ArticleBlock,
+  type BlockAttributes,
+  type BlockSyntax,
   type ArticleHeading,
   type ArticleSegment,
   type BlockArticle,
   type BlockOutput,
   type BlockPlugin,
   type BlogRenderMessages,
+  type ExternalLinkMarker,
   type FoundBlock,
   type RenderArticleOptions,
   type RenderedArticle,