astro-theme-popular 0.5.0 → 0.7.0

package/README.md

@@ -21,6 +21,16 @@ export default defineConfig({
 });
 ```
 
+Override any theme component with your own, without forking:
+
+```js
+popular({ overrides: { Header: './src/overrides/Header.astro' } })
+```
+
+Overridable: `Header`, `Footer`, `Hero`, `EventRow`, `PostCard`,
+`OrganizerCard`, `AuthorBox`, `PageHero`. Your file receives the same props
+the theme component does.
+
 Disable any injected route group when your site replaces it (also the
 answer when you provide your own `/` or `/rss.xml`):
 

package/index.mjs

@@ -6,6 +6,11 @@
  *     integrations: [mdx(), popular()],
  *   });
  *
+ * Override components without forking: popular({ overrides: { Header:
+ *   './src/overrides/Header.astro' } }). Theme code imports overridable
+ * components from popular:component/<Name>; the integration resolves each
+ * to the adopter's file or the theme default.
+ *
  * Theme config (SITE, STRINGS, BRAND, NAV, ...) lives in the adopter's
  * `popular.config.ts` (same named exports as the classic src/config.ts;
  * the shape is the parity contract, see PARITY.md). Theme code reads it
@@ -13,6 +18,21 @@
  */
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import sitemap from '@astrojs/sitemap';
+
+/* loading="lazy" decoding="async" on markdown images (CWV parity with the
+   Hugo render hook). Dependency-free HAST walk. */
+function rehypeLazyImages() {
+  const walk = (node) => {
+    if (node.tagName === 'img') {
+      node.properties = node.properties || {};
+      if (!('loading' in node.properties)) node.properties.loading = 'lazy';
+      if (!('decoding' in node.properties)) node.properties.decoding = 'async';
+    }
+    (node.children || []).forEach(walk);
+  };
+  return (tree) => walk(tree);
+}
 
 /* Injected routes, grouped by opt-out key: popular({ routes: { speakers:
    false } }) skips a group. Disabling is also the durable answer when your
@@ -35,14 +55,29 @@ const ROUTES = {
     ['/organizers/[...page]', 'organizers/[...page].astro'],
     ['/organizers/[...slug]', 'organizers/[slug].astro'],
   ],
-  speakers: [['/speakers/[...slug]', 'speakers/[slug].astro']],
-  venues: [['/venues/[...slug]', 'venues/[slug].astro']],
+  speakers: [
+    ['/speakers', 'speakers/index.astro'],
+    ['/speakers/[...slug]', 'speakers/[slug].astro'],
+  ],
+  venues: [
+    ['/venues', 'venues/index.astro'],
+    ['/venues/[...slug]', 'venues/[slug].astro'],
+  ],
   tags: [['/tags/[tag]/[...page]', 'tags/[tag]/[...page].astro']],
+  // Opt-in talk archive: injected always, but the page only builds when
+  // SITE.talks is true (gated in the route's getStaticPaths).
+  talks: [['/talks/[...page]', 'talks/[...page].astro']],
   rss: [['/rss.xml', 'rss.xml.js']],
+  robots: [['/robots.txt', 'robots.txt.ts']],
+  calendar: [['/events/calendar.ics', 'events/calendar.ics.ts']],
+  llms: [['/llms.txt', 'llms.txt.ts']],
 };
 
+const OVERRIDABLE = ['Header', 'Footer', 'Hero', 'EventRow', 'PostCard', 'OrganizerCard', 'AuthorBox', 'PageHero'];
+
 export default function popular(options = {}) {
   const configFile = options.configFile ?? './popular.config.ts';
+  const overrides = options.overrides ?? {};
   return {
     name: 'astro-theme-popular',
     hooks: {
@@ -51,6 +86,8 @@ export default function popular(options = {}) {
         const userConfig = path.resolve(root, configFile);
         addWatchFile(userConfig);
         updateConfig({
+          integrations: [sitemap()],
+          markdown: { rehypePlugins: [rehypeLazyImages] },
           vite: {
             plugins: [
               {
@@ -64,6 +101,20 @@ export default function popular(options = {}) {
                   }
                 },
               },
+              {
+                name: 'popular:component',
+                resolveId(id) {
+                  if (id.startsWith('popular:component/')) return '\0' + id;
+                },
+                load(id) {
+                  if (!id.startsWith('\0popular:component/')) return;
+                  const name = id.slice('\0popular:component/'.length);
+                  const target = overrides[name]
+                    ? path.resolve(root, overrides[name])
+                    : `astro-theme-popular/components/${name}.astro`;
+                  return `export { default } from ${JSON.stringify(target)};`;
+                },
+              },
             ],
           },
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-theme-popular",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Popular: a warm, community-first Astro theme for meetups, clubs and fan communities. Ships as an Astro integration.",
   "type": "module",
   "license": "MIT",
@@ -27,7 +27,8 @@
     "./scripts/*": "./scripts/*"
   },
   "dependencies": {
-    "@astrojs/rss": "^4.0.0"
+    "@astrojs/rss": "^4.0.0",
+    "@astrojs/sitemap": "^3.0.0"
   },
   "peerDependencies": {
     "astro": "^7.0.0"

package/schemas.ts

@@ -57,6 +57,22 @@ const events = defineCollection({
     venueNotes: z.string().optional(), // e.g. "Buzz 204 at the side door."; overrides the venue page's notes
     rsvp: z.string().optional(),
     meetupUrl: z.string().optional(), // metadata convention; the theme renders no external links on event rows
+    cancelled: z.boolean().default(false), // EventCancelled JSON-LD + visible badge
+    online: z.boolean().default(false), // OnlineEventAttendanceMode + VirtualLocation
+    price: z.union([z.number(), z.string()]).optional(), // machine price for Offer
+    currency: z.string().optional(), // ISO currency for price
+    cost: z.string().optional(), // free-text displayed cost (e.g. "15 CAD")
+    // §3 talk archive (all optional). Simple case: event-level recording/slides
+    // (single-talk meetups). Multi-talk case: a talks[] array, which wins over
+    // the event-level recording/slides when present.
+    recording: z.string().optional(),
+    slides: z.string().optional(),
+    talks: z.array(z.object({
+      title: z.string(),
+      speaker: z.string().optional(), // speaker-collection slug, same resolution as `speakers`
+      recording: z.string().optional(),
+      slides: z.string().optional(),
+    })).optional(),
   }),
 });
 
@@ -109,6 +125,10 @@ const venues = defineCollection({
     photo: z.string().optional(),
     notes: z.string().optional(), // arrival notes inherited by events held here
     accessibility: z.string().optional(),
+    wheelchair: z.boolean().default(false), // step-free access badge
+    transit: z.string().optional(),
+    parking: z.string().optional(),
+    access: z.string().optional(), // freeform markdown: washrooms, quiet space, childcare, scent policy
     website: z.string().optional(),
   }),
 });

package/src/components/AuthorBox.astro

@@ -23,7 +23,7 @@ const bio = d ? ((d as any).bio ?? (d as any).description) : undefined;
 <div class="g-persona g-persona--primary">
   {d && (
     <>
-      {d.photo && <img class="g-persona__img" src={d.photo} alt={entry.data.title} />}
+      {d.photo && <img class="g-persona__img" src={d.photo} alt={entry.data.title} loading="lazy" decoding="async" />}
       <div>
         <div class="g-persona__name"><a href={`${base}${entry.id}/`} style="color:inherit">{d.title}</a></div>
         {d.role && <div class="g-persona__role">{d.role}</div>}
@@ -37,7 +37,7 @@ const bio = d ? ((d as any).bio ?? (d as any).description) : undefined;
   )}
   {guest && (
     <>
-      {guest.photo && <img class="g-persona__img" src={guest.photo} alt={guest.name} />}
+      {guest.photo && <img class="g-persona__img" src={guest.photo} alt={guest.name} loading="lazy" decoding="async" />}
       <div>
         <div class="g-persona__name">{guest.name} <span class="g-badge g-badge--soft" style="vertical-align:middle">{STRINGS.guest}</span></div>
         {guest.title && <div class="g-persona__role">{guest.title}</div>}

package/src/components/DemoBar.astro

@@ -22,6 +22,8 @@ const bar = import.meta.env.DEV ? null : ((cfg as Record<string, any>).DEMO_BAR
       .g-demobar a:hover { color: #fff; background: rgba(255,255,255,0.08); }
       .g-demobar a.is-current { background: var(--color-primary); color: #fff; }
       @media (max-width: 640px) { .g-demobar__label { display: none; } }
+      /* Reserve space so the fixed demo bar never covers the footer credit. */
+      .g-footer__bottom { padding-bottom: 72px; }
     </style>
     <nav class="g-demobar" aria-label="Theme demos">
       <a href="#" data-demo-home><i class="fa-solid fa-star" aria-hidden="true"></i>Popular</a>

package/src/components/EventRow.astro

@@ -2,10 +2,12 @@
 import { SITE, STRINGS } from 'popular:config';
 import type { CollectionEntry } from 'astro:content';
 import { safeCollection } from '../lib/collections';
+import { eventHasRecording } from '../lib/talks';
 
 interface Props { event: CollectionEntry<'events'> }
 const { event } = Astro.props;
 const d = event.data;
+const hasRecording = eventHasRecording(d);
 
 /* Venue: a venueRef to the venues collection wins over the flat fields. */
 const venuePage = d.venueRef ? (await safeCollection('venues')).find((v) => v.id === d.venueRef) : undefined;
@@ -47,9 +49,14 @@ const day = d.date.toLocaleDateString(SITE.locale, { month: 'short', day: 'numer
     {speakerLine && (
       <div class="g-event__meta"><i class="fa-solid fa-microphone-lines" aria-hidden="true"></i>{speakerLine}</div>
     )}
+    {hasRecording && (
+      <div class="g-event__meta"><i class="fa-solid fa-circle-play" aria-hidden="true"></i>{STRINGS.hasRecording}</div>
+    )}
   </div>
   <div class="g-event__aside">
-    {tbd
+    {d.cancelled
+      ? <span class="g-badge g-badge--danger g-badge--soft">{STRINGS.eventCancelled}</span>
+      : tbd
       ? <span class="g-badge g-badge--warning g-badge--soft">{STRINGS.venueWanted}</span>
       : <span class="g-badge g-badge--success g-badge--soft">{STRINGS.confirmed}</span>}
     {d.rsvp && (

package/src/components/EventsEmpty.astro

@@ -0,0 +1,25 @@
+---
+/** Designed empty state for zero upcoming events (§5). Shown on the home page
+ *  and events list instead of a blank section: a message, then the chat CTA
+ *  (if SITE.community.chat is set, §4) and the calendar-subscribe link.
+ *  The calendar link mirrors Hugo's OutputFormats "Calendar" endpoint. */
+import { SITE, STRINGS } from 'popular:config';
+
+const chat = (SITE as Record<string, any>).community?.chat;
+const calendar = '/events/calendar.ics';
+const external = (url: string) => !url.startsWith('/');
+---
+<div class="g-empty">
+  <span class="g-medallion g-medallion--lg"><i class="fa-solid fa-calendar-day" aria-hidden="true"></i></span>
+  <p class="g-lead">{STRINGS.noUpcomingEvents}</p>
+  {(chat?.url || calendar) && (
+    <div class="g-row" style="justify-content:center">
+      {chat?.url && (
+        <a class="g-btn g-btn--primary" href={chat.url} {...(external(chat.url) ? { rel: 'noopener', target: '_blank' } : {})}>
+          <i class="fa-solid fa-comments" aria-hidden="true"></i> {chat.label ?? STRINGS.joinChat}
+        </a>
+      )}
+      <a class="g-btn g-btn--outline" href={calendar}><i class="fa-solid fa-calendar-plus" aria-hidden="true"></i> {STRINGS.subscribeCalendar}</a>
+    </div>
+  )}
+</div>

package/src/components/FAQ.astro

@@ -0,0 +1,30 @@
+---
+/** FAQ block: wraps <FAQItem> children (native <details>, zero JS; answers in
+ *  the DOM for indexing + AI answer engines). Emits FAQPage JSON-LD collected
+ *  from the rendered items (gated on SITE.seo.faqJsonLd, default true),
+ *  mirroring Hugo's faq shortcode. No FAQ rich results are expected (Google
+ *  restricts them); this aids agents and future-proofs. */
+import { SITE } from 'popular:config';
+import { jsonld } from '../lib/jsonld';
+
+const html = await Astro.slots.render('default');
+const strip = (s: string) => s.replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim();
+const items = [...html.matchAll(
+  /<summary class="g-faq__q">([\s\S]*?)<\/summary>\s*<div class="g-faq__a[^"]*">([\s\S]*?)<\/div>\s*<\/details>/g,
+)].map((m) => ({ q: strip(m[1]), a: strip(m[2]) }));
+
+const emit = (SITE as Record<string, any>).seo?.faqJsonLd !== false && items.length;
+const faqLd = emit
+  ? jsonld({
+      '@context': 'https://schema.org',
+      '@type': 'FAQPage',
+      mainEntity: items.map((i) => ({
+        '@type': 'Question',
+        name: i.q,
+        acceptedAnswer: { '@type': 'Answer', text: i.a },
+      })),
+    })
+  : null;
+---
+<div class="g-faq" set:html={html} />
+{faqLd && <script type="application/ld+json" set:html={faqLd} />}

package/src/components/FAQItem.astro

@@ -0,0 +1,10 @@
+---
+/** One FAQ item: native <details> (zero JS). `q` is the question; the default
+ *  slot is the markdown answer. `open` renders it expanded. */
+interface Props { q: string; open?: boolean }
+const { q, open = false } = Astro.props;
+---
+<details class="g-faq__item" open={open}>
+  <summary class="g-faq__q">{q}</summary>
+  <div class="g-faq__a g-prose"><slot /></div>
+</details>

package/src/components/Footer.astro

@@ -1,7 +1,10 @@
 ---
-import { SITE, FOOTER, SOCIAL } from 'popular:config';
+import { SITE, FOOTER, SOCIAL, STRINGS } from 'popular:config';
+import { version } from '../../package.json';
 const year = new Date().getFullYear();
 const credit = (FOOTER as { credit?: { label: string; url: string } }).credit;
+const chat = (SITE as Record<string, any>).community?.chat;
+const showVersion = !!credit && credit.url.includes('mariatta.ca');
 ---
 
 <footer class="g-footer">
@@ -35,7 +38,10 @@ const credit = (FOOTER as { credit?: { label: string; url: string } }).credit;
   <div class="g-footer__bottom">
     <div class="g-container">
       <span>© {year} {SITE.title}</span>
-      {credit && <span><a href={credit.url} rel="noopener">{credit.label}</a></span>}
+      {chat && (
+        <span><a href={chat.url} {...(chat.url.startsWith('/') ? {} : { rel: 'noopener', target: '_blank' })}><i class="fa-solid fa-comments" aria-hidden="true"></i> {chat.label ?? STRINGS.joinChat}</a></span>
+      )}
+      {credit && <span><a href={credit.url} rel="noopener">{credit.label}</a>{showVersion && <> · v{version}</>}</span>}
       {FOOTER.tagline && <span>{FOOTER.tagline}</span>}
     </div>
   </div>

package/src/components/Gallery.astro

@@ -0,0 +1,7 @@
+---
+/** Photo gallery (§6): a CSS-grid of <Photo> figures. No JS, no lightbox
+ *  (each photo links to its full-size image). Mirrors the Hugo `gallery`
+ *  shortcode. Use in MDX:
+ *    <Gallery><Photo src="/images/recap-1.jpg" alt="…" caption="…" /></Gallery> */
+---
+<div class="g-gallery"><slot /></div>

package/src/components/Notice.astro

@@ -0,0 +1,19 @@
+---
+/** Site-wide notice banner (§5). Reads optional SITE.notice = { text, url? }.
+ *  Static, not dismissible, no JS. Rendered by BaseLayout above the header.
+ *  Text is inline-markdown rendered (parity with Hugo's notice.html). */
+import { SITE, STRINGS } from 'popular:config';
+import { inlineMarkdown } from '../lib/inline-md';
+
+const notice = (SITE as Record<string, any>).notice;
+const text: string | undefined = notice?.text;
+const html = text ? inlineMarkdown(text) : '';
+---
+{text && (
+  <div class="g-notice" role="status">
+    <div class="g-notice__inner">
+      <i class="fa-solid fa-circle-info" aria-hidden="true"></i>
+      <span><Fragment set:html={html} />{notice.url && <> <a href={notice.url}>{STRINGS.learnMore}</a></>}</span>
+    </div>
+  </div>
+)}

package/src/components/OrganizerCard.astro

@@ -7,7 +7,7 @@ const d = organizer.data;
 ---
 
 <div class="g-org">
-  {d.photo && <a href={`/organizers/${organizer.id}/`}><img class="g-org__img" src={d.photo} alt={d.title} loading="lazy" /></a>}
+  {d.photo && <a href={`/organizers/${organizer.id}/`}><img class="g-org__img" src={d.photo} alt={d.title} loading="lazy" decoding="async" /></a>}
   <div class="g-org__name"><a href={`/organizers/${organizer.id}/`} style="color:inherit">{d.title}</a></div>
   {d.role && <div class="g-org__role">{d.role}</div>}
   {d.description && <p class="g-org__bio">{d.description}</p>}

package/src/components/PageHero.astro

@@ -3,12 +3,17 @@ interface Props {
   eyebrow?: string;
   title: string;
   lead?: string;
+  backHref?: string;
+  backLabel?: string;
 }
-const { eyebrow, title, lead } = Astro.props;
+const { eyebrow, title, lead, backHref, backLabel } = Astro.props;
 ---
 
 <header class="g-pagehero">
   <div class="g-container">
+    {backHref && (
+      <div style="margin-bottom:1rem"><a href={backHref} style="display:inline-flex;gap:.4rem;align-items:center;font-size:var(--text-sm);font-weight:var(--weight-medium)"><i class="fa-solid fa-arrow-left" aria-hidden="true"></i> {backLabel}</a></div>
+    )}
     {eyebrow && <span class="g-eyebrow">{eyebrow}</span>}
     <h1>{title}</h1>
     {lead && <p class="g-pagehero__lead">{lead}</p>}

package/src/components/Photo.astro

@@ -0,0 +1,12 @@
+---
+/** A gallery photo (§6). `alt` is required: the build throws with an
+ *  actionable message when it is missing, keeping the image-alt CI green by
+ *  construction. No lightbox, the figure links to the full-size image. */
+interface Props { src: string; alt: string; caption?: string; }
+const { src, alt, caption } = Astro.props;
+if (!alt) throw new Error(`<Photo src="${src}"> requires a non-empty alt`);
+---
+<figure class="g-gallery__item">
+  <a href={src}><img src={src} alt={alt} loading="lazy" decoding="async" /></a>
+  {caption && <figcaption>{caption}</figcaption>}
+</figure>

package/src/components/PostCard.astro

@@ -22,7 +22,7 @@ if (!names.length && d.author) names.push(d.author);
 
 <article class="g-card" data-tags={d.tags.join(',')}>
   {d.image && (
-    <a href={href} class="g-card__media"><img src={d.image} alt={d.title} loading="lazy" /></a>
+    <a href={href} class="g-card__media"><img src={d.image} alt={d.title} loading="lazy" decoding="async" /></a>
   )}
   <div class="g-card__body">
     {(month || names.length > 0) && (

package/src/components/Pullquote.astro

@@ -0,0 +1,11 @@
+---
+/** Pull-quote (§6): a styled blockquote with optional attribution. Mirrors the
+ *  Hugo `pullquote` shortcode. Use in MDX:
+ *    <Pullquote cite="A happy member">The best Tuesday of my month.</Pullquote> */
+interface Props { cite?: string; }
+const { cite } = Astro.props;
+---
+<figure class="g-pullquote">
+  <blockquote><slot /></blockquote>
+  {cite && <figcaption>{cite}</figcaption>}
+</figure>

package/src/components/SpeakerInvite.astro

@@ -0,0 +1,16 @@
+---
+/** §7: "Your name here?" invite card appended to the speakers list when
+ *  SITE.speakers.invite is true. Links to the /speak/ CFP page. Off by
+ *  default, so sites that do not solicit talks show nothing. */
+import { SITE, STRINGS } from 'popular:config';
+const invite = (SITE as Record<string, any>).speakers?.invite === true;
+---
+{invite && (
+  <div class="g-persona g-persona--primary">
+    <span class="g-medallion g-medallion--lg" aria-hidden="true"><i class="fa-solid fa-microphone-lines"></i></span>
+    <div>
+      <div class="g-persona__name"><a href="/speak/" style="color:inherit">{STRINGS.speakerInviteTitle} <i class="fa-solid fa-arrow-right" aria-hidden="true"></i></a></div>
+      <p class="g-persona__bio">{STRINGS.speakerInviteBody}</p>
+    </div>
+  </div>
+)}

package/src/layouts/BaseLayout.astro

@@ -7,9 +7,10 @@ import '../styles/tokens/spacing.css';
 import '../styles/tokens/elevation.css';
 import '../styles/base.css';
 import '../styles/components.css';
-import Header from '../components/Header.astro';
-import Footer from '../components/Footer.astro';
+import Header from 'popular:component/Header';
+import Footer from 'popular:component/Footer';
 import DemoBar from '../components/DemoBar.astro';
+import Notice from '../components/Notice.astro';
 import { SITE, BRAND, STRINGS } from 'popular:config';
 
 interface Props {
@@ -18,8 +19,11 @@ interface Props {
   image?: string;
   /** Set on blog posts: emits og:type=article plus article meta. */
   article?: { published?: Date; modified?: Date; authors?: string[]; tags?: string[] };
+  imageAlt?: string;
+  noindex?: boolean;
 }
-const { title, description, image, article } = Astro.props;
+const { title, description, image, article, imageAlt, noindex } = Astro.props;
+const ogLocale = SITE.locale.replace('-', '_');
 const pageTitle = title ? `${title} · ${SITE.title}` : `${SITE.title}, ${SITE.tagline}`;
 const desc = description ?? SITE.description;
 const ogImage = image ?? SITE.ogImage;
@@ -71,6 +75,7 @@ const brandCss = `html:root{${vars.join(';')}}`;
     <title>{pageTitle}</title>
     <meta name="description" content={desc} />
     <meta property="og:site_name" content={SITE.title} />
+    <meta property="og:locale" content={ogLocale} />
     <meta property="og:title" content={title ?? SITE.title} />
     <meta property="og:description" content={desc} />
     <meta property="og:url" content={canonical} />
@@ -81,17 +86,22 @@ const brandCss = `html:root{${vars.join(';')}}`;
     {article?.authors?.map((a) => <meta property="article:author" content={a} />)}
     {article?.tags?.map((t) => <meta property="article:tag" content={t} />)}
     {ogImage && <meta property="og:image" content={new URL(ogImage, Astro.site ?? Astro.url)} />}
+    {ogImage && <meta property="og:image:alt" content={imageAlt ?? title ?? SITE.title} />}
     <meta name="twitter:card" content={ogImage ? 'summary_large_image' : 'summary'} />
     <link rel="icon" href={SITE.favicon ?? SITE.logo} />
     <link rel="alternate" type="application/rss+xml" title={(SITE as Record<string, any>).rssTitle ?? SITE.title} href={new URL("rss.xml", Astro.site ?? Astro.url)} />
+    {SITE.fontAwesome.includes("font-awesome/6.5.2/css/all.min.css") && <link rel="preconnect" href="https://cdnjs.cloudflare.com" crossorigin />}
     <link rel="stylesheet" href={SITE.fontAwesome} referrerpolicy="no-referrer"
       integrity={SITE.fontAwesome.includes("font-awesome/6.5.2/css/all.min.css") ? "sha384-PPIZEGYM1v8zp5Py7UjFb79S58UeqCL9pYVnVPURKEqvioPROaVAJKKLzvH2rDnI" : undefined}
       crossorigin={SITE.fontAwesome.includes("font-awesome/6.5.2/css/all.min.css") ? "anonymous" : undefined} />
     {(SITE as Record<string, any>).customCSS?.map((href: string) => <link rel="stylesheet" href={href} />)}
+    {noindex && <meta name="robots" content="noindex,follow" />}
     <style is:inline id="popular-brand" set:html={brandCss}></style>
+    <slot name="head" />
   </head>
   <body data-copy-label={STRINGS.copyCode} data-checklist-done={STRINGS.checklistDone}>
     <a class="g-skip" href="#main">{STRINGS.skipToContent}</a>
+    <Notice />
     <Header />
     <main id="main">
       <slot />

package/src/lib/eventld.ts

@@ -0,0 +1,95 @@
+/** Event JSON-LD helpers, mirroring partials/jsonld-event.html.
+ *  The time-parsing contract and its vectors live in PARITY.md; the Hugo and
+ *  Astro implementations must agree on every vector. */
+
+/** Parse an event `time` free-text field to event-local "HH:MM", or null.
+ *  Leading token only: "6:00 PM · doors 5:30" -> "18:00"; "doors 5:30" -> null. */
+export function parseEventTime(raw: string | undefined): string | null {
+  const m = (raw ?? '').trim().match(/^(\d{1,2}):(\d{2})\s*(am|pm)?/i);
+  if (!m) return null;
+  let h = parseInt(m[1], 10);
+  const min = parseInt(m[2], 10);
+  const mer = m[3]?.toLowerCase();
+  if (mer) {
+    if (h < 1 || h > 12) return null;
+    if (mer === 'pm' && h < 12) h += 12;
+    if (mer === 'am' && h === 12) h = 0;
+  } else if (h > 23) {
+    return null;
+  }
+  if (min > 59) return null;
+  return `${String(h).padStart(2, '0')}:${String(min).padStart(2, '0')}`;
+}
+
+/** startDate = YYYY-MM-DD, or YYYY-MM-DDTHH:MM when a leading time parses. */
+export function eventStartDate(date: Date, time: string | undefined): string {
+  const day = date.toISOString().slice(0, 10);
+  const hm = parseEventTime(time);
+  return hm ? `${day}T${hm}` : day;
+}
+
+/** Recursively key-sort so output matches Hugo's jsonify (sorted, no spaces). */
+function sortKeys(v: any): any {
+  if (Array.isArray(v)) return v.map(sortKeys);
+  if (v && typeof v === 'object') {
+    return Object.fromEntries(Object.keys(v).sort().map((k) => [k, sortKeys(v[k])]));
+  }
+  return v;
+}
+export function jsonld(obj: Record<string, any>): string {
+  return JSON.stringify(sortKeys(obj));
+}
+
+export interface EventLdInput {
+  title: string;
+  date: Date;
+  time?: string;
+  description?: string;
+  cancelled?: boolean;
+  online?: boolean;
+  price?: number | string;
+  currency?: string;
+  cost?: string;
+  image?: string;
+  rsvp?: string;
+  permalink: string;
+  siteUrl: string;
+  siteTitle: string;
+  defaultCurrency: string;
+  venue?: { name: string; address?: string };
+  performers?: string[];
+}
+
+export function buildEventLd(i: EventLdInput): Record<string, any> {
+  const ld: Record<string, any> = {
+    '@context': 'https://schema.org',
+    '@type': 'Event',
+    name: i.title,
+    startDate: eventStartDate(i.date, i.time),
+    eventStatus: i.cancelled ? 'https://schema.org/EventCancelled' : 'https://schema.org/EventScheduled',
+    eventAttendanceMode: i.online
+      ? 'https://schema.org/OnlineEventAttendanceMode'
+      : 'https://schema.org/OfflineEventAttendanceMode',
+    organizer: { '@type': 'Organization', name: i.siteTitle, url: i.siteUrl },
+  };
+  const desc = (i.description ?? '').trim();
+  if (desc) ld.description = desc.length > 300 ? desc.slice(0, 299) + '…' : desc;
+  if (i.online) {
+    ld.location = { '@type': 'VirtualLocation', url: i.rsvp || i.permalink };
+  } else if (i.venue) {
+    ld.location = { '@type': 'Place', name: i.venue.name };
+    if (i.venue.address) ld.location.address = i.venue.address;
+  }
+  if (i.image) ld.image = i.image;
+  if (i.performers && i.performers.length) {
+    ld.performer = i.performers.map((name) => ({ '@type': 'Person', name }));
+  }
+  if (i.price !== undefined && i.price !== '') {
+    ld.isAccessibleForFree = false;
+    ld.offers = { '@type': 'Offer', price: String(i.price), priceCurrency: i.currency || i.defaultCurrency, availability: 'https://schema.org/InStock', url: i.permalink };
+  } else if (!i.cost) {
+    ld.isAccessibleForFree = true;
+    ld.offers = { '@type': 'Offer', price: '0', priceCurrency: i.defaultCurrency, availability: 'https://schema.org/InStock', url: i.permalink };
+  }
+  return ld;
+}