@rathnasgala2/template 2.2.0 → 3.0.1

package/src/core/internal/render-policy-content.js

@@ -271,7 +271,7 @@ export const CSP_HEADER_ONLY_DIRECTIVES = Object.freeze([
 export const CONTENT_SECURITY_POLICY_META_BASELINE =
   "default-src 'none'; base-uri 'none'; object-src 'none'; " +
   "form-action 'none'; script-src 'self'; " +
-  "style-src 'self'; img-src 'self'; font-src 'self'; connect-src 'none'; " +
+  "style-src 'self'; img-src 'self'; font-src 'self'; connect-src 'self'; " +
   "media-src 'self'; manifest-src 'self'; worker-src 'none'";
 
 /**
@@ -287,7 +287,7 @@ export const CONTENT_SECURITY_POLICY_META_BASELINE =
 export const CONTENT_SECURITY_POLICY_COMPLETE =
   "default-src 'none'; base-uri 'none'; object-src 'none'; " +
   "frame-ancestors 'none'; form-action 'none'; script-src 'self'; " +
-  "style-src 'self'; img-src 'self'; font-src 'self'; connect-src 'none'; " +
+  "style-src 'self'; img-src 'self'; font-src 'self'; connect-src 'self'; " +
   "media-src 'self'; manifest-src 'self'; worker-src 'none'";
 
 /**

package/src/core/internal/robots.js

@@ -0,0 +1,70 @@
+/**
+ * `robots.txt` generation.
+ *
+ * Every site allows all crawlers and names its sitemap by absolute URL. The
+ * publication may additionally opt out of AI training and AI-assistant
+ * crawlers through the validated `publication.crawlers.ai` (`"allow"` |
+ * `"block"`; absent means allow).
+ *
+ * Unlisted (`noindex`) pages are deliberately not disallowed here: a
+ * crawler can only honour a `noindex` directive on a page it is allowed to
+ * fetch.
+ *
+ * Only a `robots.txt` at the host root is honoured by crawlers. This file is
+ * always written at the output root; when the site is served from a path
+ * (for example a GitHub project site), the host's own root `robots.txt` is
+ * what crawlers read, and the `Sitemap:` line here still names the absolute
+ * sitemap URL so it can be copied there.
+ */
+
+/**
+ * The AI crawler and assistant user agents blocked by `crawlers.ai:
+ * "block"`: training crawlers, search crawlers and user-initiated fetchers
+ * of the major AI providers.
+ *
+ * @type {readonly string[]}
+ */
+export const AI_CRAWLER_USER_AGENTS = Object.freeze([
+  'GPTBot',
+  'ChatGPT-User',
+  'OAI-SearchBot',
+  'ClaudeBot',
+  'Claude-User',
+  'Claude-SearchBot',
+  'anthropic-ai',
+  'Google-Extended',
+  'PerplexityBot',
+  'Perplexity-User',
+  'CCBot',
+  'Applebot-Extended',
+  'Bytespider',
+  'Meta-ExternalAgent',
+  'Amazonbot',
+]);
+
+/**
+ * @param {{crawlers?: {ai: 'allow' | 'block'}}} publication the validated
+ *   `publication` (`crawlers` is optional; absent means allow)
+ * @returns {'allow' | 'block'} the AI crawler policy
+ */
+export function readAiCrawlerPolicy(publication) {
+  return publication.crawlers?.ai ?? 'allow';
+}
+
+/**
+ * @param {object} options
+ * @param {'allow' | 'block'} options.aiPolicy
+ * @param {string} options.sitemapUrl the absolute sitemap URL
+ * @returns {string} the exact `robots.txt` text
+ */
+export function buildRobotsTxt({ aiPolicy, sitemapUrl }) {
+  /** @type {string[]} */
+  const groups = ['User-agent: *\nAllow: /'];
+  if (aiPolicy === 'block') {
+    for (const agent of AI_CRAWLER_USER_AGENTS) {
+      groups.push(`User-agent: ${agent}\nDisallow: /`);
+    }
+  }
+  groups.push(`Sitemap: ${sitemapUrl}`);
+  return `${groups.join('\n\n')}\n`;
+}

package/src/core/internal/route-labels.js

@@ -65,3 +65,34 @@ export function routeSegmentForLabel(label) {
   const prefix = asciiReadablePrefix(label);
   return prefix.length > 0 ? `${prefix}-${hash}` : hash;
 }
+
+/**
+ * Derive each author's URL segment: a readable slug of the display name
+ * (lowercase ASCII, at most 48 characters), stable for a given name. When a
+ * name yields no ASCII characters or two authors yield the same slug, the
+ * author with the lower id keeps the slug and every other one falls back to
+ * its id, so a segment is always unique and a later colliding author never
+ * moves an existing author's URL.
+ *
+ * @param {readonly {id: string, displayName: string}[]} authors
+ * @returns {Map<string, string>} author id to URL segment
+ */
+export function deriveAuthorSlugs(authors) {
+  /** @type {Map<string, string>} */
+  const slugs = new Map();
+  const taken = new Set(authors.map((author) => author.id));
+  const ordered = authors.slice().sort((a, b) => (a.id < b.id ? -1 : 1));
+  for (const author of ordered) {
+    const slug = asciiReadablePrefix(author.displayName);
+    if (
+      slug !== '' &&
+      !taken.has(slug) &&
+      ![...slugs.values()].includes(slug)
+    ) {
+      slugs.set(author.id, slug);
+    } else {
+      slugs.set(author.id, author.id);
+    }
+  }
+  return slugs;
+}

package/src/core/internal/seo.js

@@ -112,3 +112,56 @@ export function resolveSocialImageUrl({
 export function twitterCardType(hasImage) {
   return hasImage ? 'summary_large_image' : 'summary';
 }
+
+/**
+ * Shorten plain text to at most `max` characters at a word boundary,
+ * appending an ellipsis when anything was cut (a `<meta name="description">`
+ * is read as a short snippet, so a clean cut beats a mid-word one).
+ *
+ * @param {string} text plain text
+ * @param {number} max the longest result, ellipsis included
+ * @returns {string} the original text when it fits, else the shortened text
+ */
+export function truncateAtWord(text, max) {
+  const collapsed = text.replace(/\s+/g, ' ').trim();
+  const characters = Array.from(collapsed);
+  if (characters.length <= max) return collapsed;
+  const clipped = characters.slice(0, max - 1).join('');
+  const cut = /\s/.test(clipped) ? clipped.replace(/\s+\S*$/, '') : clipped;
+  return `${cut.replace(/[\s,;:.–-]+$/, '')}…`;
+}
+
+/**
+ * Resolve one social image to its absolute URL and pixel dimensions.
+ *
+ * @param {object} options
+ * @param {readonly {path: string, mediaType: string}[]} options.mediaAssets
+ * @param {Readonly<Record<string, {width: number, height: number}>>} [options.mediaDimensions]
+ *   the media pipeline's pixel dimensions per derivative path
+ * @param {{path: string, sourceDigest: string} | undefined} options.reference
+ * @param {string} options.baseUrl
+ * @param {string} options.basePath the public base path
+ * @returns {{url: string, width?: number, height?: number} | undefined}
+ */
+export function resolveSocialImage({
+  mediaAssets,
+  mediaDimensions = {},
+  reference,
+  baseUrl,
+  basePath,
+}) {
+  const url = resolveSocialImageUrl({
+    mediaAssets,
+    reference,
+    baseUrl,
+    basePath,
+  });
+  if (!url) return undefined;
+  const size =
+    mediaDimensions[
+      /** @type {string} */ (
+        resolveOriginalDerivativePath(mediaAssets, reference)
+      )
+    ];
+  return { url, width: size?.width, height: size?.height };
+}

package/src/core/internal/skeleton.js

@@ -11,17 +11,18 @@
  * through {@link renderPageBody}:
  *
  * - a skip link, the very first focusable element, targeting `#main-content`;
- * - exactly one `<header>` (home link with the validated publication name and
- *   an optional core logo carrying required alternative text, plus the
- *   always-present, currently-empty `header-actions` slot);
- * - exactly one primary `<nav>` built from `navigationNormalized.items`;
- * - exactly one `<main id="main-content">`, carrying an optional breadcrumb
- *   `<nav>` before the page's own single `<h1>`;
- * - exactly one `<footer>` with the publication name, resolved footer
- *   navigation, footer profile slot, copyright/license text and the
- *   template attribution line, plus the remaining always-present,
- *   currently-empty core slots (`footer-auxiliary`, `account-intent`,
- *   `conversation`, `newsletter`, `edition-selector`).
+ * - exactly one `<header>` (brand mark or monogram, publication name and
+ *   tagline, the one primary `<nav>` built from `navigationNormalized.items`,
+ *   a script-revealed search button, the `header-actions` slot carrying the
+ *   appearance control, and a `<details>` mobile menu), rendered by
+ *   `internal/chrome.js`;
+ * - exactly one `<main id="main-content">`; each page kind places its own
+ *   breadcrumb `<nav>` and single `<h1>` inside it;
+ * - exactly one `<footer>` (brand, description, social links, navigation
+ *   columns, author profile, copyright and the template attribution line),
+ *   plus the always-present, currently-empty core slots (`footer-auxiliary`,
+ *   `account-intent`, `conversation`, `newsletter`, `edition-selector`),
+ *   rendered by `internal/chrome.js`.
  *
  * Core owns nine versioned semantic slots plus the collapsed
  * `article-footer-ad` slot: `header-actions`, `article-preamble`,
@@ -133,7 +134,7 @@ export function renderSlot(slotName, options = {}) {
  */
 export function renderSkipLink(messages) {
   const label = escapeHtml(/** @type {string} */ (messages.skipToContent));
-  return `<a href="#main-content">${label}</a>`;
+  return `<a class="g-skip" href="#main-content">${label}</a>`;
 }
 
 /**
@@ -148,7 +149,7 @@ export function renderSkipLink(messages) {
  *   internal route's href (`/` when `baseUrl` has no path)
  * @returns {string} the rendered `<li>`
  */
-function renderNavItem(item, currentRoute, urlPrefix) {
+export function renderNavItem(item, currentRoute, urlPrefix) {
   const label = escapeHtml(item.label);
   const href = escapeHtml(
     /** @type {string} */ (
@@ -200,28 +201,7 @@ export function renderPrimaryNavigation({
   const itemsHtml = items
     .map((item) => renderNavItem(item, currentRoute, urlPrefix))
     .join('');
-  return `<nav aria-label="${label}"><ul>${itemsHtml}</ul></nav>`;
-}
-
-/**
- * Render the footer `<nav>` from `navigationNormalized.footerItems`.
- *
- * @param {object} options rendering options
- * @param {readonly import('../../../types/index.d.ts').NavigationItem[]} options.items
- *   `navigationNormalized.footerItems` (0..50 root items)
- * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} options.messages
- *   the resolved message catalog
- * @param {string} [options.urlPrefix] the `baseUrl` path prefix (default `/`)
- * @returns {string} the rendered footer navigation
- */
-export function renderFooterNavigation({ items, messages, urlPrefix = '/' }) {
-  const label = escapeHtml(
-    /** @type {string} */ (messages.footerNavigationLabel),
-  );
-  const itemsHtml = items
-    .map((item) => renderNavItem(item, undefined, urlPrefix))
-    .join('');
-  return `<nav aria-label="${label}"><ul>${itemsHtml}</ul></nav>`;
+  return `<nav class="g-nav" aria-label="${label}"><ul>${itemsHtml}</ul></nav>`;
 }
 
 /**
@@ -262,7 +242,7 @@ export function renderBreadcrumbs({ trail, messages }) {
       return `<li><a href="${escapeHtml(step.route)}">${text}</a></li>`;
     })
     .join('');
-  return `<nav aria-label="${label}"><ol>${items}</ol></nav>`;
+  return `<nav class="g-crumbs" aria-label="${label}"><ol>${items}</ol></nav>`;
 }
 
 /**
@@ -307,7 +287,7 @@ export function renderPagination({
       ? `<a rel="next" href="${escapeHtml(routeForPage(currentPage + 1))}">${nextLabel}</a>`
       : `<span>${nextLabel}</span>`;
   return (
-    `<nav aria-label="${label}"><ul>` +
+    `<nav class="g-pagination" aria-label="${label}"><ul>` +
     `<li>${previous}</li>` +
     `<li aria-current="page">${statusLabel}</li>` +
     `<li>${next}</li>` +
@@ -316,117 +296,62 @@ export function renderPagination({
 }
 
 /**
- * Render the one `<header>` landmark.
+ * Render the (initially invisible) status region the site script uses for
+ * short confirmations, and the carrier of every localized string the script
+ * needs: each one is a plain `data-*` attribute, so the script ships no
+ * language of its own. With JavaScript off it is an empty, inert live region.
  *
- * @param {object} options rendering options
- * @param {string} options.homeRoute the publication's own home route
- *   (`basePath`, joined)
- * @param {string} options.publicationName the validated publication title
- * @param {{route: string, alt: string} | undefined} options.logo an optional
- *   core logo image, always carrying alternative text
- * @param {string} [options.appearanceControlHtml] the already-rendered
- *   Light/Dark/System appearance control
- *   (`internal/appearance/controller-markup.js`'s `renderAppearanceControl`),
- *   inserted into the `header-actions` slot
- * @returns {string} the rendered header
- */
-export function renderHeader({
-  homeRoute,
-  publicationName,
-  logo,
-  appearanceControlHtml,
-}) {
-  const name = escapeHtml(publicationName);
-  const href = escapeHtml(homeRoute);
-  const logoHtml = logo
-    ? `<img src="${escapeHtml(logo.route)}" alt="${escapeHtml(logo.alt)}">`
-    : '';
-  return (
-    '<header>' +
-    `<a href="${href}">${logoHtml}<span>${name}</span></a>` +
-    renderSlot('header-actions', { html: appearanceControlHtml }) +
-    '</header>'
-  );
-}
-
-/**
- * Render the one `<footer>` landmark.
- *
- * @param {object} options rendering options
- * @param {string} options.publicationName the validated publication title
- * @param {string} options.footerNavHtml the already-rendered footer
- *   navigation (see {@link renderFooterNavigation})
- * @param {string} options.footerProfileHtml the already-rendered
- *   `footer-profile` slot content (footer card and/or author cards; may be
- *   empty when the publication authored neither)
- * @param {string | undefined} options.copyrightText an optional
- *   already-resolved copyright/license text line
- * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} options.messages
+ * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} messages
  *   the resolved message catalog
- * @returns {string} the rendered footer
+ * @returns {string} the toast element
  */
-export function renderFooter({
-  publicationName,
-  footerNavHtml,
-  footerProfileHtml,
-  copyrightText,
-  messages,
-}) {
-  const name = escapeHtml(publicationName);
-  const copyrightHtml = copyrightText
-    ? `<p>${escapeHtml(copyrightText)}</p>`
-    : '';
-  const attribution = escapeHtml(
-    /** @type {string} */ (messages.footerAttributionLabel),
-  );
-  return (
-    '<footer>' +
-    `<p>${name}</p>` +
-    footerNavHtml +
-    `<div data-gala-slot="footer-profile">${footerProfileHtml}</div>` +
-    renderSlot('footer-auxiliary') +
-    renderSlot('account-intent') +
-    renderSlot('conversation') +
-    renderSlot('newsletter') +
-    renderSlot('edition-selector') +
-    copyrightHtml +
-    `<p>${attribution}</p>` +
-    '</footer>'
-  );
+export function renderToast(messages) {
+  /** @type {readonly [string, string][]} */
+  const strings = [
+    ['search-label', 'searchButtonAriaLabel'],
+    ['search-placeholder', 'searchPlaceholderLabel'],
+    ['search-empty', 'searchEmptyLabel'],
+    ['search-unavailable', 'searchUnavailableLabel'],
+    ['copy', 'copyCodeLabel'],
+    ['copied', 'copiedLabel'],
+    ['link-copied', 'linkCopiedLabel'],
+    ['copy-blocked', 'copyBlockedLabel'],
+    ['code-selected', 'codeSelectedLabel'],
+    ['saved', 'savedLabel'],
+    ['unsaved', 'unsavedLabel'],
+  ];
+  const attributes = strings
+    .map(
+      ([name, key]) =>
+        ` data-${name}="${escapeHtml(/** @type {string} */ (messages[key]))}"`,
+    )
+    .join('');
+  return `<div class="g-toast" role="status" aria-live="polite"${attributes}></div>`;
 }
 
 /**
  * Compose one complete page body (everything inside `<body>`) from its
  * pre-rendered landmark parts. Every page kind in `internal/page-kinds.js`
  * funnels through this one function, so the landmark order and count (one
- * skip link, one header, one primary nav, one main, one footer) can never
- * drift between page kinds.
+ * skip link, one header carrying the one primary nav, one main, one footer)
+ * can never drift between page kinds.
  *
  * @param {object} options rendering options
  * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} options.messages
  *   the resolved message catalog
- * @param {string} options.headerHtml the already-rendered header
- * @param {string} options.navHtml the already-rendered primary navigation
+ * @param {string} options.headerHtml the already-rendered header (which
+ *   contains the primary navigation; see `internal/chrome.js`)
  * @param {string} options.footerHtml the already-rendered footer
- * @param {string} [options.breadcrumbHtml] an optional already-rendered
- *   breadcrumb, inserted before the page's own `<h1>`
- * @param {string} options.mainHtml the page kind's own inner markup, always
- *   starting with exactly one `<h1>`
+ * @param {string} options.mainHtml the page kind's own inner markup,
+ *   including its breadcrumb (when it has one) and exactly one `<h1>`
  * @returns {string} the complete `<body>` inner HTML
  */
-export function renderPageBody({
-  messages,
-  headerHtml,
-  navHtml,
-  footerHtml,
-  breadcrumbHtml,
-  mainHtml,
-}) {
+export function renderPageBody({ messages, headerHtml, footerHtml, mainHtml }) {
   return (
     renderSkipLink(messages) +
+    renderToast(messages) +
     headerHtml +
-    navHtml +
-    `<main id="main-content">${breadcrumbHtml ?? ''}${mainHtml}</main>` +
+    `<main id="main-content" class="g-main" tabindex="-1">${mainHtml}</main>` +
     footerHtml
   );
 }

package/src/core/internal/structured-data.js

@@ -0,0 +1,247 @@
+/**
+ * schema.org structured data (JSON-LD) for every generated page. One
+ * `<script type="application/ld+json">` carrying one `@graph` per page:
+ *
+ * - home: `WebSite` + `Blog` (no `SearchAction`: the site search is a
+ *   client-side dialog over a static index, there is no search-results URL
+ *   a crawler could call, and an invented one would be a false claim);
+ * - article: `BlogPosting` + `BreadcrumbList`;
+ * - tag / series / archive / paginated index: `CollectionPage` +
+ *   `BreadcrumbList`;
+ * - author: `ProfilePage` whose `mainEntity` is the `Person`;
+ * - authored page / publication profile: `WebPage` (+ `BreadcrumbList`).
+ *
+ * The block is data, never executed: a browser does not run a script whose
+ * `type` is not a JavaScript type, and the page CSP (`script-src 'self'`)
+ * does not govern it. The "exactly one executable script per page" rule
+ * therefore stays true: the one executable script is the `<script src>`; the
+ * data block is distinguished by its `type`.
+ */
+
+/** @type {number} Google's recommended maximum `headline` length. */
+const HEADLINE_MAX = 110;
+
+/**
+ * Serialize a JSON-LD document for safe embedding inside a `<script>`
+ * element: `<`, `>`, `&`, U+2028 and U+2029 become `\uXXXX` escapes, so the
+ * text can never close the element or start a comment, and stays valid
+ * JSON.
+ *
+ * @param {unknown} document the JSON-LD value
+ * @returns {string} compact, embed-safe JSON
+ */
+export function serializeJsonLd(document) {
+  return JSON.stringify(document).replace(
+    /[<>&\u2028\u2029]/g,
+    (character) =>
+      `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`,
+  );
+}
+
+/**
+ * @typedef {{url: string, width?: number, height?: number}} ImageInfo
+ * @typedef {{label: string, route?: string}} CrumbStep
+ */
+
+/**
+ * @param {ImageInfo | undefined} image
+ * @returns {Record<string, unknown> | undefined}
+ */
+function imageObject(image) {
+  return image
+    ? {
+        '@type': 'ImageObject',
+        url: image.url,
+        width: image.width,
+        height: image.height,
+      }
+    : undefined;
+}
+
+/**
+ * @param {string} text
+ * @param {number} max
+ * @returns {string}
+ */
+function bound(text, max) {
+  const characters = Array.from(text);
+  return characters.length > max
+    ? `${characters
+        .slice(0, max - 1)
+        .join('')
+        .trimEnd()}…`
+    : text;
+}
+
+/**
+ * Bind the JSON-LD builders to one build.
+ *
+ * @param {object} context
+ * @param {{title: string, description: string, defaultLanguage: string}} context.publication
+ * @param {(route: string) => string} context.absolute the absolute URL of a
+ *   `basePath`-joined route
+ * @param {ImageInfo | undefined} context.brandMark the appearance brand mark
+ * @returns {{
+ *   serialize: (graph: readonly unknown[]) => string,
+ *   home: (input: {posts: readonly {url: string, headline: string, datePublished: string}[]}) => unknown[],
+ *   article: (input: ArticleInput) => unknown[],
+ *   collection: (input: {name: string, description?: string, url: string, language: string, trail: readonly CrumbStep[], image?: ImageInfo}) => unknown[],
+ *   profile: (input: {name: string, description?: string, url: string, language: string, image?: ImageInfo, sameAs: readonly string[]}) => unknown[],
+ *   webPage: (input: {name: string, description?: string, url: string, language: string, trail: readonly CrumbStep[], dateModified?: string}) => unknown[],
+ * }}
+ */
+export function createStructuredData({ publication, absolute, brandMark }) {
+  const origin = absolute('/');
+  const organization = {
+    '@type': 'Organization',
+    '@id': `${origin}#organization`,
+    name: publication.title,
+    url: origin,
+    logo: imageObject(brandMark),
+  };
+
+  /**
+   * @param {readonly CrumbStep[]} trail
+   * @returns {Record<string, unknown>}
+   */
+  const breadcrumbs = (trail) => ({
+    '@type': 'BreadcrumbList',
+    itemListElement: trail.map((step, index) => ({
+      '@type': 'ListItem',
+      position: index + 1,
+      name: step.label,
+      item: step.route ? absolute(step.route) : undefined,
+    })),
+  });
+
+  return {
+    serialize: (graph) =>
+      serializeJsonLd({ '@context': 'https://schema.org', '@graph': graph }),
+
+    home: ({ posts }) => [
+      {
+        '@type': 'WebSite',
+        '@id': `${origin}#website`,
+        url: origin,
+        name: publication.title,
+        description: publication.description,
+        inLanguage: publication.defaultLanguage,
+        publisher: { '@id': organization['@id'] },
+        // No SearchAction: this site has no search-results URL (see module
+        // documentation).
+      },
+      {
+        '@type': 'Blog',
+        '@id': `${origin}#blog`,
+        url: origin,
+        name: publication.title,
+        description: publication.description,
+        inLanguage: publication.defaultLanguage,
+        publisher: { '@id': organization['@id'] },
+        blogPost: posts.map((post) => ({
+          '@type': 'BlogPosting',
+          headline: bound(post.headline, HEADLINE_MAX),
+          url: post.url,
+          datePublished: post.datePublished,
+        })),
+      },
+      organization,
+    ],
+
+    article: (input) => {
+      const authors = input.authors.map((author) => ({
+        '@type': 'Person',
+        name: author.name,
+        url: author.url,
+        sameAs: author.sameAs.length > 0 ? [...author.sameAs] : undefined,
+      }));
+      return [
+        {
+          '@type': 'BlogPosting',
+          '@id': `${input.url}#article`,
+          mainEntityOfPage: { '@type': 'WebPage', '@id': input.url },
+          url: input.url,
+          headline: bound(input.headline, HEADLINE_MAX),
+          description: input.description,
+          image: imageObject(input.image),
+          datePublished: input.datePublished,
+          dateModified: input.dateModified,
+          inLanguage: input.language,
+          author: authors.length === 1 ? authors[0] : authors,
+          publisher: organization,
+          keywords: input.tags.length > 0 ? input.tags.join(', ') : undefined,
+          isPartOf: input.series
+            ? {
+                '@type': 'CreativeWorkSeries',
+                name: input.series.name,
+                url: input.series.url,
+              }
+            : undefined,
+        },
+        breadcrumbs(input.trail),
+      ];
+    },
+
+    collection: ({ name, description, url, language, trail, image }) => [
+      {
+        '@type': 'CollectionPage',
+        '@id': `${url}#page`,
+        url,
+        name,
+        description,
+        inLanguage: language,
+        primaryImageOfPage: imageObject(image),
+        isPartOf: { '@id': `${origin}#website` },
+      },
+      breadcrumbs(trail),
+    ],
+
+    profile: ({ name, description, url, language, image, sameAs }) => [
+      {
+        '@type': 'ProfilePage',
+        '@id': `${url}#page`,
+        url,
+        name,
+        inLanguage: language,
+        mainEntity: {
+          '@type': 'Person',
+          '@id': `${url}#person`,
+          name,
+          url,
+          description,
+          image: imageObject(image),
+          sameAs: sameAs.length > 0 ? [...sameAs] : undefined,
+        },
+      },
+    ],
+
+    webPage: ({ name, description, url, language, trail, dateModified }) => [
+      {
+        '@type': 'WebPage',
+        '@id': `${url}#page`,
+        url,
+        name,
+        description,
+        inLanguage: language,
+        dateModified,
+        isPartOf: { '@id': `${origin}#website` },
+      },
+      ...(trail.length > 0 ? [breadcrumbs(trail)] : []),
+    ],
+  };
+}
+
+/**
+ * @typedef {object} ArticleInput
+ * @property {string} url the article's absolute URL
+ * @property {string} headline
+ * @property {string} [description]
+ * @property {ImageInfo} [image]
+ * @property {string} datePublished
+ * @property {string} dateModified
+ * @property {string} language
+ * @property {readonly {name: string, url: string, sameAs: readonly string[]}[]} authors
+ * @property {readonly string[]} tags
+ * @property {{name: string, url: string}} [series]
+ * @property {readonly CrumbStep[]} trail
+ */