@softure-ai/blog 0.1.8 → 0.1.9

package/src/options.ts

@@ -200,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. */
@@ -232,6 +268,12 @@ export const blogOptionsSchema = z
      * 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`. */

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,

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;

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;

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;
 }