@rathnasgala2/template 2.2.0 → 3.0.0

package/src/core/internal/chrome.js

@@ -0,0 +1,199 @@
+/**
+ * Site chrome: the one `<header>` and the one `<footer>` landmark every page
+ * is composed with (see `internal/skeleton.js`'s landmark contract). Markup
+ * mirrors the approved design reference and reads completely with JavaScript
+ * off; the optional site script only reveals the search button (rendered
+ * `hidden`) and enhances the rest.
+ */
+
+import { escapeHtml, renderNavItem, renderSlot } from './skeleton.js';
+import { icon } from './icons.js';
+import { monogram, renderImage } from './components.js';
+
+/** @type {Readonly<Record<string, string>>} */
+const SOCIAL_ICONS = Object.freeze({
+  email: 'mail',
+  github: 'code',
+  website: 'link',
+});
+
+/**
+ * @param {string} name publication title
+ * @param {{url: string, width?: number, height?: number} | undefined} mark
+ *   the brand mark image, if any
+ * @returns {string} the brand mark element
+ */
+function renderMark(name, mark) {
+  return (
+    `<span class="g-mark" aria-hidden="true">` +
+    (mark
+      ? renderImage({ image: mark, alt: '', eager: true })
+      : escapeHtml(monogram(name))) +
+    `</span>`
+  );
+}
+
+/**
+ * Render the one `<header>` landmark.
+ *
+ * @param {object} options rendering options
+ * @param {string} options.homeRoute the publication's own home route
+ * @param {string} options.publicationName the validated publication title
+ * @param {string} options.tagline the publication description
+ * @param {{url: string, width?: number, height?: number} | undefined} options.brandMark
+ *   the appearance brand mark image; the monogram is used when absent
+ * @param {string} options.navHtml the already-rendered primary navigation
+ * @param {readonly import('../../../types/index.d.ts').NavigationItem[]} options.navItems
+ *   the same items, rendered again as the mobile menu's link list
+ * @param {string | undefined} options.currentRoute the page's joined route
+ * @param {string} options.urlPrefix the `baseUrl` path prefix
+ * @param {string} options.searchIndexHref the static search index URL, read
+ *   by the site script
+ * @param {string} [options.appearanceControlHtml] the already-rendered
+ *   appearance control, inserted into the `header-actions` slot
+ * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} options.messages
+ * @returns {string} the rendered header
+ */
+export function renderHeader({
+  homeRoute,
+  publicationName,
+  tagline,
+  brandMark,
+  navHtml,
+  navItems,
+  currentRoute,
+  urlPrefix,
+  searchIndexHref,
+  appearanceControlHtml,
+  messages,
+}) {
+  const label = (/** @type {string} */ key) =>
+    escapeHtml(/** @type {string} */ (messages[key]));
+  const menu =
+    navItems.length > 0
+      ? `<details class="g-menu"><summary>${icon('menu')}<span class="g-sr">${label('menuSummaryLabel')}</span></summary>` +
+        `<ul>${navItems.map((item) => renderNavItem(item, currentRoute, urlPrefix)).join('')}</ul></details>`
+      : '';
+  return (
+    `<header class="g-header"><div class="g-wrap g-header-row">` +
+    `<a class="g-brand" href="${escapeHtml(homeRoute)}">${renderMark(publicationName, brandMark)}` +
+    `<span class="g-brand-text"><span class="g-brand-name">${escapeHtml(publicationName)}</span>` +
+    `<span class="g-brand-tag">${escapeHtml(tagline)}</span></span></a>` +
+    navHtml +
+    `<div class="g-actions">` +
+    `<button class="g-search-btn" type="button" hidden data-action="search" data-search-index="${escapeHtml(searchIndexHref)}" aria-label="${label('searchButtonAriaLabel')}">` +
+    `${icon('search')}<span>${label('searchButtonLabel')}</span></button>` +
+    renderSlot('header-actions', { html: appearanceControlHtml }) +
+    menu +
+    `</div></div></header>`
+  );
+}
+
+/**
+ * @param {readonly unknown[]} socialLinks `publication.socialLinks`
+ * @param {string} rssHref the RSS feed URL
+ * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} messages
+ * @returns {string} the `<ul>` of icon links
+ */
+function renderSocialLinks(socialLinks, rssHref, messages) {
+  const items = socialLinks.flatMap((entry) => {
+    const link = /** @type {Record<string, unknown>} */ (entry);
+    if (typeof link?.uri !== 'string') return [];
+    const type = typeof link.type === 'string' ? link.type : 'other';
+    const text = typeof link.label === 'string' ? link.label : type;
+    return [
+      { href: link.uri, text, iconName: SOCIAL_ICONS[type] ?? 'upright' },
+    ];
+  });
+  items.push({
+    href: rssHref,
+    text: /** @type {string} */ (messages.rssFeedLabel),
+    iconName: 'rss',
+  });
+  return (
+    `<ul class="g-social">` +
+    items
+      .map(
+        (item) =>
+          `<li><a class="g-icon-btn" href="${escapeHtml(item.href)}" aria-label="${escapeHtml(item.text)}" title="${escapeHtml(item.text)}">${icon(item.iconName)}</a></li>`,
+      )
+      .join('') +
+    `</ul>`
+  );
+}
+
+/**
+ * Render the one `<footer>` landmark.
+ *
+ * @param {object} options rendering options
+ * @param {string} options.homeRoute the publication's own home route
+ * @param {string} options.publicationName the validated publication title
+ * @param {string} options.description the publication description
+ * @param {{url: string, width?: number, height?: number} | undefined} options.brandMark the brand mark image
+ * @param {readonly unknown[]} options.socialLinks `publication.socialLinks`
+ * @param {string} options.rssHref the RSS feed URL
+ * @param {readonly import('../../../types/index.d.ts').NavigationItem[]} options.primaryItems
+ *   the primary navigation items, repeated as the "Explore" column
+ * @param {readonly import('../../../types/index.d.ts').NavigationItem[]} options.footerItems
+ *   `navigationNormalized.footerItems`
+ * @param {string} options.urlPrefix the `baseUrl` path prefix
+ * @param {string} options.authorHtml the already-rendered author mini
+ *   profile (may be empty)
+ * @param {string} options.footerProfileHtml the already-rendered footer card
+ *   body (may be empty)
+ * @param {string | undefined} options.copyrightText the copyright line
+ * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} options.messages
+ * @returns {string} the rendered footer
+ */
+export function renderFooter({
+  homeRoute,
+  publicationName,
+  description,
+  brandMark,
+  socialLinks,
+  rssHref,
+  primaryItems,
+  footerItems,
+  urlPrefix,
+  authorHtml,
+  footerProfileHtml,
+  copyrightText,
+  messages,
+}) {
+  const label = (/** @type {string} */ key) =>
+    escapeHtml(/** @type {string} */ (messages[key]));
+  /**
+   * @param {string} labelKey
+   * @param {readonly import('../../../types/index.d.ts').NavigationItem[]} items
+   * @returns {string}
+   */
+  const column = (labelKey, items) =>
+    items.length === 0
+      ? ''
+      : `<nav class="g-footer-col" aria-label="${label(labelKey)}"><p class="g-label">${label(labelKey)}</p>` +
+        `<ul>${items.map((item) => renderNavItem(item, undefined, urlPrefix)).join('')}</ul></nav>`;
+  return (
+    `<footer class="g-footer"><div class="g-wrap g-footer-grid">` +
+    `<div class="g-footer-brand">` +
+    `<a class="g-brand" href="${escapeHtml(homeRoute)}">${renderMark(publicationName, brandMark)}` +
+    `<span class="g-brand-name">${escapeHtml(publicationName)}</span></a>` +
+    `<p class="g-footer-about">${escapeHtml(description)}</p>` +
+    renderSocialLinks(socialLinks, rssHref, messages) +
+    `</div>` +
+    column('exploreColumnLabel', primaryItems) +
+    column('footerNavigationLabel', footerItems) +
+    `<div class="g-footer-col">` +
+    renderSlot('footer-profile', { html: authorHtml + footerProfileHtml }) +
+    `</div>` +
+    `</div>` +
+    renderSlot('footer-auxiliary') +
+    renderSlot('account-intent') +
+    renderSlot('conversation') +
+    renderSlot('newsletter') +
+    renderSlot('edition-selector') +
+    `<div class="g-wrap g-footer-base">` +
+    (copyrightText ? `<span>${escapeHtml(copyrightText)}</span>` : '') +
+    `<span>${label('footerAttributionLabel')}</span>` +
+    `</div></footer>`
+  );
+}

package/src/core/internal/components.js

@@ -0,0 +1,379 @@
+/**
+ * Shared, template-owned presentational components used by the page kinds
+ * (`internal/page-kinds.js`) and the site chrome (`internal/chrome.js`):
+ * chips, meta lines, bylines, cards and the optional newsletter panel.
+ *
+ * Every component is a pure `(data) -> HTML string` function over already
+ * validated build-input records. Every link is a real `href` (the pages read
+ * completely with JavaScript off); the optional site script only enhances.
+ *
+ * Hook naming convention: every class this module emits is a `g-*` class.
+ * Each distinct class is one published public theme hook, listed in
+ * `internal/appearance/styling-contract.js`'s `COMPONENT_CLASSES`; the
+ * contract drift test fails if a rendered `g-*` class is unpublished or a
+ * published one is never rendered.
+ */
+
+import { escapeHtml } from './skeleton.js';
+import { icon } from './icons.js';
+import { joinBasePathAndRoute } from './route.js';
+import { resolveOriginalDerivativePath } from './seo.js';
+
+/** Reading speed used for every reading-time estimate. */
+export const WORDS_PER_MINUTE = 230;
+
+/**
+ * @param {string} html sanitized body HTML
+ * @returns {string} its text content, whitespace-collapsed
+ */
+export function plainText(html) {
+  return html
+    .replace(/<[^>]*>/g, ' ')
+    .replace(/&(?:[a-z]+|#\d+|#x[0-9a-f]+);/gi, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * Reading time in whole minutes: body words at 230 words per minute,
+ * rounded up, never less than one minute.
+ *
+ * @param {string} bodyHtml sanitized body HTML
+ * @returns {number} minutes (at least 1)
+ */
+export function readingMinutes(bodyHtml) {
+  const text = plainText(bodyHtml);
+  const words = text === '' ? 0 : text.split(' ').length;
+  return Math.max(1, Math.ceil(words / WORDS_PER_MINUTE));
+}
+
+/**
+ * Extract the `<h2 id="...">` entries of a sanitized body, in order, for the
+ * article contents list.
+ *
+ * @param {string} bodyHtml sanitized body HTML
+ * @returns {{id: string, text: string}[]} each h2's id and plain text
+ */
+export function extractH2Headings(bodyHtml) {
+  /** @type {{id: string, text: string}[]} */
+  const headings = [];
+  for (const match of bodyHtml.matchAll(
+    /<h2\b[^>]*\bid="([^"]+)"[^>]*>([\s\S]*?)<\/h2>/g,
+  )) {
+    headings.push({ id: match[1], text: plainText(match[2]) });
+  }
+  return headings;
+}
+
+/**
+ * Up to two initials from a display name, uppercased (the monogram and the
+ * image-less avatar fallback).
+ *
+ * @param {string} name a publication title or author display name
+ * @returns {string} one or two characters
+ */
+export function monogram(name) {
+  const words = name.split(/\s+/).filter(Boolean);
+  const picked = words.length > 1 ? [words[0], words[1]] : [words[0] ?? ''];
+  const letters = picked.map((word) => Array.from(word)[0] ?? '').join('');
+  return (letters || '?').toUpperCase();
+}
+
+/**
+ * Render the optional newsletter panel: a call-to-action link to the
+ * sign-up page the author configured in publication settings, never a form.
+ * Reads `publication.newsletter` defensively: absent, or without an
+ * `https:` `url`, renders nothing.
+ *
+ * @param {object} options rendering options
+ * @param {unknown} options.newsletter `publication.newsletter` (may be
+ *   undefined on a build input that predates the field)
+ * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} options.messages
+ *   the resolved message catalog
+ * @returns {string} the panel markup, or an empty string
+ */
+export function renderNewsletterPanel({ newsletter, messages }) {
+  const value = /** @type {Record<string, unknown> | undefined} */ (
+    newsletter && typeof newsletter === 'object' ? newsletter : undefined
+  );
+  if (!value || typeof value.url !== 'string' || !/^https:\/\//.test(value.url))
+    return '';
+  const title =
+    typeof value.title === 'string' && value.title !== ''
+      ? value.title
+      : /** @type {string} */ (messages.newsletterLabel);
+  const text = typeof value.text === 'string' ? value.text : '';
+  return (
+    `<section class="g-wrap g-newsletter" aria-labelledby="newsletter-title">` +
+    `<div class="g-panel">` +
+    `<div class="g-panel-copy">` +
+    `<p class="g-label">${icon('mail')}${escapeHtml(/** @type {string} */ (messages.newsletterLabel))}</p>` +
+    `<h2 id="newsletter-title">${escapeHtml(title)}</h2>` +
+    (text ? `<p>${escapeHtml(text)}</p>` : '') +
+    `</div>` +
+    `<a class="g-btn" href="${escapeHtml(value.url)}" rel="noopener">${escapeHtml(/** @type {string} */ (messages.newsletterActionLabel))}${icon('arrow')}</a>` +
+    `</div></section>`
+  );
+}
+
+/**
+ * Build the resolver every component uses to turn an image reference into
+ * its emitted URL (the media pipeline's processed original), or `undefined`
+ * when the pipeline produced no derivative for it.
+ *
+ * @param {object} options
+ * @param {readonly {path: string, mediaType: string}[]} options.mediaAssets
+ *   the media pipeline's finished `assets` list
+ * @param {string} options.publicBasePath the public base path
+ * @returns {(ref: {path: string, sourceDigest: string} | undefined) => string | undefined}
+ */
+export function createMediaUrl({ mediaAssets, publicBasePath }) {
+  return (ref) => {
+    const derivative = resolveOriginalDerivativePath(mediaAssets, ref);
+    return derivative
+      ? joinBasePathAndRoute(publicBasePath, `/${derivative}`)
+      : undefined;
+  };
+}
+
+/**
+ * Build the resolver for a processed image's URL plus its pixel dimensions
+ * (from the media pipeline's own `dimensions` map), so every `<img>` can
+ * carry `width`/`height` and reserve its space before the file loads.
+ *
+ * @param {object} options
+ * @param {readonly {path: string, mediaType: string}[]} options.mediaAssets
+ * @param {string} options.publicBasePath the public base path
+ * @param {Readonly<Record<string, {width: number, height: number}>>} [options.mediaDimensions]
+ *   the pipeline's dimensions, keyed by derivative path
+ * @returns {(ref: {path: string, sourceDigest: string} | undefined) => ({url: string, width?: number, height?: number}) | undefined}
+ */
+export function createMediaImage({
+  mediaAssets,
+  publicBasePath,
+  mediaDimensions = {},
+}) {
+  return (ref) => {
+    const derivative = resolveOriginalDerivativePath(mediaAssets, ref);
+    if (!derivative) return undefined;
+    const size = mediaDimensions[derivative];
+    return {
+      url: joinBasePathAndRoute(publicBasePath, `/${derivative}`),
+      width: size?.width,
+      height: size?.height,
+    };
+  };
+}
+
+/**
+ * Render one `<img>` with intrinsic `width`/`height` (when known) and the
+ * right loading hints: a priority image (the page's largest above-the-fold
+ * image) is `fetchpriority="high"` and never lazy; every other image is
+ * `loading="lazy" decoding="async"`.
+ *
+ * @param {object} options
+ * @param {{url: string, width?: number, height?: number}} options.image
+ * @param {string} options.alt the alternative text (empty when decorative)
+ * @param {string} [options.className]
+ * @param {boolean} [options.priority]
+ * @param {boolean} [options.eager] above-the-fold but not the page's main
+ *   image (the header brand mark): no `loading="lazy"`
+ * @param {{width: number, height: number}} [options.fallbackSize] used when
+ *   the pipeline reported no dimensions
+ * @returns {string} the `<img>` element
+ */
+export function renderImage({
+  image,
+  alt,
+  className,
+  priority = false,
+  eager = false,
+  fallbackSize,
+}) {
+  const width = image.width ?? fallbackSize?.width;
+  const height = image.height ?? fallbackSize?.height;
+  return (
+    `<img${className ? ` class="${className}"` : ''} src="${escapeHtml(image.url)}" alt="${escapeHtml(alt)}"` +
+    (width && height ? ` width="${width}" height="${height}"` : '') +
+    (priority
+      ? ' fetchpriority="high" decoding="async"'
+      : eager
+        ? ' decoding="async"'
+        : ' loading="lazy" decoding="async"') +
+    `>`
+  );
+}
+
+/**
+ * Add `loading="lazy" decoding="async"` to every `<img>` in an
+ * already-sanitized body. Applied at render time only: the body's own
+ * digest is over the stored bytes and is never recomputed.
+ *
+ * @param {string} bodyHtml sanitized body HTML
+ * @returns {string} the body with loading hints on its images
+ */
+export function lazyBodyImages(bodyHtml) {
+  return bodyHtml.replace(
+    /<img\b(?![^>]*\bloading=)/g,
+    '<img loading="lazy" decoding="async"',
+  );
+}
+
+/**
+ * @typedef {object} ComponentContext
+ * @property {Readonly<Record<string, string | ((...args: string[]) => string)>>} messages
+ * @property {(route: string) => string} site joins a canonical route with
+ *   the public base path
+ * @property {(ref: {path: string, sourceDigest: string} | undefined) => ({url: string, width?: number, height?: number}) | undefined} mediaImage
+ *   the emitted URL and dimensions of an image reference's processed derivative
+ * @property {(author: import('../../../types/index.d.ts').AuthorNormalized) => string} authorHref
+ *   the author page's joined route
+ * @property {ReadonlyMap<string, import('../../../types/index.d.ts').AuthorNormalized>} authorsById
+ * @property {(record: import('../../../types/index.d.ts').ContentBuildRecord) => string} recordHref
+ *   the record's own joined route
+ * @property {(tag: string) => string} tagHref
+ */
+
+/**
+ * Build the component renderers bound to one build's context.
+ *
+ * @param {ComponentContext} context
+ * @returns {{text: (key: string) => string, call: (key: string, ...args: string[]) => string, chip: (tag: string) => string, meta: (record: import('../../../types/index.d.ts').ContentBuildRecord, showUpdated?: boolean) => string, avatar: (author: import('../../../types/index.d.ts').AuthorNormalized | undefined) => string, byline: (record: import('../../../types/index.d.ts').ContentBuildRecord, showUpdated?: boolean) => string, card: (record: import('../../../types/index.d.ts').ContentBuildRecord, options?: {partLabel?: string, headingLevel?: number}, variant?: 'grid' | 'row') => string, recordAuthors: (record: import('../../../types/index.d.ts').ContentBuildRecord) => import('../../../types/index.d.ts').AuthorNormalized[]}}
+ *   the bound renderers
+ */
+export function createComponents(context) {
+  const { messages, mediaImage, authorsById, recordHref, tagHref } = context;
+  /**
+   * @param {string} key a plain message key
+   * @returns {string} the escaped message text
+   */
+  const text = (key) => escapeHtml(/** @type {string} */ (messages[key]));
+  /**
+   * @param {string} key a function message key
+   * @param {...string} args the message function's arguments
+   * @returns {string} the escaped message text
+   */
+  const call = (key, ...args) =>
+    escapeHtml(
+      /** @type {(...a: string[]) => string} */ (messages[key])(...args),
+    );
+
+  /**
+   * @param {string} tag
+   * @returns {string}
+   */
+  const chip = (tag) =>
+    `<a class="g-chip" href="${escapeHtml(tagHref(tag))}">${escapeHtml(tag)}</a>`;
+
+  /**
+   * @param {import('../../../types/index.d.ts').ContentBuildRecord} record
+   * @param {boolean} [showUpdated] append the "Updated" date when the
+   *   record was modified after publication
+   * @returns {string}
+   */
+  const meta = (record, showUpdated = false) => {
+    const { publishedAt, updatedAt } = record.frontmatter;
+    const formatDate = /** @type {(iso: string) => string} */ (
+      messages.formatDate
+    );
+    const updated =
+      showUpdated && updatedAt && updatedAt !== publishedAt
+        ? `<span class="g-dot" aria-hidden="true"></span><time datetime="${escapeHtml(updatedAt)}">` +
+          `${call('updatedLabel', formatDate(updatedAt))}</time>`
+        : '';
+    return (
+      `<span class="g-meta"><time datetime="${escapeHtml(publishedAt)}">` +
+      `${call('formatDate', publishedAt)}</time>` +
+      `<span class="g-dot" aria-hidden="true"></span>` +
+      `<span>${icon('clock')}${call('readingTimeLabel', String(readingMinutes(record.body)))}</span>${updated}</span>`
+    );
+  };
+
+  /**
+   * @param {import('../../../types/index.d.ts').AuthorNormalized | undefined} author
+   * @returns {string}
+   */
+  const avatar = (author) => {
+    const image = mediaImage(author?.avatar);
+    return image
+      ? renderImage({
+          image,
+          alt: '',
+          className: 'g-avatar',
+          fallbackSize: { width: 40, height: 40 },
+        })
+      : `<span class="g-avatar" aria-hidden="true">${escapeHtml(monogram(author?.displayName ?? ''))}</span>`;
+  };
+
+  /**
+   * @param {import('../../../types/index.d.ts').ContentBuildRecord} record
+   * @returns {import('../../../types/index.d.ts').AuthorNormalized[]}
+   */
+  const recordAuthors = (record) =>
+    record.frontmatter.authorIds.flatMap((id) => {
+      const author = authorsById.get(id);
+      return author ? [author] : [];
+    });
+
+  /**
+   * @param {import('../../../types/index.d.ts').ContentBuildRecord} record
+   * @param {boolean} [showUpdated] show the "Updated" date (article head)
+   * @returns {string}
+   */
+  const byline = (record, showUpdated = false) => {
+    const authors = recordAuthors(record);
+    const names = authors
+      .map(
+        (author) =>
+          `<a href="${escapeHtml(context.authorHref(author))}">${escapeHtml(author.displayName)}</a>`,
+      )
+      .join(', ');
+    return (
+      `<div class="g-byline">${avatar(authors[0])}` +
+      `<div class="g-byline-text"><span>${names}</span>${meta(record, showUpdated)}</div></div>`
+    );
+  };
+
+  /**
+   * @param {import('../../../types/index.d.ts').ContentBuildRecord} record
+   * @param {{partLabel?: string, headingLevel?: number}} [options] an
+   *   optional series part label and the title's heading level (default 3)
+   * @param {'grid' | 'row'} [variant]
+   * @returns {string}
+   */
+  const card = (record, options = {}, variant = 'grid') => {
+    const fm = record.frontmatter;
+    const href = escapeHtml(recordHref(record));
+    const hero = mediaImage(fm.hero?.file);
+    const media = hero
+      ? `<figure class="g-card-media">${renderImage({ image: hero, alt: fm.hero?.role === 'decorative' ? '' : (fm.hero?.alt ?? '') })}</figure>`
+      : `<div class="g-card-placeholder" aria-hidden="true">${icon('sparkle')}</div>`;
+    const seriesTag = options.partLabel
+      ? `<span class="g-series-tag">${icon('book')}${escapeHtml(options.partLabel)}</span>`
+      : '';
+    const firstTag = fm.tags[0];
+    return (
+      `<article class="g-card${variant === 'row' ? ' g-card-row' : ''}">` +
+      media +
+      `<div class="g-card-body">` +
+      `<div class="g-card-top">${firstTag ? chip(firstTag) : ''}${seriesTag}</div>` +
+      `<h${options.headingLevel ?? 3}><a class="g-card-link" href="${href}">${escapeHtml(fm.title)}</a></h${options.headingLevel ?? 3}>` +
+      (fm.description
+        ? `<p class="g-card-excerpt">${escapeHtml(fm.description)}</p>`
+        : '') +
+      `<div class="g-card-foot">${meta(record)}<span aria-hidden="true">${icon('arrow')}</span></div>` +
+      `</div></article>`
+    );
+  };
+
+  return {
+    text,
+    call,
+    chip,
+    meta,
+    avatar,
+    byline,
+    card,
+    recordAuthors,
+  };
+}

package/src/core/internal/eleventy-render.js

@@ -143,13 +143,22 @@ const SKELETON_LAYOUT_SOURCE = [
   '<meta property="og:site_name" content="{{ siteName }}">',
   '{% if canonicalUrl %}<meta property="og:url" content="{{ canonicalUrl }}">{% endif %}',
   '<meta property="og:type" content="{{ ogType }}">',
-  '<meta property="og:title" content="{{ title }}">',
+  '<meta property="og:title" content="{{ ogTitle }}">',
   '{% if description %}<meta property="og:description" content="{{ description }}">{% endif %}',
-  '{% if ogImage %}<meta property="og:image" content="{{ ogImage }}">{% endif %}',
+  '{% if ogImage %}<meta property="og:image" content="{{ ogImage }}">{% if ogImageWidth %}<meta property="og:image:width" content="{{ ogImageWidth }}">{% endif %}{% if ogImageHeight %}<meta property="og:image:height" content="{{ ogImageHeight }}">{% endif %}{% if ogImageAlt %}<meta property="og:image:alt" content="{{ ogImageAlt }}">{% endif %}{% endif %}',
+  '{% if articlePublished %}<meta property="article:published_time" content="{{ articlePublished }}">{% endif %}',
+  '{% if articleModified %}<meta property="article:modified_time" content="{{ articleModified }}">{% endif %}',
+  '{% for authorUrl in articleAuthors %}<meta property="article:author" content="{{ authorUrl }}">{% endfor %}',
+  '{% for articleTag in articleTags %}<meta property="article:tag" content="{{ articleTag }}">{% endfor %}',
   '<meta name="twitter:card" content="{{ twitterCard }}">',
-  '<meta name="twitter:title" content="{{ title }}">',
+  '<meta name="twitter:title" content="{{ ogTitle }}">',
   '{% if description %}<meta name="twitter:description" content="{{ description }}">{% endif %}',
-  '{% if ogImage %}<meta name="twitter:image" content="{{ ogImage }}">{% endif %}',
+  '{% if ogImage %}<meta name="twitter:image" content="{{ ogImage }}">{% if ogImageAlt %}<meta name="twitter:image:alt" content="{{ ogImageAlt }}">{% endif %}{% endif %}',
+  // One JSON-LD data block per page (`internal/structured-data.js`). Its
+  // `type` is not a JavaScript type, so a browser never executes it and the
+  // CSP `script-src` does not govern it; `jsonLd` is already escaped for
+  // embedding (`<`, `>`, `&`, U+2028/9 as \uXXXX).
+  '{% if jsonLd %}<script type="application/ld+json">{{ jsonLd | safe }}</script>{% endif %}',
   '<link rel="alternate" type="application/atom+xml" href="{{ atomFeedUrl }}" title="{{ siteName }}">',
   '<link rel="alternate" type="application/rss+xml" href="{{ rssFeedUrl }}" title="{{ siteName }}">',
   // TPL-H3/TPL-M7: the template-owned gala-base layer's own `<link>`,