@softure-ai/blog 0.1.7 → 0.1.9

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/index.ts

@@ -23,7 +23,7 @@ export {
   type RunBlogPublishOptions,
 } from "../db/publish-run.js";
 export { checkArticlesTable } from "./health.js";
-export { getBlogMessages, getBlogOptions, getBlogRefreshPath, getBlogReservedSlugs, getBlogRoutes, getQualitySettings } from "./options.js";
+export { getBlogLocaleTags, getBlogMessages, getBlogOptions, getBlogRefreshPath, getBlogReservedSlugs, getBlogRoutes, getQualitySettings, type BlogLocaleTags } from "./options.js";
 export * from "../discovery/index.js";
 export * from "../pages/index.js";
 export * from "../quality/index.js";

package/src/server/options.ts

@@ -1,7 +1,7 @@
 // The blog options, routes and copy of the running app, read from the configuration.
 import { getModule, getSiteUrls, type AnySoftureModule, type SoftureConfig } from "@softure-ai/core";
 import type { BlogMessages } from "../messages/index.js";
-import type { BlogOptions } from "../options.js";
+import { DEFAULT_OPEN_GRAPH_LOCALES, type BlogOptions } from "../options.js";
 import { getReservedSlugs, normalizeRoute, type BlogRoutes } from "../pages/paths.js";
 import { resolveQualitySettings, type QualitySettings } from "../quality/settings.js";
 
@@ -39,6 +39,19 @@ export function getBlogRoutes(config: SoftureConfig): BlogRoutes {
   return { index: read("index"), glossary: read("glossary"), method: read("method"), rss: read("rss") };
 }
 
+export interface BlogLocaleTags {
+  /** BCP-47: JSON-LD `inLanguage` and the feed's `<language>`. */
+  readonly bcp47: string;
+  /** `og:locale`, `language_TERRITORY`. */
+  readonly openGraph: string;
+}
+
+/** The app locale's language tags: the app's `locales` entry, else the bare code and `en_US` / `pl_PL`. */
+export function getBlogLocaleTags(config: SoftureConfig): BlogLocaleTags {
+  const tags = getBlogOptions(config).locales[config.locale];
+  return { bcp47: tags?.bcp47 ?? config.locale, openGraph: tags?.openGraph ?? DEFAULT_OPEN_GRAPH_LOCALES[config.locale] };
+}
+
 /** The path of the cache refresh route (`refreshBlogCache`), outside the pages' routes. */
 export function getBlogRefreshPath(config: SoftureConfig): string {
   const path = getBlogModule(config).routes.refresh;
@@ -57,6 +70,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);
 }

package/src/ui/blog-listing.tsx

@@ -59,8 +59,8 @@ export function BlogListingView({ context, groups, termCount, timezone, cta }: B
       ) : (
         <div className="blog-groups">
           {groups.map((group) => {
-            const id = group.cluster === null ? undefined : getClusterAnchor(group.cluster);
-            const headingId = `${id ?? "cluster-other"}-heading`;
+            const id = group.cluster === null ? undefined : getClusterAnchor(group.cluster, context.clusterAnchorPrefix);
+            const headingId = `${id ?? getClusterAnchor("other", context.clusterAnchorPrefix)}-heading`;
             return (
               <section key={group.cluster ?? ""} id={id} aria-labelledby={headingId} className="blog-group">
                 <h2 id={headingId} className="blog-group-title">

package/src/ui/page-context.ts

@@ -14,4 +14,6 @@ export interface BlogPageContext {
   readonly brand: string | null;
   /** The note under every text in the locale; `null` without one. */
   readonly disclaimer: string | null;
+  /** The listing's cluster anchor prefix (`<prefix>-<cluster>`); `cluster` when left out. */
+  readonly clusterAnchorPrefix?: string;
 }