template.mjs

// Phase 4 TEMPLATE: wrap each page's renderedContent in the just-the-docs
// layout chrome. Direct string concatenation replaces Liquid; HTML
// compression replaces vendor/compress.html. See builder/PLAN-4.md.
//
// Inputs: each page's Phase 1/2/3 fields (frontmatter, permalink, srcRel,
// renderedContent, navPath, breadcrumbs, children, navLevels, seoTitle,
// seoFullTitle, seoCanonical, seoIsHome) plus site.{config, navTree,
// seoSiteTitle, seoLogoUrl}. Mutates each page in place, adding page.html
// (a complete HTML document) -- except book.html, which Phase 8 handles
// directly from page.renderedContent.
//
// Ports the project shadows under docs/_includes (head, head_seo, head_custom,
// title, components/{breadcrumbs,children_nav,footer,site_nav,nav/links},
// footer_custom) plus the upstream just-the-docs theme's components/{sidebar,
// header,aux_nav,search_header,search_footer}, _includes/icons/*, and the
// _layouts/default.html outer wrap. Activation CSS ports
// _includes/css/activation.scss.liquid.

import { replaceOutsideCode } from "./code-guard.mjs";
import { compressHtml } from "./compress.mjs";
import { stripHtml } from "./seo.mjs";
import { absoluteUrl, relativeUrl } from "./url.mjs";
import { escapeMarkupAndQuotes } from "./escape.mjs";
import { formatDate } from "./strftime.mjs";

export async function templatePhase(pages, site, initData) {
  if (site.config.just_the_docs?.collections) {
    throw new Error(
      "site.config.just_the_docs.collections is set; Phase 4 (and Phase 2) " +
        "do not support collections. Update _config.yml or extend the port.",
    );
  }

  const init = initData ?? buildInit(site);

  await Promise.all(
    pages.map(async (page) => {
      if (page.frontmatter.layout === "book-combined") return;
      page.html = templatePage(page, site, init);
    }),
  );
}

// Config-only chrome fields -- no nav-tree dependency. Exported for the
// scheduler's buildInit task so it can run after discover, in parallel
// with nav. Does not include sidebar; that is rendered by nav and merged
// by dispatch.
export function buildInitConfig(site) {
  return {
    svgSprites: buildSvgSprites(site.config),
    header: renderHeader(site),
    searchFooter: renderSearchFooter(site),
    faviconLink: buildFaviconLink(site.config),
    gaSnippet: buildGaSnippet(site.config),
    searchEnabled: site.config.search_enabled !== false,
  };
}

// Full init -- used by the templatePhase fallback (no scheduler) and tools.
export { buildInit as buildInitFn, renderSidebar };
function buildInit(site) {
  return { ...buildInitConfig(site), sidebar: renderSidebar(site) };
}

// ---------- §5.1 templatePage --------------------------------------------

function templatePage(page, site, init) {
  const supportedLayouts = new Set(["default", "home", "page", undefined, null]);
  const layout = page.frontmatter.layout;
  if (!supportedLayouts.has(layout) && layout !== "book-combined") {
    throw new Error(`Unsupported layout "${layout}" on ${page.srcRel}`);
  }

  const lang = site.config.lang ?? "en-US";
  const baseurl = String(site.config.baseurl ?? "");

  // Compose. The literal newlines + indentation are for source clarity;
  // compress collapses them to single spaces. The body assembly mirrors
  // _layouts/default.html: skip-to-main link, icon sprite, sidebar,
  // <div class="main">, header, breadcrumbs, <main> wrapping body +
  // children-nav, footer (section-links + actions + legal), then the
  // per-page-search-footer.

  // Collected by injectAnchorHeadings as it walks the headings, then spent by
  // renderSectionLinks, which renderFooter places at the top of the footer.
  const sectionHeadings = [];
  const mainHtml = injectAnchorHeadings(page.renderedContent, sectionHeadings);

  const html =
    `<!DOCTYPE html>\n` +
    `<html lang="${escapeMarkupAndQuotes(lang)}">\n` +
    renderHead(page, site, init) +
    `<body>\n` +
    `  <a class="skip-to-main" href="#main-content">Skip to main content</a>\n` +
    `  <div id="a11y-status" class="sr-only" aria-live="polite" aria-atomic="true"></div>\n` +
    init.svgSprites +
    `\n` +
    (page.hasFigure ? FIGURE_SPRITE + `\n` : "") +
    init.sidebar +
    `\n` +
    `  <div class="main" id="page-top">\n` +
    init.header +
    `\n` +
    `    <div class="main-content-wrap">\n` +
    renderBreadcrumbs(page, baseurl) +
    `      <div id="main-content" class="main-content">\n` +
    `        <main>\n` +
    mainHtml +
    renderChildrenNav(page, baseurl) +
    `        </main>\n` +
    renderFooter(page, site, renderSectionLinks(sectionHeadings)) +
    `      </div>\n` +
    `    </div>\n` +
    (init.searchEnabled ? init.searchFooter + `\n` : "") +
    `  </div>\n` +
    `</body>\n` +
    `</html>\n`;

  return compressHtml(html);
}

// ---------- §5.2 renderHead ----------------------------------------------

// The two roman faces every page uses, started before the stylesheet that
// declares them has even arrived. Without this the UA cannot discover a
// @font-face src until the CSS has downloaded and parsed, which puts the
// whole font fetch one round trip later and widens the `font-display: swap`
// flash correspondingly.
//
// The italic faces are deliberately NOT preloaded. Preload fetches
// unconditionally, so a page with no italic text would pay 166 KB for
// nothing; the CSS discovers them on demand, which is the right behaviour
// for a face most pages use lightly.
//
// `crossorigin` is required even though these are same-origin: font fetches
// are always made in CORS mode, and a preload whose mode does not match the
// later @font-face fetch is not reused -- the browser downloads the file
// twice and warns about it in the console.
const PRELOAD_FONTS = ["/assets/fonts/inter-variable.woff2", "/assets/fonts/cascadia-mono-variable.woff2"];

function fontPreloads(bu) {
  return PRELOAD_FONTS.map(
    (f) =>
      `  <link rel="preload" href="${escapeMarkupAndQuotes(relativeUrl(f, bu))}" as="font" ` +
      `type="font/woff2" crossorigin>\n`,
  ).join("");
}

function renderHead(page, site, init) {
  // Order matches docs/_includes/head.html: charset, X-UA, theme
  // early script, theme-toggle.js (deferred), font preloads, CSS combined,
  // CSS head-nav, activation <style>, GA snippet, lunr.min.js (when search on),
  // just-the-docs.js, viewport, head_seo, head_custom (favicon link).
  // The favicon AFTER head_seo is intentional (D2 of PLAN-4).
  // The `<meta IE=Edge>` is directly followed by `<script>` (no
  // whitespace) because head.html has `{%- comment -%}...{%- endcomment -%}`
  // between them that strips surrounding whitespace.
  // The early script applies the theme before first paint: a `?theme=light`
  // or `dark` in the URL, which the help add-in passes to match the IDE and
  // which is kept in sessionStorage for the pages reached from it, else the
  // reader's stored choice. theme-toggle.js reads the same two keys.
  // It also marks the page for the help add-in's pane: `?pane=1`, kept in
  // sessionStorage the same way, sets `data-pane`, and custom.scss then hides
  // the site's navigation and header.
  // Where storage throws, as it does in the frame of the add-in's detached
  // window (a frame of another site than its `data:` page), both are kept in
  // the frame's window.name instead, as `tbdocs:<theme>:<1 for pane>`, which
  // a navigation inside the frame keeps; it is written only by a page given
  // either parameter, and read only when storage throws.
  const bu = String(site.config.baseurl ?? "");
  return (
    `<head>\n` +
    `  <meta charset="UTF-8">\n` +
    `  <meta http-equiv="X-UA-Compatible" content="IE=Edge"><script>\n` +
    `    (function () { var q = /[?&]theme=(light|dark)(?:&|$)/.exec(location.search), a = /[?&]pane=1(?:&|$)/.test(location.search), p = a, t = null, n = /^tbdocs:(light|dark)?:(1)?$/.exec(window.name);\n` +
    `    try { if (q) sessionStorage.setItem('theme', q[1]); t = sessionStorage.getItem('theme') || localStorage.getItem('theme');\n` +
    `    if (p) sessionStorage.setItem('pane', '1'); else p = sessionStorage.getItem('pane') === '1'; } catch (e) { if (n) { t = n[1]; p = p || !!n[2]; } }\n` +
    `    if (q) t = q[1];\n` +
    `    if (t === 'light' || t === 'dark') document.documentElement.setAttribute('data-theme', t);\n` +
    `    if (q || a) window.name = 'tbdocs:' + (t === 'light' || t === 'dark' ? t : '') + ':' + (p ? '1' : '');\n` +
    `    if (p) document.documentElement.setAttribute('data-pane', ''); })();\n` +
    `  </script>\n` +
    `  <script type="text/javascript" src="${escapeMarkupAndQuotes(relativeUrl("/assets/js/theme-toggle.js", bu))}" defer></script>\n` +
    fontPreloads(bu) +
    `  <link rel="stylesheet" href="${escapeMarkupAndQuotes(relativeUrl("/assets/css/just-the-docs-combined.css", bu))}">\n` +
    `  <link rel="stylesheet" href="${escapeMarkupAndQuotes(relativeUrl("/assets/css/tb-highlight.css", bu))}">\n` +
    `  <link rel="stylesheet" href="${escapeMarkupAndQuotes(relativeUrl("/assets/css/just-the-docs-head-nav.css", bu))}" id="jtd-head-nav-stylesheet">\n` +
    `  <style id="jtd-nav-activation">\n` +
    navActivationCss(page) +
    `\n  </style>\n` +
    (init.gaSnippet ? init.gaSnippet + `\n` : "") +
    (init.searchEnabled
      ? `  <script src="${escapeMarkupAndQuotes(relativeUrl("/assets/js/vendor/lunr.min.js", bu))}"></script>\n`
      : "") +
    (bu ? `  <script>window.jtdBaseurl=${JSON.stringify(bu)};</script>\n` : "") +
    `  <script src="${escapeMarkupAndQuotes(relativeUrl("/assets/js/just-the-docs.js", bu))}"></script>\n` +
    (page.hasFigure
      ? `  <script src="${escapeMarkupAndQuotes(relativeUrl("/assets/js/figure.js", bu))}" defer></script>\n`
      : "") +
    `  <meta name="viewport" content="width=device-width, initial-scale=1">\n` +
    headSeoBlock(page, site) +
    init.faviconLink +
    `</head>\n`
  );
}

// Port of docs/_includes/head_seo.html. Verbatim byte parity with
// jekyll-seo-tag v2.8.0 for this site's configuration.
//
// `seoTitle` / `seoFullTitle` / `seoSiteTitle` are already HTML-
// escaped by Phase 2's seo.mjs (`escape_once` pipeline output), so
// they go in verbatim. Escaping again would double-encode `&` to
// `&amp;amp;` on titles like `&, &=`.
function headSeoBlock(page, site) {
  return (
    `<!-- Begin Jekyll SEO tag v2.8.0 -->\n` +
    `<title>${page.seoFullTitle ?? ""}</title>\n` +
    `<meta name="generator" content="Jekyll v4.4.1" />\n` +
    `<meta property="og:title" content="${page.seoTitle ?? ""}" />\n` +
    `<meta property="og:locale" content="en_US" />\n` +
    `<link rel="canonical" href="${escapeMarkupAndQuotes(page.seoCanonical ?? "")}" />\n` +
    `<meta property="og:url" content="${escapeMarkupAndQuotes(page.seoCanonical ?? "")}" />\n` +
    `<meta property="og:site_name" content="${site.seoSiteTitle ?? ""}" />\n` +
    `<meta property="og:type" content="website" />\n` +
    `<meta name="twitter:card" content="summary" />\n` +
    `<meta property="twitter:title" content="${page.seoTitle ?? ""}" />\n` +
    `<script type="application/ld+json">\n` +
    jsonLd(page, site) +
    `</script>\n` +
    `<!-- End Jekyll SEO tag -->\n`
  );
}

// JSON.stringify matches Liquid's `| jsonify` -- compact, no extra
// whitespace, double-quoted keys. Two variants: WebSite for the
// homepage / about pages, WebPage for everything else.
function jsonLd(page, site) {
  if (page.seoIsHome) {
    return JSON.stringify({
      "@context": "https://schema.org",
      "@type": "WebSite",
      headline: page.seoTitle,
      name: site.seoSiteTitle,
      publisher: {
        "@type": "Organization",
        logo: { "@type": "ImageObject", url: site.seoLogoUrl },
      },
      url: page.seoCanonical,
    });
  }
  return JSON.stringify({
    "@context": "https://schema.org",
    "@type": "WebPage",
    headline: page.seoTitle,
    publisher: {
      "@type": "Organization",
      logo: { "@type": "ImageObject", url: site.seoLogoUrl },
    },
    url: page.seoCanonical,
  });
}

// Port of docs/_includes/head_custom.html. The rendered output has the
// trailing space-before-`>` artifact from the Liquid source's
// multi-line `<link ... href="..." >` shape (compress collapses the
// internal whitespace to a single space).
function buildFaviconLink(config) {
  const bu = String(config.baseurl ?? "");
  return `<link rel="shortcut icon" type="image/png" href="${relativeUrl("/favicon.png", bu)}" >\n`;
}

// Currently unset in _config.yml; emits empty string. When set, mirror
// the head.html template's gtag.js loader pattern.
function buildGaSnippet(config) {
  if (!config.ga_tracking) return "";
  const ids = String(config.ga_tracking).split(",");
  const primary = ids[0];
  const configCalls = ids
    .map(
      (id) =>
        `      gtag('config', '${id}'${config.ga_tracking_anonymize_ip != null ? ", { 'anonymize_ip': true }" : ""});\n`,
    )
    .join("");
  return (
    `    <script async src="https://www.googletagmanager.com/gtag/js?id=${primary}"></script>\n` +
    `    <script>\n` +
    `      window.dataLayer = window.dataLayer || [];\n` +
    `      function gtag(){dataLayer.push(arguments);}\n` +
    `      gtag('js', new Date());\n` +
    configCalls +
    `    </script>`
  );
}

// ---------- §5.3 SVG icon sprite -----------------------------------------

const SVG_SYMBOL_LINK = `<symbol id="svg-link" viewBox="0 0 24 24">
  <title>Link</title>
  <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link">
    <path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path>
  </svg>
</symbol>`;

const SVG_SYMBOL_MENU = `<symbol id="svg-menu" viewBox="0 0 24 24">
  <title>Menu</title>
  <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-menu">
    <line x1="3" y1="12" x2="21" y2="12"></line><line x1="3" y1="6" x2="21" y2="6"></line><line x1="3" y1="18" x2="21" y2="18"></line>
  </svg>
</symbol>`;

const SVG_SYMBOL_EXPAND = `<symbol id="svg-arrow-right" viewBox="0 0 24 24">
  <title>Expand</title>
  <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-chevron-right">
    <polyline points="9 18 15 12 9 6"></polyline>
  </svg>
</symbol>
<!-- Feather. MIT License: https://github.com/feathericons/feather/blob/master/LICENSE -->
<symbol id="svg-external-link" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-external-link">
  <title id="svg-external-link-title">(external link)</title>
  <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"></path><polyline points="15 3 21 3 21 9"></polyline><line x1="10" y1="14" x2="21" y2="3"></line>
</symbol>`;

const SVG_SYMBOL_DOC = `<symbol id="svg-doc" viewBox="0 0 24 24">
  <title>Document</title>
  <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-file">
    <path d="M13 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9z"></path><polyline points="13 2 13 9 20 9"></polyline>
  </svg>
</symbol>
<symbol id="svg-search" viewBox="0 0 24 24">
  <title>Search</title>
  <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-search">
    <circle cx="11" cy="11" r="8"></circle><line x1="21" y1="21" x2="16.65" y2="16.65"></line>
  </svg>
</symbol>`;

const SVG_SYMBOLS_COPY = `<!-- Bootstrap Icons. MIT License: https://github.com/twbs/icons/blob/main/LICENSE.md -->
<symbol id="svg-copy" viewBox="0 0 16 16">
  <title>Copy</title>
  <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-clipboard" viewBox="0 0 16 16">
    <path d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1h1a1 1 0 0 1 1 1V14a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V3.5a1 1 0 0 1 1-1h1v-1z"/>
    <path d="M9.5 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3zm-3-1A1.5 1.5 0 0 0 5 1.5v1A1.5 1.5 0 0 0 6.5 4h3A1.5 1.5 0 0 0 11 2.5v-1A1.5 1.5 0 0 0 9.5 0h-3z"/>
  </svg>
</symbol>
<symbol id="svg-copied" viewBox="0 0 16 16">
  <title>Copied</title>
  <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-clipboard-check-fill" viewBox="0 0 16 16">
    <path d="M6.5 0A1.5 1.5 0 0 0 5 1.5v1A1.5 1.5 0 0 0 6.5 4h3A1.5 1.5 0 0 0 11 2.5v-1A1.5 1.5 0 0 0 9.5 0h-3Zm3 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3Z"/>
    <path d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1A2.5 2.5 0 0 1 9.5 5h-3A2.5 2.5 0 0 1 4 2.5v-1Zm6.854 7.354-3 3a.5.5 0 0 1-.708 0l-1.5-1.5a.5.5 0 0 1 .708-.708L7.5 10.793l2.646-2.647a.5.5 0 0 1 .708.708Z"/>
  </svg>
</symbol>`;

// Port of theme's _includes/icons/icons.html. The search icon is
// conditional; the copy-code icons ship unconditionally.
//
// FIGURE_SPRITE is the figure controls bar's glyphs (render.mjs, figureButton),
// written only on a page with a figure. Feather's style on its 24 grid, at the
// 1.5 stroke of the theme toggle's icons; download, the clipboard and the
// magnifier follow Feather's own, and vector (a curve on two anchors, with its
// handles) and raster (pixels) are drawn for this bar.
const FIGURE_SPRITE = `  <svg xmlns="http://www.w3.org/2000/svg" class="d-none">
<symbol id="fig-download" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="7 10 12 15 17 10"/><line x1="12" y1="15" x2="12" y2="3"/></symbol>
<symbol id="fig-copy" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2"/><rect x="8" y="2" width="8" height="4" rx="1"/></symbol>
<symbol id="fig-copied" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2"/><rect x="8" y="2" width="8" height="4" rx="1"/><polyline points="8.5 14 11 16.5 15.5 11.5"/></symbol>
<symbol id="fig-zoom" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="7"/><line x1="21" y1="21" x2="16" y2="16"/><line x1="11" y1="8" x2="11" y2="14"/><line x1="8" y1="11" x2="14" y2="11"/></symbol>
<symbol id="fig-close" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><line x1="6" y1="6" x2="18" y2="18"/><line x1="18" y1="6" x2="6" y2="18"/></symbol>
<symbol id="fig-vector" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><rect x="2" y="15" width="4" height="4" rx=".5"/><rect x="18" y="15" width="4" height="4" rx=".5"/><path d="M4 15C4 9 8 6 12 6s8 3 8 9"/><line x1="4" y1="6" x2="20" y2="6"/><circle cx="4" cy="6" r="1.3" fill="currentColor"/><circle cx="20" cy="6" r="1.3" fill="currentColor"/></symbol>
<symbol id="fig-raster" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linejoin="round"><rect x="3" y="3" width="18" height="18" rx="2"/><g fill="currentColor" stroke="none"><rect x="3.5" y="3.5" width="5.5" height="5.5"/><rect x="15" y="3.5" width="5.5" height="5.5"/><rect x="9" y="9" width="6" height="6"/><rect x="3.5" y="15" width="5.5" height="5.5"/><rect x="15" y="15" width="5.5" height="5.5"/></g></symbol>
</svg>`;

function buildSvgSprites(config) {
  const searchEnabled = config.search_enabled !== false;
  const parts = [
    `  <svg xmlns="http://www.w3.org/2000/svg" class="d-none">`,
    SVG_SYMBOL_LINK,
    SVG_SYMBOL_MENU,
    SVG_SYMBOL_EXPAND,
  ];
  if (searchEnabled) parts.push(SVG_SYMBOL_DOC);
  parts.push(SVG_SYMBOLS_COPY);
  parts.push(`</svg>`);
  return parts.join("\n");
}

// ---------- §5.4 sidebar + recursive nav ---------------------------------

function renderSidebar(site) {
  const config = site.config;
  const baseurl = String(config.baseurl ?? "");
  return (
    `  <div class="side-bar">\n` +
    `    <div class="site-header" role="banner">\n` +
    `      <a href="${escapeMarkupAndQuotes(relativeUrl("/", baseurl))}" class="site-title lh-tight">${renderSiteTitle(config)}</a>\n` +
    `      <button id="menu-button" class="site-button btn-reset" aria-label="Toggle menu" aria-expanded="false" aria-controls="site-nav">\n` +
    `        <svg viewBox="0 0 24 24" class="icon" aria-hidden="true"><use xlink:href="#svg-menu"></use></svg>\n` +
    `      </button>\n` +
    `    </div>\n` +
    `    ${NAV_OPEN}` +
    renderNavTree(site.navTree, [], baseurl) +
    renderNavExternalLinks(config) +
    `</nav>\n` +
    // Upstream sidebar.html: when nav_footer_custom.html is empty
    // (it is on this site), the else-branch emits the "Just the Docs"
    // fallback footer. The site doesn't override nav_footer_custom.html,
    // so the upstream default applies verbatim.
    `    <footer class="site-footer" aria-label="Site">\n` +
    `      This site uses <a href="https://github.com/just-the-docs/just-the-docs">Just the Docs</a>, a documentation theme originally for Jekyll.\n` +
    `    </footer>\n` +
    `  </div>`
  );
}

// The offline tree's nav. An online page holds the whole tree, so the nav
// works without JavaScript. An offline page holds only the part of it that
// shows when the page opens: the top level, and the children of the page and
// of each of its ancestors. The whole tree is in the offline tree's
// /assets/js/nav.js (`navScript`), loaded right after the nav, which puts it
// in place before the page's scripts run. The part keeps every sibling of the
// expanded path, so the nth-child selectors of `navActivationCss` find the
// same items in both.

export const NAV_SCRIPT_REL = "assets/js/nav.js";
const NAV_OPEN = `<nav aria-label="Main" id="site-nav" class="site-nav">`;

/** The whole nav tree's first list, compressed as a page is. */
export function renderFullNav(site) {
  return compressHtml(renderNavTree(site.navTree, [], String(site.config.baseurl ?? "")).replace(/\n$/, ""));
}

/**
 * A templated page's HTML with its whole nav tree (`fullNav`, from
 * `renderFullNav`) swapped for the page's part of it, and nav.js loaded
 * after the nav: what the offline tree is derived from. A page without the
 * whole tree is returned as it is.
 */
export function withPartialNav(html, page, site, fullNav) {
  const navAt = html.indexOf(NAV_OPEN + fullNav);
  if (navAt === -1) return html;
  const treeAt = navAt + NAV_OPEN.length;
  const closeAt = html.indexOf("</nav> ", treeAt + fullNav.length);
  if (closeAt === -1) return html;
  const baseurl = String(site.config.baseurl ?? "");
  const open = page.navLevels ? page.navLevels.slice(1) : [];
  const part = compressHtml(renderNavTree(site.navTree, [], baseurl, open).replace(/\n$/, ""));
  const script = `<script src="${escapeMarkupAndQuotes(relativeUrl(`/${NAV_SCRIPT_REL}`, baseurl))}"></script> `;
  const afterNav = closeAt + "</nav> ".length;
  return html.slice(0, treeAt) + part + html.slice(treeAt + fullNav.length, afterNav) + script + html.slice(afterNav);
}

/**
 * The offline tree's /assets/js/nav.js: puts the whole tree in place of a
 * page's part of it. `navHtml` is `renderFullNav`'s list with its links
 * relative to the site's root, and the page's `OFFLINE_SITE_ROOT` goes in
 * front of each. The help add-in's pane hides the nav, so it is left alone
 * there.
 */
export function navScript(navHtml) {
  return (
    `(function () {\n` +
    `  var nav = document.getElementById("site-nav"), root = window.OFFLINE_SITE_ROOT || "";\n` +
    `  if (!nav || !nav.firstElementChild || document.documentElement.hasAttribute("data-pane")) return;\n` +
    `  var html = ${JSON.stringify(navHtml)};\n` +
    `  nav.firstElementChild.outerHTML = root ? html.replace(/<a href="/g, '<a href="' + root) : html;\n` +
    `})();\n`
  );
}

// Port of docs/_includes/title.html: when site.logo is set, the title
// renders as a logo div; with logo_with_title also set, append the
// title text after the logo. Leading space matches the source-side
// whitespace between `<a class="site-title">` and the include body
// (compress collapses to one space).
function renderSiteTitle(config) {
  const title = String(config.title ?? "");
  if (config.logo) {
    let out = ` <div class="site-logo" role="img" aria-label="${escapeMarkupAndQuotes(title)}"></div>`;
    if (config.logo_with_title) {
      // The Liquid source has `{{ site.title }}` on its own indented
      // line; compress collapses surrounding whitespace to single spaces.
      out += ` ${title} `;
    }
    return out;
  }
  return ` ${title} `;
}

// Port of docs/_includes/components/nav/links.html. Cycle defence by
// title matches the upstream visual: a page that shares a title with
// one of its ancestors renders as an infinity link without recursion.
//
// Liquid `{{ node.title }}` does NOT HTML-escape -- titles with `&` /
// `<` / `>` (the operator pages: `&, &=`, `<<, <<=`, `>>, >>=`) render
// literal in Jekyll. Mirror that here so byte parity holds.
//
// A trailing `\n` after the recursive call's `</ul>` comes from the
// included file's trailing newline (survives Liquid trim semantics --
// see test in PLAN-4 §5.4 notes). Compress collapses to one space,
// producing `</ul> </li>` rather than `</ul></li>`.
//
// `open`, when given, renders only part of the tree: the 1-based positions
// of the path to expand, one per level (a page's `navLevels` after its
// first entry). A node off the path keeps its expander but not its list.
function renderNavTree(nodes, ancestorTitles, baseurl, open) {
  if (!nodes || nodes.length === 0) return `<ul class="nav-list"></ul>\n`;
  let out = `<ul class="nav-list">`;
  for (const [i, node] of nodes.entries()) {
    const rest = !open ? undefined : open[0] === i + 1 ? open.slice(1) : null;
    out += `<li class="nav-list-item">`;
    if (ancestorTitles.includes(node.title)) {
      out += `<a href="${escapeMarkupAndQuotes(relativeUrl(node.url, baseurl))}" class="nav-list-link"> &#8734; </a>`;
    } else {
      const hasChildren = node.children && node.children.length > 0;
      if (hasChildren) {
        // The upstream emits the button + svg across multiple source
        // lines; compress collapses to single spaces.
        out +=
          `<button class="nav-list-expander btn-reset" aria-label="toggle items in ${escapeMarkupAndQuotes(String(node.title))} category" aria-expanded="false"> ` +
          `<svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg>` +
          ` </button>`;
      }
      out += `<a href="${escapeMarkupAndQuotes(relativeUrl(node.url, baseurl))}" class="nav-list-link">${String(node.title)}</a>`;
      if (hasChildren && rest !== null) {
        out += renderNavTree(node.children, [...ancestorTitles, node.title], baseurl, rest);
      }
    }
    out += `</li>`;
  }
  out += `</ul>\n`;
  return out;
}

// Port of the site_nav.html shadow's nav_external_links branch.
function renderNavExternalLinks(config) {
  const list = config.nav_external_links;
  if (!list || list.length === 0) return "";
  const items = list
    .map((node) => {
      const opensNewTab =
        node.opens_in_new_tab === true || (node.opens_in_new_tab == null && config.nav_external_links_new_tab);
      // The Liquid source has a multi-line `<a ... class="..." {% if ...
      // %}target="..." rel="..."{% endif %}>` shape; with target absent,
      // compress collapses the whitespace inside the open tag to a single
      // space, leaving `class="nav-list-link external" >` (note the
      // trailing space before `>`). Mirror the exact byte form.
      const targetAttrs = opensNewTab ? `target="_blank" rel="noopener noreferrer" ` : ``;
      const url = absoluteUrl(node.url, config);
      const svg = node.hide_icon
        ? ""
        : ` <svg viewBox="0 0 24 24" aria-labelledby="svg-external-link-title"><use xlink:href="#svg-external-link"></use></svg>`;
      return (
        `<li class="nav-list-item external"> ` +
        `<a href="${escapeMarkupAndQuotes(url)}" class="nav-list-link external" ${targetAttrs}>` +
        ` ${escapeMarkupAndQuotes(String(node.title))}${svg} ` +
        `</a> ` +
        `</li>`
      );
    })
    .join("");
  // No trailing whitespace: the Liquid source's `{%- endif -%}</nav>`
  // strips between the closing `</ul>` and the outer `</nav>`.
  return `<ul class="nav-list">${items}</ul>`;
}

// ---------- §5.5 navActivationCss ----------------------------------------

const COLLECTION_PREFIX = ".site-nav > ul.nav-list:first-child";

export function navActivationCss(page) {
  const levels = page.navLevels;
  if (!levels) {
    // Fallback for pages not in the nav (no title, nav_exclude, or
    // unresolved parent chain). Matches _site/404.html exactly.
    return `    .site-nav ul li a {\n      background-image: none;\n    }`;
  }

  // levels[0] = 1 (collection-prefix, always 1 on this site).
  // levels[1..depth] = 1-based child positions for each ancestor + leaf.
  // depth = navLevels.length - 1.
  const depth = levels.length - 1;
  const active = levels[depth];

  // ---- Rule 1: background-image: none for non-active links ----
  // Verbatim port of activation.scss.liquid lines 65-77.
  //
  // Three parts:
  //   (a) ancestor selectors (only when depth >= 2):
  //       prefix > li > a,
  //       prefix > li > ul > li > a,
  //       ... up to (depth - 1) levels deep.
  //   (b) current page's siblings (li at depth, excluding the active one):
  //       prefix > (li > ul > ){depth-1 times} li:not(:nth-child(N)) > a
  //   (c) current page's descendants:
  //       prefix > (li > ul > ){depth times} li a
  const noBg = [];
  if (depth >= 2) {
    for (let i = 1; i <= depth - 1; i++) {
      let s = COLLECTION_PREFIX + " >";
      for (let j = 2; j <= i; j++) s += ` li > ul >`;
      s += ` li > a`;
      noBg.push(s);
    }
  }
  {
    let s = COLLECTION_PREFIX + " >";
    for (let i = 1; i <= depth - 1; i++) s += ` li > ul >`;
    s += ` li:not(:nth-child(${active})) > a`;
    noBg.push(s);
  }
  {
    let s = COLLECTION_PREFIX + " >";
    for (let i = 1; i <= depth; i++) s += ` li > ul >`;
    s += ` li a`;
    noBg.push(s);
  }

  let css = `    ${noBg.join(",\n    ")} {\n` + `      background-image: none;\n` + `    }\n\n`;

  // ---- Rule 2: trailer for other collections + externals (constant) ----
  css +=
    `    .site-nav > ul.nav-list:not(:first-child) a,\n` +
    `    .site-nav li.external a {\n` +
    `      background-image: none;\n` +
    `    }\n\n`;

  // ---- Rule 3: bolding the active leaf link ----
  // Liquid: `prefix > li:nth-child(N1)` then `for i in (2..depth)`
  // appends ` > ul > li:nth-child(Ni)`, then ` > a`.
  {
    let s = `    ${COLLECTION_PREFIX} > li:nth-child(${levels[1]})`;
    for (let i = 2; i <= depth; i++) {
      s += ` > ul > li:nth-child(${levels[i]})`;
    }
    s += ` > a`;
    css += `${s} {\n      font-weight: 600;\n      text-decoration: none;\n    }`;
  }

  // ---- Rule 4: expander icon rotation (button svg), depth selectors ----
  // Liquid:
  //   prefix > li:nth-child(N1) > button svg
  //   prefix > li:nth-child(N1) > ul > li:nth-child(N2) > button svg
  //   ...
  // No leading newline before the first rule -- the upstream Liquid
  // has `{%- if site.just_the_docs.collections %}...{% endif -%}` that
  // strips the surrounding whitespace, so this rule abuts the previous
  // `}` with no separator.
  {
    const sels = [];
    for (let i = 1; i <= depth; i++) {
      let s = `${COLLECTION_PREFIX} > li:nth-child(${levels[1]})`;
      // Liquid: outer is at i=1 unconditional, inner loop for j in (2..i)
      // appends ` > ul > li:nth-child(Nj)`, then ` button svg` (with
      // single space before button when inner loop fires, else just one
      // ` > button svg`). For i=1: `prefix > li:nth-child(N1) > button svg`.
      // For i=2: `prefix > li:nth-child(N1) > ul > li:nth-child(N2) > button svg`.
      for (let j = 2; j <= i; j++) {
        s += ` > ul > li:nth-child(${levels[j]})`;
      }
      s += ` > button svg`;
      sels.push(s);
    }
    css += sels.join(",\n    ");
    css += ` {\n      transform: rotate(-90deg);\n    }`;
  }

  // ---- Rule 5: collection display (ul.nav-list display: block) ----
  // Same shape as Rule 4 but classed (`li.nav-list-item:nth-child(N)`)
  // and ul.nav-list terminals. Like Rule 4, no separator from previous.
  {
    const sels = [];
    for (let i = 1; i <= depth; i++) {
      let s = `${COLLECTION_PREFIX} > li.nav-list-item:nth-child(${levels[1]})`;
      for (let j = 2; j <= i; j++) {
        s += ` > ul.nav-list > li.nav-list-item:nth-child(${levels[j]})`;
      }
      s += ` > ul.nav-list`;
      sels.push(s);
    }
    css += sels.join(",\n    ");
    css += ` {\n      display: block;\n    }`;
  }

  // Prepend a leading 4-space indent on the first non-blank line of
  // each major rule above. The Liquid source has 4-space indentation;
  // compress preserves all single spaces (collapsing runs to one).
  return css;
}

// ---------- §5.6 renderHeader + auxNav -----------------------------------

function renderHeader(site) {
  const config = site.config;
  const searchEnabled = config.search_enabled !== false;
  const auxLinks = config.aux_links;
  return (
    `    <div id="main-header" class="main-header">\n` +
    (searchEnabled ? renderSearchInput(config) : `      <div></div>\n`) +
    (auxLinks ? renderAuxNav(config) : "") +
    `    </div>`
  );
}

function renderSearchInput(config) {
  // Search placeholder (port of upstream search_placeholder_custom.html):
  // `Search ${site.title}`, then strip_html + strip. The site title is
  // plain text so strip_html is a no-op.
  const placeholder = `Search ${escapeMarkupAndQuotes(String(config.title ?? ""))}`;
  return (
    `      <div class="search" role="search">\n` +
    `        <div class="search-input-wrap">\n` +
    `          <input type="text" id="search-input" class="search-input" role="combobox" placeholder="${placeholder}" aria-label="${placeholder}" autocomplete="off" aria-haspopup="listbox" aria-expanded="false">\n` +
    `          <label for="search-input" class="search-label"><svg viewBox="0 0 24 24" class="search-icon"><use xlink:href="#svg-search"></use></svg></label>\n` +
    `        </div>\n` +
    `        <div id="search-results" class="search-results"></div>\n` +
    `      </div>\n`
  );
}

// Port of docs/_includes/components/aux_nav.html. The sun/moon SVG
// sprite lives INSIDE the aux-nav wrapper (D8: byte parity).
function renderAuxNav(config) {
  const links = config.aux_links || {};
  // YAML hash → ordered [title, urls[]] pairs. `link.first` in Liquid
  // is the key; `link.last` is the value (first url).
  const items = Object.entries(links)
    .map(([title, urls]) => {
      const url = Array.isArray(urls) ? urls[0] : urls;
      const targetAttrs = config.aux_links_new_tab ? ` target="_blank" rel="noopener noreferrer"` : ``;
      // Liquid source has a multi-line `<a ... {% if ... %}...{% endif %}>`
      // shape; with new_tab absent, compress collapses the whitespace
      // inside the open tag to a single space, leaving `class="site-button" >`.
      // Liquid `{{ link.first }}` doesn't escape -- emit title verbatim.
      return (
        `      <li class="aux-nav-list-item">\n` +
        `        <a href="${escapeMarkupAndQuotes(String(url ?? ""))}" class="site-button"${targetAttrs}\n` +
        `        >\n` +
        `          ${String(title)}\n` +
        `        </a>\n` +
        `      </li>`
      );
    })
    .join("\n");
  return (
    `      <nav aria-label="Auxiliary" class="aux-nav">` +
    AUX_NAV_THEME_SVG +
    `        <ul class="aux-nav-list">\n` +
    `          <li class="aux-nav-list-item">\n` +
    `            <button type="button" id="theme-toggle" class="site-button btn-reset" hidden aria-label="Theme" data-label-system="Follow system" data-label-light="Light" data-label-dark="Dark" data-theme-choice="system">\n` +
    `              <svg width='18px' height='18px' class="theme-icon" data-icon="system" aria-hidden="true"><use href="#svg-monitor"></use></svg>\n` +
    `              <svg width='18px' height='18px' class="theme-icon" data-icon="light" aria-hidden="true"><use href="#svg-sun"></use></svg>\n` +
    `              <svg width='18px' height='18px' class="theme-icon" data-icon="dark" aria-hidden="true"><use href="#svg-moon"></use></svg>\n` +
    `            </button>\n` +
    `          </li>\n` +
    items +
    `\n` +
    `        </ul>\n` +
    `      </nav>\n`
  );
}

// No leading whitespace: docs/_includes/components/aux_nav.html has a
// `{%- comment -%}...{%- endcomment -%}` between `<nav>` and `<svg>`
// that strips it. Concatenated tight against the opening `<nav>`.
const AUX_NAV_THEME_SVG = `<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
          <symbol id="svg-sun" viewBox="0 0 24 24">
            <title>Light mode</title>
            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
              stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="feather-sun">
              <circle cx="12" cy="12" r="5"></circle>
              <line x1="12" y1="1" x2="12" y2="3"></line>
              <line x1="12" y1="21" x2="12" y2="23"></line>
              <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
              <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
              <line x1="1" y1="12" x2="3" y2="12"></line>
              <line x1="21" y1="12" x2="23" y2="12"></line>
              <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
              <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
            </svg>
          </symbol>
          <symbol id="svg-moon" viewBox="0 0 24 24">
            <title>Dark mode</title>
            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
              stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon">
              <path stroke="none" d="M0 0h24v24H0z" fill="none" />
              <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" />
            </svg>
          </symbol>
          <symbol id="svg-monitor" viewBox="0 0 24 24">
            <title>Follow system</title>
            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
              stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="feather-monitor">
              <rect x="2" y="3" width="20" height="14" rx="2" ry="2"></rect>
              <line x1="8" y1="21" x2="16" y2="21"></line>
              <line x1="12" y1="17" x2="12" y2="21"></line>
            </svg>
          </symbol>
        </svg>
`;

// ---------- §5.7 renderBreadcrumbs ---------------------------------------

function renderBreadcrumbs(page, baseurl) {
  if (page.permalink === "/" || !page.frontmatter.parent || !page.frontmatter.title) {
    return "";
  }
  const chain = page.breadcrumbs || [];
  // Liquid `{{ entry.title }}` and `{{ page.title }}` do NOT escape.
  // Operator titles like `&, &=` render literal in Jekyll's breadcrumb;
  // escaping here would emit `&amp;, &amp;=` instead.
  const items = chain
    .map(
      (entry) =>
        `        <li class="breadcrumb-nav-list-item"><a href="${escapeMarkupAndQuotes(relativeUrl(entry.url, baseurl))}">${String(entry.title)}</a></li>`,
    )
    .join("\n");
  return (
    `      <nav aria-label="Breadcrumb" class="breadcrumb-nav">\n` +
    `        <ol class="breadcrumb-nav-list">\n` +
    (items ? items + "\n" : "") +
    `          <li class="breadcrumb-nav-list-item"><span>${String(page.frontmatter.title)}</span></li>\n` +
    `        </ol>\n` +
    `      </nav>\n`
  );
}

// ---------- §5.8 injectAnchorHeadings ------------------------------------

const HEADING_REGEX = /<(h[1-6])(\s[^>]*?)?>([\s\S]*?)<\/\1>/g;
const ID_ATTR_REGEX = /\bid="([^"]+)"/;
// The icon is deliberately out of the accessibility tree and out of the tab
// order. An `aria-labelledby` pointing at the enclosing heading would make
// the accessible name the heading text verbatim -- so every heading would appear a
// second time in a screen reader's links list, named identically, with nothing
// saying it was a permalink. It stays a real
// `<a href>` so the mouse affordances that people actually use to copy these
// (right-click Copy Link Address, middle-click, the status-bar URL preview) are
// untouched; the keyboard/AT equivalent is the section-links disclosure that
// renderSectionLinks emits once per page. axe reports `aria-hidden-focus` as a
// pass because `tabindex="-1"` takes it out of the tab order.
const ANCHOR_SVG_TPL = (id) =>
  `<a href="#${id}" class="anchor-heading" tabindex="-1" aria-hidden="true"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a>`;

// `headingsOut`, when given, collects {id, text} for every heading that has
// an id -- piggybacking on this pass rather than sweeping the page a second
// time. `body` is rendered HTML whose text is already escaped, so dropping
// the tags leaves a string that is still safe to emit as HTML; re-escaping
// would double-encode headings like `&, &=`. It goes through
// replaceOutsideCode (render.mjs's applyPostRenderRewrites says why): the
// spaces this adds around a heading's body would be content in a raw `<pre>`.
export function injectAnchorHeadings(html, headingsOut) {
  return replaceOutsideCode(html, HEADING_REGEX, (_, tag, attrs = "", body) => {
    const idMatch = attrs ? attrs.match(ID_ATTR_REGEX) : null;
    if (idMatch) {
      const id = idMatch[1];
      if (headingsOut) {
        const text = stripHtml(body).replace(/\s+/g, " ").trim();
        if (text) headingsOut.push({ id, text });
      }
      return `<${tag}${attrs}> ${ANCHOR_SVG_TPL(id)} ${body} </${tag}>`;
    }
    return `<${tag}${attrs}> ${body} </${tag}>`;
  });
}

// ---------- §5.8b renderSectionLinks -------------------------------------

// The keyboard and screen-reader path to the per-section URLs whose only
// other affordance is the aria-hidden chain icon beside each heading.
//
// A closed <details> subtree is `notRendered`: it contributes nothing to the
// accessibility tree and nothing to the tab order beyond the <summary>
// itself. So the whole feature costs one tab stop and zero links-list entries
// per page, against one entry per heading for per-heading icons, and
// expands on demand to the full set.
//
// Emitted from the template rather than from the markdown render, which is
// what keeps it out of two places it does not belong: the PDF book assembles
// its chapters from `page.renderedContent` (book.mjs) and the search index
// reads the same field (search.mjs), and both are upstream of this. So there
// is nothing to mark here and nothing to strip downstream.
//
// Deliberately not wrapped in <nav>: a fourth landmark on all 869 pages would
// put back some of the noise this exists to remove. A single heading is not
// worth a disclosure, so the block starts at two.
function renderSectionLinks(headings) {
  if (!headings || headings.length < 2) return "";
  const items = headings
    .map(({ id, text }) => `          <li><a href="#${escapeMarkupAndQuotes(id)}">${text}</a></li>`)
    .join("\n");
  return (
    `        <details class="section-links">\n` +
    `        <summary>Link to a section</summary>\n` +
    `        <ul>\n${items}\n        </ul>\n` +
    `        </details>\n`
  );
}

// ---------- §5.9 renderChildrenNav ---------------------------------------

function renderChildrenNav(page, baseurl) {
  const children = page.children;
  if (!children || children.length === 0) return "";
  if (page.frontmatter.has_toc === false) return "";
  // Liquid `{{ nav_child.title }}` / `{{ nav_child.summary }}` do NOT
  // escape -- emit titles and summaries verbatim.
  const items = children
    .map((child) => {
      const summary = child.summary != null && child.summary !== "" ? ` - ${String(child.summary)}` : "";
      return (
        `  <li>\n` +
        `    <a href="${escapeMarkupAndQuotes(relativeUrl(child.url, baseurl))}">${String(child.title)}</a>${summary}\n` +
        `  </li>`
      );
    })
    .join("\n");
  return `\n<hr>\n` + `<h2 class="text-delta">Table of contents</h2>\n` + `<ul>\n` + items + `\n` + `</ul>\n\n`;
}

// ---------- §5.11 renderFooter -------------------------------------------

// One rule, one block, one type size. The old shape had two dividers (this
// <hr> plus the section-links border-top), a 16px "Back to top" sitting among
// 12px siblings, and five stacked <p> where two wrapped rows do -- 224px of
// page bottom. The section-links disclosure moved in here from the end of
// <main>: it belongs with the other per-page utilities, and putting it inside
// the existing contentinfo landmark makes it easier to find without adding a
// landmark of its own.
function renderFooter(page, site, sectionLinks) {
  const config = site.config;
  const footerLegal = renderFooterLegal(page, config);
  const footerActions = renderFooterActions(page, config);
  if (sectionLinks === "" && footerLegal === "" && footerActions === "") return "";

  return (
    `      <hr>\n` +
    `      <footer role="contentinfo">\n` +
    sectionLinks +
    footerActions +
    footerLegal +
    `      </footer>\n`
  );
}

// The legal row: the last-modified stamp, copyright, and the CC-BY-4.0 line
// on VBA-derived pages. These were `<p class="text-small mb-0">` stacked; they
// are now one wrapped flex row, and the type size comes from the footer rather
// than a utility class on each element, so nothing can drift out of step.
//
// Every child is a <span> and nothing else, the mirror of the actions row's
// all-<a> rule: this row is prose, which may contain a link, rather than a
// link that may contain prose. Keep it that way if you add to it.
function renderFooterLegal(page, config) {
  let out = "";
  if (config.last_edit_timestamp && config.last_edit_time_format && page.frontmatter.last_modified_date) {
    const formatted = formatDate(page.frontmatter.last_modified_date, config.last_edit_time_format);
    out += `          <span>Page last modified: ${escapeMarkupAndQuotes(formatted)}.</span>\n`;
  }
  if (config.footer_content) {
    // Emitted verbatim, NOT escaped: the current value contains `&copy;`
    // which is the desired HTML entity; escaping would double-encode it.
    out += `          <span>${config.footer_content}</span>\n`;
  }
  if (page.frontmatter.vba_attribution) {
    // Three items, not one: the row's flex `gap` is what separates them, and
    // as a single span the three label/link pairs ran together.
    out +=
      `          <span>License: <a href="https://github.com/MicrosoftDocs/VBA-Docs/blob/main/LICENSE">CC-BY-4.0</a></span>\n` +
      `          <span>Code license: <a href="https://github.com/MicrosoftDocs/VBA-Docs/blob/main/LICENSE-CODE">MIT</a></span>\n` +
      `          <span>Attribution: <a href="https://github.com/MicrosoftDocs/VBA-Docs/tree/main">VBA-Docs</a></span>\n`;
  }
  if (out === "") return "";
  return `        <div class="footer-legal">\n` + out + `        </div>\n`;
}

// The actions row. Every child is an <a> and nothing else -- that is the
// invariant the styling relies on, so keep it if you add to this row. It used
// to hold a <span> too, wrapping "Download <a>Offline Copy</a> or <a>PDF</a>."
// as one item, and that lone odd element out is what let the row's baselines
// drift: the min-height that makes the links 24px targets applied to the
// anchors and not to it. The framing sentence was the only reason for the
// span, so it is gone. The two downloads have since become one link to the
// Downloads page's section on reading offline, which offers both and says what
// each is.
//
// The last-modified stamp is not an action, and moved to the legal row where
// the prose items live.
//
// Separation is by flex `gap` alone -- a "·" in a ::before would be announced
// by some screen readers on every page, which is the noise the section-links
// work just removed.
//
// #back-to-top and #edit-this-page keep their ids: print.scss hides both by
// id, and that is the only thing pinning them.
function renderFooterActions(page, config) {
  const showBackToTop = Boolean(config.back_to_top);
  const showEdit =
    config.gh_edit_link &&
    config.gh_edit_link_text &&
    config.gh_edit_repository &&
    config.gh_edit_branch &&
    config.gh_edit_view_mode;
  const readOffline = config.read_offline_link ? String(config.read_offline_link) : "";

  let inner = "";
  if (showBackToTop) {
    inner += `          <a href="#page-top" id="back-to-top">${escapeMarkupAndQuotes(String(config.back_to_top_text ?? "Back to top"))}</a>\n`;
  }
  if (showEdit) {
    const href = ghEditHref(page, config);
    inner += `          <a href="${escapeMarkupAndQuotes(href)}" id="edit-this-page">${escapeMarkupAndQuotes(String(config.gh_edit_link_text))}</a>\n`;
  }
  if (readOffline) {
    const href = relativeUrl(readOffline, String(config.baseurl ?? ""));
    inner += `          <a href="${escapeMarkupAndQuotes(href)}" id="read-offline-link">Read Offline</a>\n`;
  }
  if (inner === "") return "";

  return `        <div class="footer-actions">\n` + inner + `        </div>\n`;
}

// `gh_edit_repository` keeps its trailing slash (D9). The Liquid
// template concatenates `repo + "/" + view_mode`, producing a
// double-slash like `/tree/`. GitHub redirects through it; matching
// the byte form is the goal.
function ghEditHref(page, config) {
  const repo = String(config.gh_edit_repository ?? "");
  const view = String(config.gh_edit_view_mode ?? "");
  const branch = String(config.gh_edit_branch ?? "");
  const source = config.gh_edit_source ? `/${config.gh_edit_source}` : "";
  // page.collection is unused on this site (no collections); skip.
  // page.path in Jekyll is the source-relative path with the leading
  // collection dir collapsed; for non-collection pages it's the same
  // as srcRel.
  return `${repo}/${view}/${branch}${source}/${page.srcRel.replace(/\\/g, "/")}`;
}

// ---------- §5.12 renderSearchFooter -------------------------------------

function renderSearchFooter(site) {
  const config = site.config;
  if (config.search_enabled === false) return "";
  const button = config.search?.button
    ? `    <button id="search-button" class="search-button btn-reset" aria-label="Focus on search">\n` +
      `      <svg viewBox="0 0 24 24" class="icon" aria-hidden="true"><use xlink:href="#svg-search"></use></svg>\n` +
      `    </button>\n`
    : "";
  return button + `    <div class="search-overlay"></div>`;
}