hubspot-cms-sync 0.3.0 → 0.5.0

package/bin/hubspot-cms-sync.mjs

@@ -10,6 +10,8 @@ import { main as preflightMain } from '../src/preflight.mjs';
 import { main as republishMain } from '../src/republish.mjs';
 import { main as manifestMain } from '../src/manifest.mjs';
 import { renderRedirectReport, syncRedirects } from '../src/redirects.mjs';
+import { buildStatic } from '../src/build-static.mjs';
+import { resolve as resolvePath } from 'node:path';
 
 function runNodeScript(script, args, { cwd }) {
   return new Promise((resolve) => {
@@ -45,6 +47,27 @@ async function main(argv = process.argv) {
       console.log(`theme: ${config.theme.name}`);
     });
 
+  program
+    .command('build')
+    .description('render the canonical site to a static directory (static target)')
+    .option('--out <dir>', 'output directory', 'dist')
+    .option('--base-url <url>', 'absolute base URL for canonical/og links', '')
+    .option('--tracking-portal <id>', 'HubSpot tracking-script portal id (keeps forms de-anonymizing)')
+    .action(async (options) => {
+      const config = await withConfig(program.opts());
+      const summary = await buildStatic({
+        siteDir: config.root,
+        outDir: resolvePath(config.root, options.out),
+        baseUrl: options.baseUrl,
+        trackingPortalId: options.trackingPortal,
+      });
+      console.log(`built static site -> ${options.out}`);
+      console.log(
+        `  pages: ${summary.pages} | posts: ${summary.posts} | tag pages: ${summary.tags} | `
+        + `html files: ${summary.files} | redirects: ${summary.redirects}`,
+      );
+    });
+
   program
     .command('pull')
     .description('pull HubSpot content into the repo')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hubspot-cms-sync",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Git-backed bidirectional sync for HubSpot CMS themes, content, blogs, forms, and assets.",
   "type": "module",
   "license": "MIT",

package/src/adapters/blog.mjs

@@ -45,12 +45,14 @@ import {
   mkdirSync,
   readdirSync,
   existsSync,
+  rmSync,
 } from 'node:fs';
 import { join, resolve as resolvePath, basename, extname } from 'node:path';
 import { createHash } from 'node:crypto';
 
 import { hub, getAll } from '../lib/hub.mjs';
 import { stableStringify } from '../lib/canonical.mjs';
+import { wireToFile, fileToWire } from '../lib/posts-format.mjs';
 import { resolve as resolveRefs, canonicalize as canonicalizeRefs } from '../lib/refs.mjs';
 import { resolveCtaEmbeds, loadInventory } from '../cta-inventory.mjs';
 
@@ -317,10 +319,13 @@ export async function pull(acct, { contentDir, registry }) {
       // (codex #7). It is content here, not a volatile timestamp to strip.
       publishDate: p.publishDate || null,
     };
-    writeFileSync(
-      join(postsOut, `${postFileFor(p.slug)}.json`),
-      stableStringify(portable),
-    );
+    // Canonical post format is frontmatter + HTML body (.md). Reshaping is lossless
+    // to the wire object (lib/posts-format.mjs round-trip), so the push payload is
+    // byte-identical to the old .json path. Drop any stale sibling .json from the
+    // pre-frontmatter format so push never sees the same post twice.
+    const base = join(postsOut, postFileFor(p.slug));
+    writeFileSync(`${base}.md`, wireToFile(portable));
+    if (existsSync(`${base}.json`)) rmSync(`${base}.json`);
     pulled++;
   }
 
@@ -372,6 +377,10 @@ export async function push(
     registry,
     publish = false,
     limit,
+    // only: restrict the push to specific posts by file base name (no extension),
+    // e.g. ['blog__hello']. Enables a scoped sample push without touching the rest
+    // of the blog — used by verification harnesses; undefined means "all posts".
+    only,
     dryRun = false,
     hubFn = hub,
     // Injectable clock + sleep so the "wait past every scheduled publish" gate
@@ -393,12 +402,29 @@ export async function push(
   // then replaces @asset tokens below. (The old blog-local rehostAssets path is
   // retired: one upload location, no /blog-migrated vs /synced-assets split.)
 
-  let files = readdirSync(postsDir).filter((f) => f.endsWith('.json'));
-  files.sort();
+  // Accept the canonical frontmatter format (.md) and the legacy .json. If both
+  // exist for one post, .md wins; dedup by base name so a post is never pushed
+  // twice during the transition.
+  const byBase = new Map();
+  for (const f of readdirSync(postsDir)) {
+    const m = /^(.*)\.(md|json)$/.exec(f);
+    if (!m) continue;
+    const [, base, ext] = m;
+    if (ext === 'md' || !byBase.has(base)) byBase.set(base, f);
+  }
+  let files = [...byBase.values()].sort();
+  if (only) {
+    const want = new Set(only);
+    files = files.filter((f) => want.has(f.replace(/\.(md|json)$/, '')));
+  }
   if (limit) files = files.slice(0, limit);
 
-  // Group posts by their blogSlug and resolve each container exactly once.
-  const posts = files.map((f) => JSON.parse(readFileSync(join(postsDir, f), 'utf8')));
+  // Group posts by their blogSlug and resolve each container exactly once. The
+  // frontmatter codec yields the same wire object JSON.parse would have.
+  const posts = files.map((f) => {
+    const raw = readFileSync(join(postsDir, f), 'utf8');
+    return f.endsWith('.md') ? fileToWire(raw) : JSON.parse(raw);
+  });
   const containerCache = new Map();
   async function containerIdFor(blogSlug) {
     if (containerCache.has(blogSlug)) return containerCache.get(blogSlug);

package/src/build-static.mjs

@@ -0,0 +1,119 @@
+// src/build-static.mjs — STATIC TARGET build: render the whole canonical site to a
+// directory of plain HTML + assets, deployable to any static host (Cloudflare Pages,
+// etc.). The mirror of push.mjs (the HubSpot target): same canonical content, a
+// different materialization. Output is build artifact — never committed; CI builds
+// it fresh and deploys.
+//
+// Emits, under outDir:
+//   <route>/index.html        for every published page (home slug "" -> index.html)
+//   blog/<slug>/index.html     for every published post
+//   blog/index.html            the blog listing (all posts)
+//   blog/tag/<slug>/index.html  one listing per tag
+//   css/ js/ images/ assets/   copied theme + @asset bytes (assets/ <- content/assets)
+//   _redirects                 Cloudflare redirects from sync/redirects.csv
+//   _headers                   cache + basic security headers
+
+import { mkdir, writeFile, cp, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+import { loadSite } from './lib/content-view.mjs';
+import { renderPage, renderPost, renderBlogListing, slugify } from './lib/render.mjs';
+import { readRedirectSpecs } from './redirects.mjs';
+
+async function loadTagSlugs(siteDir) {
+  const map = {};
+  try {
+    const raw = JSON.parse(await readFile(join(siteDir, 'content/blog/tags.json'), 'utf8'));
+    for (const t of Array.isArray(raw) ? raw : raw.tags || []) {
+      if (t?.name && t?.slug) map[t.name] = t.slug;
+    }
+  } catch {
+    /* tags.json optional — fall back to slugify */
+  }
+  return map;
+}
+
+/**
+ * buildStatic({ siteDir, outDir, baseUrl, assetBase, trackingPortalId }) -> summary
+ *
+ * baseUrl is used for canonical/og absolute URLs (e.g. https://www2.7thsense.io).
+ * trackingPortalId, if set, injects the HubSpot tracking script into the footer so
+ * forms keep de-anonymizing (`standard_footer_includes`). Returns counts.
+ */
+export async function buildStatic({ siteDir, outDir, baseUrl = '', assetBase = '/assets', trackingPortalId } = {}) {
+  const tagMap = await loadTagSlugs(siteDir);
+  const tagSlugFor = (name) => tagMap[name] || slugify(name);
+  const footerIncludes = trackingPortalId
+    ? `<script type="text/javascript" id="hs-script-loader" async defer src="//js.hs-scripts.com/${trackingPortalId}.js"></script>`
+    : '';
+
+  const site = await loadSite(siteDir);
+  const pages = site.pages.filter((p) => p.status === 'published');
+  const posts = site.posts.filter((p) => p.status === 'published'); // already newest-first
+  const opts = { siteDir, site, baseUrl, assetBase, footerIncludes, tagSlugFor };
+
+  let fileCount = 0;
+  async function emit(route, html) {
+    const rel = route === '/' || route === '' ? 'index.html' : join(route.replace(/^\//, ''), 'index.html');
+    const file = join(outDir, rel);
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(file, html, 'utf8');
+    fileCount++;
+  }
+
+  for (const page of pages) await emit(page.route, renderPage(page, opts));
+  for (const post of posts) await emit(post.route, renderPost(post, opts));
+
+  // Cloudflare Pages serves /404.html for any unmatched route; without it, an unknown
+  // path falls back to index.html. Render it flat at the output root.
+  if (existsSync(join(siteDir, 'templates/404.html'))) {
+    const html = renderPage(
+      { template: 'templates/404.html', route: '/404', title: 'Page not found', htmlTitle: 'Page not found', metaDescription: '', modules: {} },
+      opts,
+    );
+    await writeFile(join(outDir, '404.html'), html, 'utf8');
+    fileCount++;
+  }
+
+  await emit('/blog', renderBlogListing(posts, { ...opts, route: '/blog' }));
+
+  // One listing per tag, posts grouped by tag slug (preserves newest-first order).
+  const byTag = new Map();
+  for (const post of posts) {
+    for (const t of post.tags) {
+      const slug = tagSlugFor(t);
+      if (!byTag.has(slug)) byTag.set(slug, []);
+      byTag.get(slug).push(post);
+    }
+  }
+  for (const [slug, tagPosts] of byTag) {
+    await emit(`/blog/tag/${slug}`, renderBlogListing(tagPosts, { ...opts, route: `/blog/tag/${slug}` }));
+  }
+
+  // Assets. get_asset_url maps ../css|js|images -> /css|js|images; @asset:<p> -> /assets/<p>.
+  for (const [src, dest] of [['css', 'css'], ['js', 'js'], ['images', 'images'],
+    ['content/assets', 'assets'], ['content/blog/assets', 'assets']]) {
+    const from = join(siteDir, src);
+    if (existsSync(from)) await cp(from, join(outDir, dest), { recursive: true });
+  }
+
+  // _redirects (Cloudflare format: "<from> <to> <code>").
+  let redirectCount = 0;
+  const redirCsv = join(siteDir, 'sync/redirects.csv');
+  if (existsSync(redirCsv)) {
+    const specs = readRedirectSpecs(redirCsv);
+    const lines = specs.map((s) => `${s.routePrefix} ${s.destination} ${s.redirectStyle || 301}`);
+    await writeFile(join(outDir, '_redirects'), `${lines.join('\n')}\n`, 'utf8');
+    redirectCount = lines.length;
+  }
+
+  await writeFile(join(outDir, '_headers'),
+    '/assets/*\n  Cache-Control: public, max-age=31536000, immutable\n'
+    + '/css/*\n  Cache-Control: public, max-age=31536000, immutable\n'
+    + '/js/*\n  Cache-Control: public, max-age=31536000, immutable\n'
+    + '/*\n  X-Content-Type-Options: nosniff\n  X-Frame-Options: SAMEORIGIN\n  Referrer-Policy: strict-origin-when-cross-origin\n',
+    'utf8');
+
+  return { pages: pages.length, posts: posts.length, tags: byTag.size, files: fileCount, redirects: redirectCount };
+}

package/src/lib/content-view.mjs

@@ -23,6 +23,7 @@
 
 import { readFile, readdir } from 'node:fs/promises';
 import { join, basename } from 'node:path';
+import { fileToWire } from './posts-format.mjs';
 
 // ---------------------------------------------------------------------------
 // Status vocabulary. HubSpot speaks `desiredState` (page) and `state` (post):
@@ -138,10 +139,19 @@ export async function loadPosts(contentDir) {
   const blogDir = join(contentDir, 'blog');
   const postsDir = join(blogDir, 'posts');
   const authorsByName = await loadAuthors(blogDir);
-  const files = (await readdir(postsDir)).filter((f) => f.endsWith('.json'));
+  // Posts may be frontmatter (.md, canonical) or legacy .json. Dedup by base name,
+  // preferring .md, so a half-migrated tree never yields a post twice.
+  const byBase = new Map();
+  for (const f of await readdir(postsDir)) {
+    const m = /^(.*)\.(md|json)$/.exec(f);
+    if (!m) continue;
+    if (m[2] === 'md' || !byBase.has(m[1])) byBase.set(m[1], f);
+  }
   const posts = [];
-  for (const f of files.sort()) {
-    posts.push(projectPost(await readJson(join(postsDir, f)), authorsByName));
+  for (const f of [...byBase.values()].sort()) {
+    const raw = await readFile(join(postsDir, f), 'utf8');
+    const wire = f.endsWith('.md') ? fileToWire(raw) : JSON.parse(raw);
+    posts.push(projectPost(wire, authorsByName));
   }
   posts.sort((a, b) => String(b.publishDate || '').localeCompare(String(a.publishDate || '')));
   return posts;

package/src/lib/render.mjs

@@ -35,11 +35,16 @@ import nunjucks from 'nunjucks';
 const SLICE_RE = /([A-Za-z_][\w.]*)\[(\d*):(\d*)\]/g;
 
 export function preprocessHubl(src) {
-  return src.replace(SLICE_RE, (_m, expr, a, b) => {
-    const start = a === '' ? '0' : a;
-    const end = b === '' ? 'null' : b;
-    return `${expr}|hubslice(${start},${end})`;
-  });
+  return src
+    // HubL's `{% module "name" path=... label=... %}` space-separates the name from
+    // its kwargs; Nunjucks' parseSignature wants a comma there. Insert one after the
+    // name literal so the remaining `key=value, ...` parses as keyword args.
+    .replace(/(\{%-?\s*module\s+(?:"[^"]*"|'[^']*'))\s+(?=[A-Za-z_])/g, '$1, ')
+    .replace(SLICE_RE, (_m, expr, a, b) => {
+      const start = a === '' ? '0' : a;
+      const end = b === '' ? 'null' : b;
+      return `${expr}|hubslice(${start},${end})`;
+    });
 }
 
 // ---------------------------------------------------------------------------
@@ -72,6 +77,22 @@ export function resolveStaticRefs(value, { assetBase = '/assets' } = {}) {
   return String(value).replace(/@asset:([^\s"'<>)]+)/g, (_m, nameRef) => `${assetBase}/${nameRef}`);
 }
 
+// HubSpot evaluates HubL functions embedded in rich-text bodies at render time; the
+// static target passes bodies through as data, so any such macro must be resolved
+// here. Currently the only one in the corpus is a Wistia video embed,
+// `{{ script_embed('wistia', '<id>', ...) }}` -> Wistia's responsive inline embed.
+const WISTIA_EMBED_RE = /\{\{\s*script_embed\(\s*['"]wistia['"]\s*,\s*['"]([A-Za-z0-9]+)['"][^}]*\)\s*\}\}/gi;
+export function resolveHublEmbeds(value) {
+  if (value == null) return value;
+  return String(value).replace(WISTIA_EMBED_RE, (_m, id) =>
+    `<script src="https://fast.wistia.com/embed/medias/${id}.jsonp" async></script>`
+    + '<script src="https://fast.wistia.com/assets/external/E-v1.js" async></script>'
+    + '<div class="wistia_responsive_padding" style="padding:56.25% 0 0 0;position:relative;">'
+    + '<div class="wistia_responsive_wrapper" style="height:100%;left:0;position:absolute;top:0;width:100%;">'
+    + `<div class="wistia_embed wistia_async_${id} videoFoam=true" style="height:100%;position:relative;width:100%;">&nbsp;</div>`
+    + '</div></div>');
+}
+
 // get_asset_url('../css/main.css') -> "/css/main.css". Theme assets live at the
 // repo root (css/ js/ images/); HubL refs them template-relative with leading ../.
 function assetUrl(path) {
@@ -80,6 +101,8 @@ function assetUrl(path) {
 
 const MONTHS = ['January', 'February', 'March', 'April', 'May', 'June',
   'July', 'August', 'September', 'October', 'November', 'December'];
+const MONTHS_ABBR = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+  'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
 
 function localizeDate(iso) {
   if (!iso) return '';
@@ -88,29 +111,111 @@ function localizeDate(iso) {
   return `${MONTHS[d.getUTCMonth()]} ${d.getUTCDate()}, ${d.getUTCFullYear()}`;
 }
 
+// Fallback tag slug when no authoritative tags.json mapping is supplied.
+export function slugify(s) {
+  return String(s).toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+// HubL's format_date(value, style). Mirrors HubSpot's en-US styles: medium uses an
+// abbreviated month ("Jun 6, 2026"), long/full the full month, short is numeric.
+// UTC so the build is deterministic regardless of the runner's timezone.
+function formatDate(value, style = 'medium') {
+  if (!value) return '';
+  const d = new Date(value);
+  if (Number.isNaN(d.getTime())) return String(value);
+  const m = d.getUTCMonth();
+  const day = d.getUTCDate();
+  const y = d.getUTCFullYear();
+  if (style === 'short') return `${m + 1}/${day}/${String(y).slice(2)}`;
+  if (style === 'long' || style === 'full') return `${MONTHS[m]} ${day}, ${y}`;
+  return `${MONTHS_ABBR[m]} ${day}, ${y}`;
+}
+
 // ---------------------------------------------------------------------------
 // Neutral post view -> HubL `content` shim (snake_case, refs resolved for the
 // static target). Reused for the page being rendered AND for related-post cards
 // returned by blog_recent_posts().
 // ---------------------------------------------------------------------------
-function postContent(post, { baseUrl = '', assetBase = '/assets' } = {}) {
+function postContent(post, { baseUrl = '', assetBase = '/assets', tagSlugFor } = {}) {
   const author = post.author || null;
+  const tagSlug = tagSlugFor || slugify;
   return {
     name: post.title,
     html_title: post.htmlTitle,
     meta_description: post.metaDescription,
-    post_body: resolveStaticRefs(post.body, { assetBase }),
-    post_summary: resolveStaticRefs(post.summary, { assetBase }),
+    post_body: resolveHublEmbeds(resolveStaticRefs(post.body, { assetBase })),
+    post_summary: resolveHublEmbeds(resolveStaticRefs(post.summary, { assetBase })),
+    publish_date: post.publishDate,
     publish_date_localized: localizeDate(post.publishDate),
     featured_image: post.featuredImage ? resolveStaticRefs(post.featuredImage, { assetBase }) : '',
     featured_image_alt_text: post.featuredImageAlt,
-    tag_list: post.tags.map((t) => ({ name: t })),
+    tag_list: post.tags.map((t) => ({ name: t, slug: tagSlug(t) })),
     blog_post_author: author ? { display_name: author.name, bio: resolveStaticRefs(author.bio, { assetBase }) } : null,
     absolute_url: baseUrl + post.route,
     canonical_url: baseUrl + post.route,
   };
 }
 
+// Recursively resolve @asset refs inside any string value of a field tree.
+function resolveDeep(val, opts) {
+  if (typeof val === 'string') return resolveStaticRefs(val, opts);
+  if (Array.isArray(val)) return val.map((v) => resolveDeep(v, opts));
+  if (val && typeof val === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(val)) out[k] = resolveDeep(v, opts);
+    return out;
+  }
+  return val;
+}
+
+// fields.json -> { fieldName: default }. A group field (with `children`) yields a
+// nested object of its children's defaults; leaf fields yield their `default`.
+function moduleFieldDefaults(fields) {
+  const out = {};
+  if (!Array.isArray(fields)) return out;
+  for (const f of fields) {
+    if (!f || !f.name) continue;
+    if (Array.isArray(f.children) && f.children.length) out[f.name] = moduleFieldDefaults(f.children);
+    else if ('default' in f) out[f.name] = f.default;
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// {% module "name" path="../modules/x.module" label="..." field=val %} — HubL's
+// module instantiation tag. HubSpot renders the module's module.html with a
+// `module` variable whose fields resolve by precedence: fields.json defaults <
+// inline template args < the page's stored widget body (content-view's modules map,
+// passed in context as __page_modules). The module bytes are read relative to the
+// theme root (path's leading ../ stripped). Returns SafeString (no double-escape).
+// ---------------------------------------------------------------------------
+function ModuleExtension(env, siteDir, opts) {
+  this.tags = ['module'];
+  this.parse = function parse(parser, nodes) {
+    const tok = parser.nextToken();
+    const args = parser.parseSignature(null, true);
+    parser.advanceAfterBlockEnd(tok.value);
+    return new nodes.CallExtension(this, 'run', args);
+  };
+  this.run = function run(context, name, kwargs) {
+    kwargs = kwargs && kwargs.__keywords ? kwargs : {};
+    const { path = '', label: _label, ...inlineFields } = kwargs;
+    const modDir = join(siteDir, String(path).replace(/^(\.\.\/)+/, ''));
+    let defaults = {};
+    try {
+      defaults = moduleFieldDefaults(JSON.parse(readFileSync(join(modDir, 'fields.json'), 'utf8')));
+    } catch {
+      /* a module may ship no fields.json */
+    }
+    const pageVals = (context.lookup('__page_modules') || {})[name] || {};
+    const merged = { ...defaults, ...inlineFields, ...pageVals };
+    const html = env.renderString(preprocessHubl(readFileSync(join(modDir, 'module.html'), 'utf8')), {
+      module: resolveDeep(merged, opts),
+    });
+    return new nunjucks.runtime.SafeString(html);
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Environment factory. One env per render call keeps globals (blog_recent_posts
 // closure, header/footer includes) bound to the current site + options.
@@ -120,6 +225,7 @@ function makeEnv(siteDir, { site, opts }) {
 
   env.addFilter('hubslice', (str, start, end) =>
     end === null || end === undefined ? String(str ?? '').slice(start) : String(str ?? '').slice(start, end));
+  env.addFilter('format_date', formatDate);
 
   env.addGlobal('get_asset_url', assetUrl);
   env.addGlobal('html_lang', opts.lang || 'en');
@@ -132,6 +238,8 @@ function makeEnv(siteDir, { site, opts }) {
   env.addGlobal('blog_recent_posts', (_group, count) =>
     (site?.posts || []).slice(0, count || 5).map((p) => postContent(p, opts)));
 
+  env.addExtension('ModuleExtension', new ModuleExtension(env, siteDir, opts));
+
   return env;
 }
 
@@ -150,4 +258,56 @@ export function renderPost(post, { siteDir, site, baseUrl = '', assetBase = '/as
   return env.render(template, context);
 }
 
-export { postContent, assetUrl, localizeDate, makeEnv };
+// ---------------------------------------------------------------------------
+// Neutral page view -> HubL `content` shim. Pages reference content.* far less
+// than posts (most copy lives in modules), but templates use name/title/meta and
+// the canonical/absolute URL for SEO + social tags.
+// ---------------------------------------------------------------------------
+function pageContent(page, { baseUrl = '' } = {}) {
+  return {
+    name: page.title,
+    html_title: page.htmlTitle,
+    meta_description: page.metaDescription,
+    absolute_url: baseUrl + page.route,
+    canonical_url: baseUrl + page.route,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public: render one neutral page view (with its module map) to an HTML string.
+// ---------------------------------------------------------------------------
+export function renderPage(page, { siteDir, site, baseUrl = '', assetBase = '/assets', lang = 'en',
+  headerIncludes = '', footerIncludes = '' } = {}) {
+  const opts = { baseUrl, assetBase, lang, headerIncludes, footerIncludes };
+  const env = makeEnv(siteDir, { site, opts });
+  const context = {
+    content: pageContent(page, opts),
+    __page_modules: page.modules || {},
+    nav_active: null,
+    nav_hide_cta: false,
+  };
+  return env.render(page.template, context);
+}
+
+// ---------------------------------------------------------------------------
+// Public: render the blog LISTING (templates/blog.html) for a set of posts —
+// the main /blog index or a /blog/tag/<slug> page. HubSpot exposes the page's
+// posts as `contents` (a list of content objects) plus pagination vars; we pass
+// all posts on one page (no pagination), so the template's paginate block (guarded
+// by contents.total_page_count > 1) is inert.
+// ---------------------------------------------------------------------------
+export function renderBlogListing(posts, { siteDir, site, baseUrl = '', assetBase = '/assets', lang = 'en',
+  headerIncludes = '', footerIncludes = '', tagSlugFor, route = '/blog' } = {}) {
+  const opts = { baseUrl, assetBase, lang, headerIncludes, footerIncludes, tagSlugFor };
+  const env = makeEnv(siteDir, { site, opts });
+  const context = {
+    contents: posts.map((p) => postContent(p, opts)),
+    content: { absolute_url: baseUrl + route, canonical_url: baseUrl + route },
+    current_page_num: 1,
+    nav_active: null,
+    nav_hide_cta: false,
+  };
+  return env.render('templates/blog.html', context);
+}
+
+export { postContent, pageContent, assetUrl, localizeDate, makeEnv };