astro-theme-popular 0.8.1 → 0.9.0

package/index.mjs

@@ -20,18 +20,94 @@ 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() {
+/* Markdown body hooks: loading="lazy" decoding="async" on images (CWV parity
+   with Hugo's render-image.html), and site-absolute links/images prefixed with
+   the configured `base` so `![](/images/x.png)` and `[the handbook](/handbook/)`
+   survive a subpath install (parity with Hugo's render hooks passing paths
+   through relURL). Everything the templates write is handled by src/lib/url.ts
+   instead; MDX component props (<Photo src="/images/x.png">) are JSX, not HAST,
+   so the components prefix those themselves.
+
+   Registered on the active markdown processor rather than through
+   `markdown.rehypePlugins`: Astro 7's default processor is Sätteri, which does
+   not run remark/rehype plugins at all, and plugins added by an integration
+   after config validation are never coerced, so they are silently dropped
+   (Astro warns "your satteri processor doesn't run them" on every build).
+   Mutating processor.options is what does reach both Markdown and MDX: Astro
+   preserves the processor's reference identity, and @astrojs/mdx reads the same
+   object at astro:config:done. */
+
+const prefixPath = (value, prefix) =>
+  typeof value === 'string' &&
+  prefix &&
+  value.startsWith('/') &&
+  !value.startsWith('//') &&
+  value !== prefix &&
+  !value.startsWith(`${prefix}/`)
+    ? prefix + value
+    : value;
+
+/* Sätteri shape: filtered visitors, mutations through ctx.setProperty. */
+function satteriMarkdownHooks(prefix) {
+  return {
+    name: 'popular-markdown-hooks',
+    element: [
+      {
+        filter: ['img'],
+        visit(node, ctx) {
+          const props = node.properties ?? {};
+          if (!('loading' in props)) ctx.setProperty(node, 'loading', 'lazy');
+          if (!('decoding' in props)) ctx.setProperty(node, 'decoding', 'async');
+          const src = prefixPath(props.src, prefix);
+          if (src !== props.src) ctx.setProperty(node, 'src', src);
+        },
+      },
+      {
+        filter: ['a'],
+        visit(node, ctx) {
+          const props = node.properties ?? {};
+          const href = prefixPath(props.href, prefix);
+          if (href !== props.href) ctx.setProperty(node, 'href', href);
+        },
+      },
+    ],
+  };
+}
+
+/* unified/rehype shape, for a site that opted into `markdown.processor:
+   unified({...})` (or set the deprecated markdown.rehypePlugins, which Astro
+   coerces into one). Dependency-free HAST walk. */
+function rehypeMarkdownHooks(prefix) {
   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';
+    const props = node.properties;
+    if (props) {
+      if (node.tagName === 'img') {
+        if (!('loading' in props)) props.loading = 'lazy';
+        if (!('decoding' in props)) props.decoding = 'async';
+        props.src = prefixPath(props.src, prefix);
+      }
+      if (node.tagName === 'a') props.href = prefixPath(props.href, prefix);
     }
     (node.children || []).forEach(walk);
   };
-  return (tree) => walk(tree);
+  return () => (tree) => walk(tree);
+}
+
+function registerMarkdownHooks(config, logger) {
+  /* config.base is '/' with no base configured, '/my-community' with one. */
+  const prefix = (config.base ?? '/').replace(/\/+$/, '');
+  const processor = config.markdown?.processor;
+  if (Array.isArray(processor?.options?.hastPlugins)) {
+    processor.options.hastPlugins.push(satteriMarkdownHooks(prefix));
+  } else if (Array.isArray(processor?.options?.rehypePlugins)) {
+    processor.options.rehypePlugins.push(rehypeMarkdownHooks(prefix));
+  } else {
+    logger.warn(
+      `markdown.processor "${processor?.name ?? 'unknown'}" takes neither hastPlugins nor rehypePlugins: ` +
+        'markdown images will not get loading="lazy"' +
+        (prefix ? ', and site-absolute links in content will not carry the base' : ''),
+    );
+  }
 }
 
 /* Injected routes, grouped by opt-out key: popular({ routes: { speakers:
@@ -81,13 +157,13 @@ export default function popular(options = {}) {
   return {
     name: 'astro-theme-popular',
     hooks: {
-      'astro:config:setup': ({ config, injectRoute, injectScript, updateConfig, addWatchFile }) => {
+      'astro:config:setup': ({ config, injectRoute, injectScript, updateConfig, addWatchFile, logger }) => {
         const root = fileURLToPath(config.root);
         const userConfig = path.resolve(root, configFile);
         addWatchFile(userConfig);
+        registerMarkdownHooks(config, logger);
         updateConfig({
           integrations: [sitemap()],
-          markdown: { rehypePlugins: [rehypeLazyImages] },
           vite: {
             plugins: [
               {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-theme-popular",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Popular: a warm, community-first Astro theme for meetups, clubs and fan communities. Ships as an Astro integration.",
   "type": "module",
   "license": "MIT",
@@ -20,6 +20,7 @@
   "exports": {
     ".": "./index.mjs",
     "./schemas": "./schemas.ts",
+    "./url": "./src/lib/url.ts",
     "./pages/*": "./src/pages/*",
     "./components/*": "./src/components/*",
     "./layouts/*": "./src/layouts/*",

package/src/components/AuthorBox.astro

@@ -4,6 +4,7 @@ import { STRINGS } from 'popular:config';
  *  Pass either `entry` (an authors-collection entry, linked to its profile)
  *  or `guest` (inline guestAuthors object from a post's front matter). */
 import type { CollectionEntry } from 'astro:content';
+import { withBase } from '../lib/url';
 
 interface Guest {
   name: string; title?: string; photo?: string; bio?: string; website?: string;
@@ -23,28 +24,28 @@ 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} loading="lazy" decoding="async" />}
+      {d.photo && <img class="g-persona__img" src={withBase(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>
+        <div class="g-persona__name"><a href={withBase(`${base}${entry.id}/`)} style="color:inherit">{d.title}</a></div>
         {d.role && <div class="g-persona__role">{d.role}</div>}
         {bio && <p class="g-persona__bio">{bio}</p>}
         <div class="g-persona__socials">
-          {(d as any).website && <a href={(d as any).website} aria-label={STRINGS.website} rel="noopener" target="_blank"><i class="fa-solid fa-globe" aria-hidden="true"></i></a>}
-          {d.social.map((s) => <a href={s.url} aria-label={s.label} rel="noopener" target="_blank"><i class={s.icon} aria-hidden="true"></i></a>)}
+          {(d as any).website && <a href={withBase((d as any).website)} aria-label={STRINGS.website} rel="noopener" target="_blank"><i class="fa-solid fa-globe" aria-hidden="true"></i></a>}
+          {d.social.map((s) => <a href={withBase(s.url)} aria-label={s.label} rel="noopener" target="_blank"><i class={s.icon} aria-hidden="true"></i></a>)}
         </div>
       </div>
     </>
   )}
   {guest && (
     <>
-      {guest.photo && <img class="g-persona__img" src={guest.photo} alt={guest.name} loading="lazy" decoding="async" />}
+      {guest.photo && <img class="g-persona__img" src={withBase(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>}
         {guest.bio && <p class="g-persona__bio">{guest.bio}</p>}
         <div class="g-persona__socials">
-          {guest.website && <a href={guest.website} aria-label={STRINGS.website} rel="noopener" target="_blank"><i class="fa-solid fa-globe" aria-hidden="true"></i></a>}
-          {(guest.social ?? []).map((s) => <a href={s.url} aria-label={s.label} rel="noopener" target="_blank"><i class={s.icon} aria-hidden="true"></i></a>)}
+          {guest.website && <a href={withBase(guest.website)} aria-label={STRINGS.website} rel="noopener" target="_blank"><i class="fa-solid fa-globe" aria-hidden="true"></i></a>}
+          {(guest.social ?? []).map((s) => <a href={withBase(s.url)} aria-label={s.label} rel="noopener" target="_blank"><i class={s.icon} aria-hidden="true"></i></a>)}
         </div>
       </div>
     </>

package/src/components/EventRow.astro

@@ -2,6 +2,7 @@
 import { SITE, STRINGS } from 'popular:config';
 import type { CollectionEntry } from 'astro:content';
 import { safeCollection } from '../lib/collections';
+import { withBase } from '../lib/url';
 import { eventHasRecording } from '../lib/talks';
 
 interface Props { event: CollectionEntry<'events'> }
@@ -41,7 +42,7 @@ const day = d.date.toLocaleDateString(SITE.locale, { month: 'short', day: 'numer
         {d.tags.map((t) => <span class="g-tag">{t}</span>)}
       </div>
     )}
-    <h3><a href={`/events/${event.id}/`} style="color:inherit">{d.title}</a></h3>
+    <h3><a href={withBase(`/events/${event.id}/`)} style="color:inherit">{d.title}</a></h3>
     {d.description && <p>{d.description}</p>}
     <div class="g-event__meta">
       <i class="fa-solid fa-location-dot" aria-hidden="true"></i>{venueName ?? STRINGS.venueTba}{venueAddress && ` · ${venueAddress}`}
@@ -60,7 +61,7 @@ const day = d.date.toLocaleDateString(SITE.locale, { month: 'short', day: 'numer
       ? <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 && (
-      <a class="g-btn g-btn--primary g-btn--sm" href={d.rsvp}><i class="fa-solid fa-calendar" aria-hidden="true"></i>{STRINGS.rsvp}</a>
+      <a class="g-btn g-btn--primary g-btn--sm" href={withBase(d.rsvp)}><i class="fa-solid fa-calendar" aria-hidden="true"></i>{STRINGS.rsvp}</a>
     )}
   </div>
 </div>

package/src/components/EventsEmpty.astro

@@ -4,6 +4,7 @@
  *  (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';
+import { withBase } from '../lib/url';
 
 const chat = (SITE as Record<string, any>).community?.chat;
 const calendar = '/events/calendar.ics';
@@ -15,11 +16,11 @@ const external = (url: string) => !url.startsWith('/');
   {(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' } : {})}>
+        <a class="g-btn g-btn--primary" href={withBase(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>
+      <a class="g-btn g-btn--outline" href={withBase(calendar)}><i class="fa-solid fa-calendar-plus" aria-hidden="true"></i> {STRINGS.subscribeCalendar}</a>
     </div>
   )}
 </div>

package/src/components/Footer.astro

@@ -1,5 +1,6 @@
 ---
 import { SITE, FOOTER, SOCIAL, STRINGS } from 'popular:config';
+import { withBase } from '../lib/url';
 import { version } from '../../package.json';
 const year = new Date().getFullYear();
 const credit = (FOOTER as { credit?: { label: string; url: string } }).credit;
@@ -10,12 +11,12 @@ const showVersion = !!credit && credit.url.includes('mariatta.ca');
 <footer class="g-footer">
   <div class="g-container g-footer__top">
     <div class="g-footer__brand">
-      {SITE.logo && <img src={SITE.logo} alt={SITE.title} />}
+      {SITE.logo && <img src={withBase(SITE.logo)} alt={SITE.title} />}
       {SITE.landAcknowledgement && <p class="g-footer__ack">{SITE.landAcknowledgement}</p>}
       {SOCIAL.length > 0 && (
         <div style="display:flex;gap:0.5rem;margin-top:0.25rem">
           {SOCIAL.map((s) => (
-            <a class="g-social" href={s.url} aria-label={s.label} rel="me noopener" target="_blank">
+            <a class="g-social" href={withBase(s.url)} aria-label={s.label} rel="me noopener" target="_blank">
               <i class={s.icon} aria-hidden="true"></i>
             </a>
           ))}
@@ -28,7 +29,7 @@ const showVersion = !!credit && credit.url.includes('mariatta.ca');
         <div class="g-footer__col-title">{col.title}</div>
         <ul>
           {col.links.map((l) => (
-            <li><a href={l.href}>{l.label}</a></li>
+            <li><a href={withBase(l.href)}>{l.label}</a></li>
           ))}
         </ul>
       </div>
@@ -39,9 +40,9 @@ const showVersion = !!credit && credit.url.includes('mariatta.ca');
     <div class="g-container">
       <span>© {year} {SITE.title}</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>
+        <span><a href={withBase(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>}
+      {credit && <span><a href={withBase(credit.url)} rel="noopener">{credit.label}</a>{showVersion && <> · v{version}</>}</span>}
       {FOOTER.tagline && <span>{FOOTER.tagline}</span>}
     </div>
   </div>

package/src/components/Header.astro

@@ -1,13 +1,16 @@
 ---
 import { SITE, NAV, CTA, STRINGS } from 'popular:config';
+import { withBase } from '../lib/url';
 const path = Astro.url.pathname;
-const isActive = (href: string) => href !== '/' && path.startsWith(href.replace(/\/$/, ''));
+/* Astro.url.pathname carries the site's base, so a config href has to gain
+   it too, or nothing is ever active on a subpath install. */
+const isActive = (href: string) => href !== '/' && path.startsWith(withBase(href).replace(/\/$/, ''));
 ---
 
 <header class="g-header">
   <nav class="g-container g-nav" aria-label={STRINGS.primaryNav}>
-    <a class="g-brand" href="/">
-      {SITE.logo && <img src={SITE.logo} alt={SITE.title} />}
+    <a class="g-brand" href={withBase('/')}>
+      {SITE.logo && <img src={withBase(SITE.logo)} alt={SITE.title} />}
       <span class="g-brand__text">
         <span class="g-brand__name">{SITE.brandName ?? SITE.title}</span>
         {SITE.brandSub && <span class="g-brand__sub">{SITE.brandSub}</span>}
@@ -23,25 +26,25 @@ const isActive = (href: string) => href !== '/' && path.startsWith(href.replace(
         l.children?.length ? (
           <li class="has-sub">
             <a
-              href={l.href}
+              href={withBase(l.href)}
               class={isActive(l.href) || l.children.some((c) => isActive(c.href)) ? 'is-active' : ''}
             >
               {l.label}<i class="fa-solid fa-chevron-down g-navlinks__caret" aria-hidden="true"></i>
             </a>
             <ul class="g-navlinks__sub">
               {l.children.map((c) => (
-                <li><a href={c.href} class={isActive(c.href) ? 'is-active' : ''}>{c.label}</a></li>
+                <li><a href={withBase(c.href)} class={isActive(c.href) ? 'is-active' : ''}>{c.label}</a></li>
               ))}
             </ul>
           </li>
         ) : (
-          <li><a href={l.href} class={isActive(l.href) ? 'is-active' : ''}>{l.label}</a></li>
+          <li><a href={withBase(l.href)} class={isActive(l.href) ? 'is-active' : ''}>{l.label}</a></li>
         )
       )}
     </ul>
 
     {CTA && (
-      <a class="g-btn g-btn--primary g-btn--sm g-nav__cta" href={CTA.url}>
+      <a class="g-btn g-btn--primary g-btn--sm g-nav__cta" href={withBase(CTA.url)}>
         {CTA.icon && <i class={CTA.icon} aria-hidden="true"></i>}{CTA.label}
       </a>
     )}

package/src/components/Notice.astro

@@ -4,6 +4,7 @@
  *  Text is inline-markdown rendered (parity with Hugo's notice.html). */
 import { SITE, STRINGS } from 'popular:config';
 import { inlineMarkdown } from '../lib/inline-md';
+import { withBase } from '../lib/url';
 
 const notice = (SITE as Record<string, any>).notice;
 const text: string | undefined = notice?.text;
@@ -13,7 +14,7 @@ const html = text ? inlineMarkdown(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>
+      <span><Fragment set:html={html} />{notice.url && <> <a href={withBase(notice.url)}>{STRINGS.learnMore}</a></>}</span>
     </div>
   </div>
 )}

package/src/components/OrganizerCard.astro

@@ -1,5 +1,6 @@
 ---
 import type { CollectionEntry } from 'astro:content';
+import { withBase } from '../lib/url';
 
 interface Props { organizer: CollectionEntry<'organizers'> }
 const { organizer } = Astro.props;
@@ -7,14 +8,14 @@ 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" decoding="async" /></a>}
-  <div class="g-org__name"><a href={`/organizers/${organizer.id}/`} style="color:inherit">{d.title}</a></div>
+  {d.photo && <a href={withBase(`/organizers/${organizer.id}/`)}><img class="g-org__img" src={withBase(d.photo)} alt={d.title} loading="lazy" decoding="async" /></a>}
+  <div class="g-org__name"><a href={withBase(`/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>}
   {d.social.length > 0 && (
     <div class="g-persona__socials">
       {d.social.map((s) => (
-        <a href={s.url} aria-label={s.label} rel="noopener" target="_blank"><i class={s.icon} aria-hidden="true"></i></a>
+        <a href={withBase(s.url)} aria-label={s.label} rel="noopener" target="_blank"><i class={s.icon} aria-hidden="true"></i></a>
       ))}
     </div>
   )}

package/src/components/PageHero.astro

@@ -1,4 +1,6 @@
 ---
+import { withBase } from '../lib/url';
+
 interface Props {
   eyebrow?: string;
   title: string;
@@ -12,7 +14,7 @@ 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>
+      <div style="margin-bottom:1rem"><a href={withBase(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>

package/src/components/Pagination.astro

@@ -5,6 +5,7 @@
    itself, page N to `${base}page/N/`, matching Hugo's paginator URLs.
    Renders nothing when everything fits on one page. */
 import { STRINGS } from 'popular:config';
+import { withBase } from '../lib/url';
 
 interface Props {
   current: number;
@@ -12,24 +13,24 @@ interface Props {
   base: string;
 }
 const { current, total, base } = Astro.props;
-const url = (n: number) => (n === 1 ? base : `${base}page/${n}/`);
+const pageHref = (n: number) => withBase(n === 1 ? base : `${base}page/${n}/`);
 const pages = Array.from({ length: total }, (_, i) => i + 1);
 ---
 
 {total > 1 && (
   <nav class="g-pager" aria-label={STRINGS.paginationLabel}>
     {current > 1 && (
-      <a class="g-pager__nav" href={url(current - 1)} rel="prev"><i class="fa-solid fa-chevron-left" aria-hidden="true"></i>{STRINGS.paginationPrev}</a>
+      <a class="g-pager__nav" href={pageHref(current - 1)} rel="prev"><i class="fa-solid fa-chevron-left" aria-hidden="true"></i>{STRINGS.paginationPrev}</a>
     )}
     {pages.map((n) =>
       n === current ? (
         <span class="g-pager__num is-active" aria-current="page">{n}</span>
       ) : (
-        <a class="g-pager__num" href={url(n)}>{n}</a>
+        <a class="g-pager__num" href={pageHref(n)}>{n}</a>
       )
     )}
     {current < total && (
-      <a class="g-pager__nav" href={url(current + 1)} rel="next">{STRINGS.paginationNext}<i class="fa-solid fa-chevron-right" aria-hidden="true"></i></a>
+      <a class="g-pager__nav" href={pageHref(current + 1)} rel="next">{STRINGS.paginationNext}<i class="fa-solid fa-chevron-right" aria-hidden="true"></i></a>
     )}
   </nav>
 )}

package/src/components/Photo.astro

@@ -2,11 +2,13 @@
 /** 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. */
+import { withBase } from '../lib/url';
+
 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>
+  <a href={withBase(src)}><img src={withBase(src)} alt={alt} loading="lazy" decoding="async" /></a>
   {caption && <figcaption>{caption}</figcaption>}
 </figure>

package/src/components/PostCard.astro

@@ -1,13 +1,14 @@
 ---
 import { SITE, SECTIONS_MAP } from 'popular:config';
 import { tagSlug } from '../lib/slugs';
+import { withBase } from '../lib/url';
 import type { CollectionEntry } from 'astro:content';
 import { safeCollection } from '../lib/collections';
 
 interface Props { post: CollectionEntry<'blog'> }
 const { post } = Astro.props;
 const d = post.data;
-const href = `/blog/${post.id}/`;
+const href = withBase(`/blog/${post.id}/`);
 // Mirror of the Hugo card's date guard: this component can render date-less
 // content, so omit the date (and, below, the whole eyebrow) when absent.
 const hasDate = d.date instanceof Date && !Number.isNaN(+d.date) && d.date.getFullYear() > 1;
@@ -22,7 +23,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" decoding="async" /></a>
+    <a href={href} class="g-card__media"><img src={withBase(d.image)} alt={d.title} loading="lazy" decoding="async" /></a>
   )}
   <div class="g-card__body">
     {(month || names.length > 0) && (
@@ -33,7 +34,7 @@ if (!names.length && d.author) names.push(d.author);
     {d.tags.length > 0 && (
       <div class="g-card__footer">
         {d.tags.slice(0, 2).map((t) => (
-          <a class="g-tag" href={`/tags/${tagSlug(t)}/`}>{t}</a>
+          <a class="g-tag" href={withBase(`/tags/${tagSlug(t)}/`)}>{t}</a>
         ))}
       </div>
     )}

package/src/components/SpeakerInvite.astro

@@ -3,13 +3,14 @@
  *  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';
+import { withBase } from '../lib/url';
 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>
+      <div class="g-persona__name"><a href={withBase('/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

@@ -12,6 +12,7 @@ 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';
+import { withBase, absoluteUrl } from '../lib/url';
 
 interface Props {
   title?: string;
@@ -27,6 +28,8 @@ 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;
+/* Astro.url.pathname already carries the base; Astro.site does not, hence
+   absoluteUrl() for everything built from a path we wrote ourselves. */
 const canonical = new URL(Astro.url.pathname, Astro.site ?? Astro.url);
 
 /* Brand overrides: mirrors the Hugo theme's brand-vars.html partial. */
@@ -85,16 +88,16 @@ const brandCss = `html:root{${vars.join(';')}}`;
     {article?.modified && <meta property="article:modified_time" content={article.modified.toISOString()} />}
     {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" content={absoluteUrl(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)} />
+    <link rel="icon" href={withBase(SITE.favicon ?? SITE.logo)} />
+    <link rel="alternate" type="application/rss+xml" title={(SITE as Record<string, any>).rssTitle ?? SITE.title} href={absoluteUrl('/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} />)}
+    {(SITE as Record<string, any>).customCSS?.map((href: string) => <link rel="stylesheet" href={withBase(href)} />)}
     {noindex && <meta name="robots" content="noindex,follow" />}
     <style is:inline id="popular-brand" set:html={brandCss}></style>
     <slot name="head" />

package/src/lib/inline-md.ts

@@ -3,6 +3,8 @@
  *  `.RenderString`: supports links, bold, emphasis, and inline code, and
  *  HTML-escapes everything else. Not a full Markdown parser; block syntax
  *  (headings, lists, images) is intentionally out of scope. */
+import { withBase } from './url';
+
 const escapeHtml = (s: string): string =>
   s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 
@@ -12,7 +14,7 @@ export function inlineMarkdown(src: string): string {
   s = s.replace(
     /\[([^\]]+)\]\((https?:\/\/[^\s)]+|\/[^\s)]*)\)/g,
     (_m, label, href) =>
-      `<a href="${href}"${href.startsWith('/') ? '' : ' rel="noopener" target="_blank"'}>${label}</a>`,
+      `<a href="${withBase(href)}"${href.startsWith('/') ? '' : ' rel="noopener" target="_blank"'}>${label}</a>`,
   );
   s = s.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>');
   s = s.replace(/(^|[^*])\*([^*]+)\*/g, '$1<em>$2</em>');

package/src/lib/url.ts

@@ -0,0 +1,39 @@
+/** Base-aware URL helpers.
+ *
+ *  A site can be served from a subpath: `base: '/my-community'` in
+ *  astro.config.mjs, which is what a GitHub project page
+ *  (user.github.io/repo/) needs. Astro rewrites the asset URLs it generates
+ *  itself, but every path the theme writes by hand is a literal string Astro
+ *  never sees, so it has to be prefixed here or it 404s on a subpath install.
+ *  The Hugo twin does the same job with relURL/absURL (see PARITY.md).
+ *
+ *  Both helpers are deliberately tolerant: they pass through anything that is
+ *  not a site-absolute path (external URLs, mailto:, tel:, #anchors, relative
+ *  paths) and anything already carrying the base. That makes them safe to
+ *  apply to adopter-authored values from popular.config.ts and to content
+ *  front matter, neither of which knows the base, so adopters never have to
+ *  rewrite their own links.
+ */
+
+/* BASE_URL is '/' when no base is configured, and '/my-community' when one
+   is (with a trailing slash if trailingSlash is 'always', hence the strip).
+   Normalizes to '' or '/my-community', so joining is plain concatenation. */
+const BASE = import.meta.env.BASE_URL.replace(/\/+$/, '');
+
+export function withBase(path: string): string;
+export function withBase(path: string | undefined | null): string | undefined;
+export function withBase(path: string | undefined | null): string | undefined {
+  if (!path || !BASE) return path ?? undefined;
+  /* Not site-absolute (external, protocol-relative, anchor, relative): leave it. */
+  if (path[0] !== '/' || path[1] === '/') return path;
+  if (path === BASE || path.startsWith(`${BASE}/`)) return path;
+  return BASE + path;
+}
+
+/** Absolute URL for canonicals, feeds and structured data: origin + base +
+ *  path. `Astro.site` (and the `site` passed to endpoints) is the bare
+ *  origin and does not carry the base, so a path resolved against it alone
+ *  silently drops the subpath. */
+export function absoluteUrl(path: string, site: URL | string | undefined): string {
+  return new URL(withBase(path), site ?? 'https://example.com').href;
+}

package/src/pages/[...slug].astro

@@ -4,6 +4,7 @@ import { STRINGS } from 'popular:config';
  *  and docs pages (handbook, runbooks, rendered with a scroll-spy TOC). */
 import { render } from 'astro:content';
 import { safeCollection } from '../lib/collections';
+import { withBase } from '../lib/url';
 import BaseLayout from '../layouts/BaseLayout.astro';
 import PageHero from 'popular:component/PageHero';
 
@@ -18,7 +19,7 @@ export async function getStaticPaths() {
       const cut = entry.id.lastIndexOf('/');
       const parentEntry = cut > 0 ? byId.get(entry.id.slice(0, cut)) : undefined;
       const parent = parentEntry
-        ? { href: `/${parentEntry.id}/`, label: parentEntry.data.shortTitle ?? parentEntry.data.title }
+        ? { href: withBase(`/${parentEntry.id}/`), label: parentEntry.data.shortTitle ?? parentEntry.data.title }
         : null;
       return { params: { slug: entry.id }, props: { entry, kind: 'page', parent } };
     }),
@@ -47,7 +48,7 @@ const allDocs = (await safeCollection('docs')).sort(
         {allDocs.map((e) => (
           <>
             <a
-              href={`/${e.id}/`}
+              href={withBase(`/${e.id}/`)}
               class={e.id === entry.id ? 'is-active' : ''}
               aria-current={e.id === entry.id ? 'page' : undefined}
             >{e.data.title}</a>

package/src/pages/blog/[...page].astro

@@ -4,6 +4,7 @@ import BaseLayout from '../../layouts/BaseLayout.astro';
 import PageHero from 'popular:component/PageHero';
 import PostCard from 'popular:component/PostCard';
 import Pagination from '../../components/Pagination.astro';
+import { withBase } from '../../lib/url';
 import { SECTIONS, STRINGS, PAGINATION } from 'popular:config';
 
 /* One route serves /blog/ and /blog/page/N/, matching the Hugo theme's
@@ -41,7 +42,7 @@ const { current, total, posts, tags } = Astro.props;
             </>
           )}
         </div>
-        <a class="g-btn g-btn--ghost g-btn--sm" href="/rss.xml" title={STRINGS.subscribeRssTitle}><i class="fa-solid fa-rss" aria-hidden="true"></i> {STRINGS.subscribeRss}</a>
+        <a class="g-btn g-btn--ghost g-btn--sm" href={withBase('/rss.xml')} title={STRINGS.subscribeRssTitle}><i class="fa-solid fa-rss" aria-hidden="true"></i> {STRINGS.subscribeRss}</a>
       </div>
       <div class="g-grid-3">
         {posts.map((p) => <PostCard post={p} />)}

package/src/pages/blog/[slug].astro

@@ -5,6 +5,7 @@ import BaseLayout from '../../layouts/BaseLayout.astro';
 import AuthorBox from 'popular:component/AuthorBox';
 import { SUPPORT, SITE, STRINGS, SECTIONS_MAP } from 'popular:config';
 import { buildBlogPostingLd, jsonld } from '../../lib/jsonld';
+import { withBase, absoluteUrl } from '../../lib/url';
 import { tagSlug } from '../../lib/slugs';
 
 export async function getStaticPaths() {
@@ -33,14 +34,14 @@ const bylineNames = [
   ...d.guestAuthors.map((g) => g.name),
 ];
 if (!bylineNames.length && d.author) bylineNames.push(d.author);
-const siteUrl = new URL('/', Astro.site ?? Astro.url).href;
+const siteUrl = absoluteUrl('/', Astro.site ?? Astro.url);
 const postLd = jsonld(buildBlogPostingLd({
   title: d.title,
   datePublished: d.date.toISOString().replace(/\.\d{3}Z$/, 'Z'),
   dateModified: d.date.toISOString().replace(/\.\d{3}Z$/, 'Z'),
   authors: bylineNames,
-  image: d.image ? new URL(d.image, Astro.site ?? Astro.url).href : undefined,
-  url: new URL(`/blog/${post.id}/`, Astro.site ?? Astro.url).href,
+  image: d.image ? absoluteUrl(d.image, Astro.site ?? Astro.url) : undefined,
+  url: absoluteUrl(`/blog/${post.id}/`, Astro.site ?? Astro.url),
   description: d.description,
   siteTitle: SITE.title,
   siteUrl,
@@ -55,12 +56,12 @@ const byline = bylineNames.length > 1
   <article>
     <header class="g-pagehero">
       <div class="g-container" style="padding-block:var(--space-6) var(--space-5)">
-        <a href="/blog/" style="display:inline-flex;gap:.4rem;align-items:center;font-size:var(--text-sm);font-weight:var(--weight-medium);margin-bottom:1rem">
+        <a href={withBase('/blog/')} style="display:inline-flex;gap:.4rem;align-items:center;font-size:var(--text-sm);font-weight:var(--weight-medium);margin-bottom:1rem">
           <i class="fa-solid fa-arrow-left" aria-hidden="true"></i> {STRINGS.allPosts}
         </a>
         {d.tags.length > 0 && (
           <div class="g-row" style="margin-bottom:.8rem">
-            {d.tags.map((t) => <a class="g-tag" href={`/tags/${tagSlug(t)}/`}>{t}</a>)}
+            {d.tags.map((t) => <a class="g-tag" href={withBase(`/tags/${tagSlug(t)}/`)}>{t}</a>)}
           </div>
         )}
         <h1 style="margin:0">{d.title}</h1>
@@ -74,7 +75,7 @@ const byline = bylineNames.length > 1
      <div class="g-article">
       {d.image && (
         <div style="border-radius:var(--radius-xl);overflow:hidden;box-shadow:var(--shadow-md);margin-bottom:var(--space-5)">
-          <img src={d.image} alt={d.title} style="width:100%;aspect-ratio:16/9;object-fit:cover" />
+          <img src={withBase(d.image)} alt={d.title} style="width:100%;aspect-ratio:16/9;object-fit:cover" />
         </div>
       )}
 
@@ -84,7 +85,7 @@ const byline = bylineNames.length > 1
         <>
           <h2 style="font-size:var(--text-xl);margin:var(--space-5) 0 1rem">{STRINGS.ourSpeaker}</h2>
           <div class="g-persona">
-            {d.speaker.photo && <img class="g-persona__img" src={d.speaker.photo} alt={d.speaker.name} />}
+            {d.speaker.photo && <img class="g-persona__img" src={withBase(d.speaker.photo)} alt={d.speaker.name} />}
             <div>
               <div class="g-persona__name">{d.speaker.name}</div>
               {d.speaker.title && <div class="g-persona__role">{d.speaker.title}</div>}
@@ -107,13 +108,13 @@ const byline = bylineNames.length > 1
       {(older || newer) && (
         <nav class="g-postnav" aria-label={STRINGS.postNavigation}>
           {older ? (
-            <a class="g-postnav__card" href={`/blog/${older.id}/`} rel="prev">
+            <a class="g-postnav__card" href={withBase(`/blog/${older.id}/`)} rel="prev">
               <span class="g-postnav__label"><i class="fa-solid fa-arrow-left" aria-hidden="true"></i> {STRINGS.olderPost}</span>
               <span class="g-postnav__title">{older.data.title}</span>
             </a>
           ) : <span></span>}
           {newer && (
-            <a class="g-postnav__card g-postnav__card--next" href={`/blog/${newer.id}/`} rel="next">
+            <a class="g-postnav__card g-postnav__card--next" href={withBase(`/blog/${newer.id}/`)} rel="next">
               <span class="g-postnav__label">{STRINGS.newerPost} <i class="fa-solid fa-arrow-right" aria-hidden="true"></i></span>
               <span class="g-postnav__title">{newer.data.title}</span>
             </a>
@@ -126,7 +127,7 @@ const byline = bylineNames.length > 1
           <div class="g-callout__body">{SUPPORT.text}</div>
           <div class="g-row">
             {SUPPORT.ctas.map((c) => (
-              <a class={`g-btn g-btn--${c.variant ?? 'secondary'}`} href={c.url}>{c.label}</a>
+              <a class={`g-btn g-btn--${c.variant ?? 'secondary'}`} href={withBase(c.url)}>{c.label}</a>
             ))}
           </div>
         </div>

package/src/pages/events/[...page].astro

@@ -4,6 +4,7 @@ import BaseLayout from '../../layouts/BaseLayout.astro';
 import PageHero from 'popular:component/PageHero';
 import EventRow from 'popular:component/EventRow';
 import Pagination from '../../components/Pagination.astro';
+import { withBase } from '../../lib/url';
 import EventsEmpty from '../../components/EventsEmpty.astro';
 import { SECTIONS, STRINGS, PAGINATION } from 'popular:config';
 
@@ -53,7 +54,7 @@ const groupByYear = (events: EventEntry[]) => {
         <span class="g-eyebrow">{STRINGS.comingUp}</span>
         <h2>{STRINGS.upcomingEvents}</h2>
         <p class="g-lead">{STRINGS.upcomingLead}</p>
-        <div class="g-row" style="margin-top:var(--space-3)"><a class="g-btn g-btn--outline g-btn--sm" href="/events/calendar.ics"><i class="fa-solid fa-calendar-plus" aria-hidden="true"></i> {STRINGS.subscribeCalendar}</a></div>
+        <div class="g-row" style="margin-top:var(--space-3)"><a class="g-btn g-btn--outline g-btn--sm" href={withBase('/events/calendar.ics')}><i class="fa-solid fa-calendar-plus" aria-hidden="true"></i> {STRINGS.subscribeCalendar}</a></div>
       </div>
       <div class="g-stack" style="margin-top:var(--space-4);gap:var(--space-3)">
         {groupByYear(upcoming).map((group) => (

package/src/pages/events/[slug].astro

@@ -1,6 +1,7 @@
 ---
 import { SITE, STRINGS } from 'popular:config';
 import { buildEventLd, jsonld } from '../../lib/eventld';
+import { withBase, absoluteUrl } from '../../lib/url';
 import { render } from 'astro:content';
 import { safeCollection } from '../../lib/collections';
 import BaseLayout from '../../layouts/BaseLayout.astro';
@@ -37,8 +38,8 @@ const talks = eventTalks(d, allSpeakers, event.id);
 const hasTalksArray = !!(d.talks && d.talks.length > 0);
 
 /* schema.org/Event JSON-LD (see lib/eventld; contract in PARITY.md). */
-const siteUrl = new URL('/', Astro.site ?? Astro.url).href;
-const permalink = new URL(`/events/${event.id}/`, Astro.site ?? Astro.url).href;
+const siteUrl = absoluteUrl('/', Astro.site ?? Astro.url);
+const permalink = absoluteUrl(`/events/${event.id}/`, Astro.site ?? Astro.url);
 const eventLd = jsonld(buildEventLd({
   title: d.title,
   date: d.date,
@@ -49,7 +50,7 @@ const eventLd = jsonld(buildEventLd({
   price: (d as any).price,
   currency: (d as any).currency,
   cost: (d as any).cost,
-  image: d.image ? new URL(d.image, Astro.site ?? Astro.url).href : undefined,
+  image: d.image ? absoluteUrl(d.image, Astro.site ?? Astro.url) : undefined,
   rsvp: d.rsvp,
   permalink,
   siteUrl,
@@ -66,7 +67,7 @@ const eventLd = jsonld(buildEventLd({
     <header class="g-pagehero">
       <div class="g-container" style="padding-block:var(--space-6) var(--space-5)">
         <div style="margin-bottom:1rem">
-          <a href="/events/" style="display:inline-flex;gap:.4rem;align-items:center;font-size:var(--text-sm);font-weight:var(--weight-medium)">
+          <a href={withBase('/events/')} 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> {STRINGS.allEvents}
           </a>
         </div>
@@ -78,13 +79,13 @@ const eventLd = jsonld(buildEventLd({
      <div class="g-article">
       <div class="g-meta-line" style="margin-bottom:var(--space-4)">
         <span><i class="fa-solid fa-location-dot" aria-hidden="true"></i> {venuePage
-          ? <><a href={`/venues/${venuePage.id}/`}>{venuePage.data.title}</a>{venuePage.data.address && ` · ${venuePage.data.address}`}</>
+          ? <><a href={withBase(`/venues/${venuePage.id}/`)}>{venuePage.data.title}</a>{venuePage.data.address && ` · ${venuePage.data.address}`}</>
           : <>{d.venue ?? STRINGS.venueTba}{d.address && ` · ${d.address}`}</>}</span>
         {venuePage?.data.wheelchair && <span><span class="g-badge g-badge--success g-badge--soft"><i class="fa-solid fa-wheelchair" aria-hidden="true"></i> {STRINGS.wheelchairAccessible}</span></span>}
-        {venuePage && (venuePage.data.transit || venuePage.data.parking || venuePage.data.access) && <span><a href={`/venues/${venuePage.id}/`}>{STRINGS.gettingThere}</a></span>}
+        {venuePage && (venuePage.data.transit || venuePage.data.parking || venuePage.data.access) && <span><a href={withBase(`/venues/${venuePage.id}/`)}>{STRINGS.gettingThere}</a></span>}
         {d.speaker && <span><i class="fa-solid fa-microphone-lines" aria-hidden="true"></i> {d.speaker}</span>}
-        {!hasTalksArray && d.recording && <span><a href={d.recording} rel="noopener" target="_blank"><i class="fa-solid fa-circle-play" aria-hidden="true"></i> {STRINGS.watchRecording}</a></span>}
-        {!hasTalksArray && d.slides && <span><a href={d.slides} rel="noopener" target="_blank"><i class="fa-solid fa-file-lines" aria-hidden="true"></i> {STRINGS.viewSlides}</a></span>}
+        {!hasTalksArray && d.recording && <span><a href={withBase(d.recording)} rel="noopener" target="_blank"><i class="fa-solid fa-circle-play" aria-hidden="true"></i> {STRINGS.watchRecording}</a></span>}
+        {!hasTalksArray && d.slides && <span><a href={withBase(d.slides)} rel="noopener" target="_blank"><i class="fa-solid fa-file-lines" aria-hidden="true"></i> {STRINGS.viewSlides}</a></span>}
       </div>
 
       {(d.checkin || venueNotes) && (
@@ -114,12 +115,12 @@ const eventLd = jsonld(buildEventLd({
               <div class="g-talk">
                 <div class="g-talk__title">{t.title}</div>
                 {t.speakerName && (
-                  <div class="g-talk__by"><i class="fa-solid fa-microphone-lines" aria-hidden="true"></i> {t.speakerSlug ? <a href={`/speakers/${t.speakerSlug}/`}>{t.speakerName}</a> : t.speakerName}</div>
+                  <div class="g-talk__by"><i class="fa-solid fa-microphone-lines" aria-hidden="true"></i> {t.speakerSlug ? <a href={withBase(`/speakers/${t.speakerSlug}/`)}>{t.speakerName}</a> : t.speakerName}</div>
                 )}
                 {(t.recording || t.slides) && (
                   <div class="g-row" style="gap:var(--space-2)">
-                    {t.recording && <a class="g-btn g-btn--sm g-btn--outline" href={t.recording} rel="noopener" target="_blank"><i class="fa-solid fa-circle-play" aria-hidden="true"></i> {STRINGS.watchRecording}</a>}
-                    {t.slides && <a class="g-btn g-btn--sm g-btn--ghost" href={t.slides} rel="noopener" target="_blank"><i class="fa-solid fa-file-lines" aria-hidden="true"></i> {STRINGS.viewSlides}</a>}
+                    {t.recording && <a class="g-btn g-btn--sm g-btn--outline" href={withBase(t.recording)} rel="noopener" target="_blank"><i class="fa-solid fa-circle-play" aria-hidden="true"></i> {STRINGS.watchRecording}</a>}
+                    {t.slides && <a class="g-btn g-btn--sm g-btn--ghost" href={withBase(t.slides)} rel="noopener" target="_blank"><i class="fa-solid fa-file-lines" aria-hidden="true"></i> {STRINGS.viewSlides}</a>}
                   </div>
                 )}
               </div>
@@ -130,7 +131,7 @@ const eventLd = jsonld(buildEventLd({
 
       {d.rsvp && (
         <div class="g-row" style="margin-top:var(--space-4)">
-          <a class="g-btn g-btn--primary g-btn--lg" href={d.rsvp}><i class="fa-solid fa-calendar" aria-hidden="true"></i> {STRINGS.rsvpExternal}</a>
+          <a class="g-btn g-btn--primary g-btn--lg" href={withBase(d.rsvp)}><i class="fa-solid fa-calendar" aria-hidden="true"></i> {STRINGS.rsvpExternal}</a>
         </div>
       )}
      </div>

package/src/pages/events/calendar.ics.ts

@@ -1,12 +1,13 @@
 import type { APIRoute } from 'astro';
 import { getCollection } from 'astro:content';
 import { buildIcs } from '../../lib/ical';
+import { absoluteUrl } from '../../lib/url';
 import { SITE } from 'popular:config';
 
 /* iCalendar feed: upcoming events plus the last 90 days. Mirrors the Hugo
    events/list.calendar.ics template. */
 export const GET: APIRoute = async ({ site }) => {
-  const base = site ?? new URL('https://example.com');
+  const origin = site ?? new URL('https://example.com');
   const cutoff = Date.now() - 90 * 24 * 60 * 60 * 1000;
   const events = (await getCollection('events'))
     .filter((e) => !e.data.draft && +e.data.date >= cutoff)
@@ -25,7 +26,7 @@ export const GET: APIRoute = async ({ site }) => {
         checkin: e.data.checkin,
         cancelled: e.data.cancelled,
         venue: v ? { name: v.data.title, address: v.data.address } : (e.data.venue ? { name: e.data.venue } : undefined),
-        permalink: new URL(`/events/${e.id}/`, base).href,
+        permalink: absoluteUrl(`/events/${e.id}/`, origin),
       };
     }),
     { siteTitle: SITE.title, dtstamp, durationMinutes: duration },

package/src/pages/index.astro

@@ -7,6 +7,7 @@ import OrganizerCard from 'popular:component/OrganizerCard';
 import EventsEmpty from '../components/EventsEmpty.astro';
 import { HOME, SITE, STRINGS, SECTIONS_MAP, SOCIAL } from 'popular:config';
 import { buildOrgLd, jsonld } from '../lib/jsonld';
+import { withBase, absoluteUrl } from '../lib/url';
 
 const now = new Date();
 const events = (await safeCollection('events')).filter((e) => !e.data.draft);
@@ -30,8 +31,8 @@ const h = HOME;
 const chat = (SITE as Record<string, any>).community?.chat;
 const orgLd = jsonld(buildOrgLd({
   name: SITE.title,
-  url: new URL('/', Astro.site ?? Astro.url).href,
-  logo: SITE.logo ? new URL(SITE.logo, Astro.site ?? Astro.url).href : undefined,
+  url: absoluteUrl('/', Astro.site ?? Astro.url),
+  logo: SITE.logo ? absoluteUrl(SITE.logo, Astro.site ?? Astro.url) : undefined,
   description: SITE.description,
   sameAs: SOCIAL.map((s) => s.url),
 }));
@@ -49,12 +50,12 @@ const orgLd = jsonld(buildOrgLd({
           {(h.hero.ctas || chat) && (
             <div class="g-row">
               {(h.hero.ctas ?? []).map((c) => (
-                <a class={`g-btn g-btn--lg g-btn--${c.variant ?? 'primary'}`} href={c.url}>
+                <a class={`g-btn g-btn--lg g-btn--${c.variant ?? 'primary'}`} href={withBase(c.url)}>
                   {'icon' in c && c.icon && <i class={c.icon} aria-hidden="true"></i>}{c.label}
                 </a>
               ))}
               {chat && (
-                <a class="g-btn g-btn--lg g-btn--secondary" href={chat.url} {...(chat.url.startsWith('/') ? {} : { rel: 'noopener', target: '_blank' })}>
+                <a class="g-btn g-btn--lg g-btn--secondary" href={withBase(chat.url)} {...(chat.url.startsWith('/') ? {} : { rel: 'noopener', target: '_blank' })}>
                   <i class="fa-solid fa-comments" aria-hidden="true"></i> {chat.label ?? STRINGS.joinChat}
                 </a>
               )}
@@ -62,7 +63,7 @@ const orgLd = jsonld(buildOrgLd({
           )}
         </div>
         {h.hero.image && (
-          <div class="g-hero__media"><img src={h.hero.image} alt={SITE.title} /></div>
+          <div class="g-hero__media"><img src={withBase(h.hero.image)} alt={SITE.title} /></div>
         )}
       </div>
     </section>
@@ -104,7 +105,7 @@ const orgLd = jsonld(buildOrgLd({
   {next && (
     <section class="g-bg-wash-soft">
       <div class="g-container g-feature">
-        {(next.data.image ?? h.hero.image) && <div class="g-feature__media"><img src={next.data.image ?? h.hero.image} alt={next.data.title} /></div>}
+        {(next.data.image ?? h.hero.image) && <div class="g-feature__media"><img src={withBase(next.data.image ?? h.hero.image)} alt={next.data.title} /></div>}
         <div class="g-feature__body">
           <span class="g-badge g-badge--soft"><i class="fa-solid fa-calendar" aria-hidden="true"></i> {STRINGS.nextMeetup}</span>
           <h2 style="margin:0">{next.data.title}</h2>
@@ -114,8 +115,8 @@ const orgLd = jsonld(buildOrgLd({
           </div>
           {next.data.description && <p style="margin:0;color:var(--text-muted);max-width:34rem">{next.data.description}</p>}
           <div class="g-row">
-            {next.data.rsvp && <a class="g-btn g-btn--primary" href={next.data.rsvp}><i class="fa-solid fa-calendar" aria-hidden="true"></i> {STRINGS.rsvpExternal}</a>}
-            <a class="g-btn g-btn--outline" href="/events/">{STRINGS.allEvents}</a>
+            {next.data.rsvp && <a class="g-btn g-btn--primary" href={withBase(next.data.rsvp)}><i class="fa-solid fa-calendar" aria-hidden="true"></i> {STRINGS.rsvpExternal}</a>}
+            <a class="g-btn g-btn--outline" href={withBase('/events/')}>{STRINGS.allEvents}</a>
           </div>
         </div>
       </div>
@@ -136,7 +137,7 @@ const orgLd = jsonld(buildOrgLd({
             <span class="g-eyebrow">{STRINGS.fromTheBlog}</span>
             <h2>{STRINGS.latestFromCommunity}</h2>
           </div>
-          <a class="g-btn g-btn--ghost" href="/blog/">{STRINGS.readTheBlog} <i class="fa-solid fa-arrow-right" aria-hidden="true"></i></a>
+          <a class="g-btn g-btn--ghost" href={withBase('/blog/')}>{STRINGS.readTheBlog} <i class="fa-solid fa-arrow-right" aria-hidden="true"></i></a>
         </div>
         <div class="g-grid-3" style="margin-top:var(--space-4)">
           {posts.map((p) => <PostCard post={p} />)}
@@ -157,7 +158,7 @@ const orgLd = jsonld(buildOrgLd({
           {organizers.slice(0, 3).map((o) => <OrganizerCard organizer={o} />)}
         </div>
         <div class="g-row" style="justify-content:center;margin-top:var(--space-4)">
-          <a class="g-btn g-btn--outline" href={`/${SECTIONS_MAP.team}/`}>All organizers</a>
+          <a class="g-btn g-btn--outline" href={withBase(`/${SECTIONS_MAP.team}/`)}>All organizers</a>
         </div>
       </div>
     </section>
@@ -178,7 +179,7 @@ const orgLd = jsonld(buildOrgLd({
             <figure class="g-quote">
               <blockquote>{t.quote}</blockquote>
               <figcaption>
-                {t.photo && <img src={t.photo} alt={t.name} />}
+                {t.photo && <img src={withBase(t.photo)} alt={t.name} />}
                 <div><span class="g-quote__name">{t.name}</span>{t.role && <span class="g-quote__role">{t.role}</span>}</div>
               </figcaption>
             </figure>
@@ -196,7 +197,7 @@ const orgLd = jsonld(buildOrgLd({
         {h.getInvolved.lead && <p style="margin:0;color:var(--ink-700);max-width:38rem">{h.getInvolved.lead}</p>}
         <div class="g-row" style="justify-content:center">
           {h.getInvolved.ctas.map((c) => (
-            <a class={`g-btn g-btn--${c.variant ?? 'primary'}`} href={c.url}>{c.label}</a>
+            <a class={`g-btn g-btn--${c.variant ?? 'primary'}`} href={withBase(c.url)}>{c.label}</a>
           ))}
         </div>
       </div>

package/src/pages/llms.txt.ts

@@ -1,5 +1,6 @@
 import type { APIRoute } from 'astro';
 import { getCollection } from 'astro:content';
+import { absoluteUrl } from '../lib/url';
 import { SITE } from 'popular:config';
 
 /* §8 llms.txt: a build-time plain-text summary for AI agents. Names the next
@@ -8,8 +9,7 @@ import { SITE } from 'popular:config';
    layouts/index.llms.txt. Always generated (SEO/discovery plumbing, like
    robots.txt). */
 export const GET: APIRoute = async ({ site }) => {
-  const base = site ?? new URL('https://example.com');
-  const abs = (p: string) => new URL(p, base).href;
+  const abs = (p: string) => absoluteUrl(p, site);
   const now = Date.now();
 
   const events = (await getCollection('events'))
@@ -31,7 +31,7 @@ export const GET: APIRoute = async ({ site }) => {
       : 'No upcoming events are scheduled right now.',
     '',
   );
-  if (chat) lines.push(`Join the community chat: ${chat.url}`, '');
+  if (chat) lines.push(`Join the community chat: ${abs(chat.url)}`, '');
   lines.push('## Links');
   if (pageIds.has('start')) lines.push(`Start here (newcomers): ${abs('/start/')}`);
   if (pageIds.has('about')) lines.push(`About and FAQ: ${abs('/about/')}`);

package/src/pages/robots.txt.ts

@@ -1,9 +1,10 @@
 import type { APIRoute } from 'astro';
+import { absoluteUrl } from '../lib/url';
 
 /* Generated so the Sitemap URL respects `site` + base path. @astrojs/sitemap
    emits sitemap-index.xml. */
 export const GET: APIRoute = ({ site }) => {
-  const sitemap = new URL('sitemap-index.xml', site ?? 'https://example.com').href;
+  const sitemap = absoluteUrl('/sitemap-index.xml', site);
   return new Response(`User-agent: *\nAllow: /\nSitemap: ${sitemap}\n`, {
     headers: { 'Content-Type': 'text/plain' },
   });

package/src/pages/rss.xml.js

@@ -1,5 +1,6 @@
 import rss from '@astrojs/rss';
 import { safeCollection } from '../lib/collections';
+import { withBase, absoluteUrl } from '../lib/url';
 import { SITE, SECTIONS_MAP } from 'popular:config';
 
 const escapeXml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
@@ -12,7 +13,7 @@ export async function GET(context) {
   return rss({
     title: SITE.title,
     description: SITE.description,
-    site: context.site,
+    site: absoluteUrl('/', context.site),
     xmlns: { dc: 'http://purl.org/dc/elements/1.1/' },
     items: posts.map((post) => {
       const names = [
@@ -24,7 +25,7 @@ export async function GET(context) {
         title: post.data.title,
         pubDate: post.data.date,
         description: post.data.description,
-        link: `/blog/${post.id}/`,
+        link: withBase(`/blog/${post.id}/`),
         categories: post.data.tags,
         customData: names.length ? `<dc:creator>${escapeXml(names.join(', '))}</dc:creator>` : undefined,
       };

package/src/pages/talks/[...page].astro

@@ -8,6 +8,7 @@
 import { SITE, STRINGS } from 'popular:config';
 import { safeCollection } from '../../lib/collections';
 import { collectTalks } from '../../lib/talks';
+import { withBase } from '../../lib/url';
 import BaseLayout from '../../layouts/BaseLayout.astro';
 import PageHero from 'popular:component/PageHero';
 
@@ -41,13 +42,13 @@ const fmt = (d: Date) => d.toLocaleDateString(SITE.locale, { month: 'short', day
           <div class="g-talk" data-tags={t.tags.join(',')}>
             <div class="g-talk__title">{t.title}</div>
             {t.speakerName && (
-              <div class="g-talk__by"><i class="fa-solid fa-microphone-lines" aria-hidden="true"></i> {t.speakerSlug ? <a href={`/speakers/${t.speakerSlug}/`}>{t.speakerName}</a> : t.speakerName}</div>
+              <div class="g-talk__by"><i class="fa-solid fa-microphone-lines" aria-hidden="true"></i> {t.speakerSlug ? <a href={withBase(`/speakers/${t.speakerSlug}/`)}>{t.speakerName}</a> : t.speakerName}</div>
             )}
-            <div class="g-talk__event"><i class="fa-solid fa-calendar-day" aria-hidden="true"></i> <a href={`/events/${t.eventId}/`}>{t.eventTitle}</a> · {fmt(t.date)}</div>
+            <div class="g-talk__event"><i class="fa-solid fa-calendar-day" aria-hidden="true"></i> <a href={withBase(`/events/${t.eventId}/`)}>{t.eventTitle}</a> · {fmt(t.date)}</div>
             {(t.recording || t.slides) && (
               <div class="g-row" style="gap:var(--space-2)">
-                {t.recording && <a class="g-btn g-btn--sm g-btn--outline" href={t.recording} rel="noopener" target="_blank"><i class="fa-solid fa-circle-play" aria-hidden="true"></i> {STRINGS.watchRecording}</a>}
-                {t.slides && <a class="g-btn g-btn--sm g-btn--ghost" href={t.slides} rel="noopener" target="_blank"><i class="fa-solid fa-file-lines" aria-hidden="true"></i> {STRINGS.viewSlides}</a>}
+                {t.recording && <a class="g-btn g-btn--sm g-btn--outline" href={withBase(t.recording)} rel="noopener" target="_blank"><i class="fa-solid fa-circle-play" aria-hidden="true"></i> {STRINGS.watchRecording}</a>}
+                {t.slides && <a class="g-btn g-btn--sm g-btn--ghost" href={withBase(t.slides)} rel="noopener" target="_blank"><i class="fa-solid fa-file-lines" aria-hidden="true"></i> {STRINGS.viewSlides}</a>}
               </div>
             )}
           </div>

package/src/pages/venues/[slug].astro

@@ -5,6 +5,7 @@ import { safeCollection } from '../../lib/collections';
 import BaseLayout from '../../layouts/BaseLayout.astro';
 import PageHero from '../../components/PageHero.astro';
 import EventRow from '../../components/EventRow.astro';
+import { withBase } from '../../lib/url';
 
 export async function getStaticPaths() {
   const venues = await safeCollection('venues');
@@ -24,10 +25,10 @@ const events = (await safeCollection('events'))
   <section class="g-bg-white g-section">
     <div class="g-container">
       <div class="g-article" style="margin-bottom:var(--space-5)">
-        {d.photo && <img src={d.photo} alt={d.title} style="width:100%;aspect-ratio:16/9;object-fit:cover;border-radius:var(--radius-xl);box-shadow:var(--shadow-md);margin-bottom:var(--space-4)" loading="lazy" decoding="async" />}
+        {d.photo && <img src={withBase(d.photo)} alt={d.title} style="width:100%;aspect-ratio:16/9;object-fit:cover;border-radius:var(--radius-xl);box-shadow:var(--shadow-md);margin-bottom:var(--space-4)" loading="lazy" decoding="async" />}
         <div class="g-meta-line" style="margin-bottom:var(--space-3)">
           {d.address && <span><i class="fa-solid fa-location-dot" aria-hidden="true"></i> {d.address}</span>}
-          {d.website && <span><i class="fa-solid fa-globe" aria-hidden="true"></i> <a href={d.website} rel="noopener" target="_blank">{STRINGS.website}</a></span>}
+          {d.website && <span><i class="fa-solid fa-globe" aria-hidden="true"></i> <a href={withBase(d.website)} rel="noopener" target="_blank">{STRINGS.website}</a></span>}
         </div>
         {(d.notes || d.accessibility) && (
           <div class="g-callout" style="flex-direction:column;gap:.6rem">

package/src/pages/venues/index.astro

@@ -3,6 +3,7 @@
  *  venue, sorted by name. Fixes the "All venues" backlink on venue detail pages,
  *  which previously had no list page to point to. */
 import { safeCollection } from '../../lib/collections';
+import { withBase } from '../../lib/url';
 import BaseLayout from '../../layouts/BaseLayout.astro';
 import PageHero from '../../components/PageHero.astro';
 import { SECTIONS } from 'popular:config';
@@ -19,10 +20,10 @@ const sec = SECTIONS.venues;
         {venues.map((v) => (
           <article class="g-card">
             {v.data.photo && (
-              <a href={`/venues/${v.id}/`} class="g-card__media"><img src={v.data.photo} alt={v.data.title} loading="lazy" decoding="async" /></a>
+              <a href={withBase(`/venues/${v.id}/`)} class="g-card__media"><img src={withBase(v.data.photo)} alt={v.data.title} loading="lazy" decoding="async" /></a>
             )}
             <div class="g-card__body">
-              <h3 class="g-card__title"><a href={`/venues/${v.id}/`}>{v.data.title}</a></h3>
+              <h3 class="g-card__title"><a href={withBase(`/venues/${v.id}/`)}>{v.data.title}</a></h3>
               {v.data.address && <div class="g-card__text"><i class="fa-solid fa-location-dot" aria-hidden="true"></i> {v.data.address}</div>}
             </div>
           </article>