astro-theme-popular 0.12.0 → 0.14.0

package/index.mjs

@@ -19,6 +19,7 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import sitemap from '@astrojs/sitemap';
+import Slugger from 'github-slugger';
 
 /* Markdown body hooks: loading="lazy" decoding="async" on images (CWV parity
    with Hugo's render-image.html), and site-absolute links/images prefixed with
@@ -26,7 +27,8 @@ import sitemap from '@astrojs/sitemap';
    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.
+   so the components prefix those themselves. And a hover "#" anchor on every
+   h2-h6, so each section has a copyable URL (Hugo's render-heading.html).
 
    Registered on the active markdown processor rather than through
    `markdown.rehypePlugins`: Astro 7's default processor is Sätteri, which does
@@ -47,6 +49,59 @@ const prefixPath = (value, prefix) =>
     ? prefix + value
     : value;
 
+/* Section permalinks: every h2-h6 ends in a "#" anchor linking to its own id
+   (parity with Hugo's render-heading.html; styled by .g-anchor in base.css).
+   Astro assigns heading ids in its own hast plugin, which runs *after* ours,
+   so the heading is slugged here with the same library and the same text
+   Astro would use, and the id set from here: Astro keeps an id that is
+   already present and reports it in `headings`, which keeps the docs sidebar
+   pointing at the same fragments. h1 is slugged too, so the duplicate counter
+   matches Astro's ("intro", "intro-1"), but gets no anchor: the page title
+   lives in the hero. The anchor is kept out of the accessibility tree and the
+   tab order on purpose: a labelled link inside a heading becomes part of the
+   heading's accessible name, and the docs sidebar already lists the same
+   fragments as real links. It is empty (the glyph comes from CSS) so feeds
+   and plain-text excerpts of the body never pick up a stray "#". */
+const HEADINGS = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'];
+
+const anchorNode = (id) => ({
+  type: 'element',
+  tagName: 'a',
+  /* Attribute spellings, not hast's camelCase: MDX output keeps property
+     names as written (`tabIndex` would reach the HTML as-is). */
+  properties: { className: ['g-anchor'], href: `#${id}`, 'aria-hidden': 'true', tabindex: '-1' },
+  children: [], // the "#" is CSS generated content; see base.css
+});
+
+/* Heading text the way Astro's own heading-id plugins read it: text nodes,
+   plus MDX `{frontmatter.x}` expressions resolved against the frontmatter
+   (mirrors collectHastText in @astrojs/markdown-satteri, which is not a
+   dependency the package can rely on). Without this a heading written as
+   `## {frontmatter.title}` would slug to "frontmattertitle". */
+const resolveFrontmatter = (expr, frontmatter) => {
+  if (!expr.startsWith('frontmatter.') && !expr.startsWith('frontmatter[')) return undefined;
+  const parts = [];
+  const re = /\.(\w+)|\[(\d+)\]|\["([^"]+)"\]|\['([^']+)'\]/g;
+  let m;
+  while ((m = re.exec(expr.slice('frontmatter'.length))) !== null) parts.push(m[1] ?? m[2] ?? m[3] ?? m[4]);
+  let value = frontmatter;
+  for (const key of parts) {
+    if (value == null || typeof value !== 'object') return undefined;
+    value = value[key];
+  }
+  return parts.length && typeof value === 'string' ? value : undefined;
+};
+const headingText = (node, frontmatter) => {
+  let text = '';
+  if (node.type === 'mdxTextExpression' || node.type === 'mdxFlowExpression') {
+    if (node.value != null) text += resolveFrontmatter(node.value.trim(), frontmatter ?? {}) ?? node.value;
+  } else if (node.type === 'text' && node.value != null) {
+    text += node.value;
+  }
+  for (const child of node.children || []) text += headingText(child, frontmatter);
+  return text;
+};
+
 /* Sätteri shape: filtered visitors, mutations through ctx.setProperty. */
 function satteriMarkdownHooks(prefix) {
   return {
@@ -70,27 +125,54 @@ function satteriMarkdownHooks(prefix) {
           if (href !== props.href) ctx.setProperty(node, 'href', href);
         },
       },
+      {
+        filter: HEADINGS,
+        visit(node, ctx) {
+          let id = node.properties?.id;
+          if (typeof id !== 'string') {
+            /* ctx.data is per document, so the duplicate counter resets per page. */
+            const slugger = (ctx.data.popularSlugger ??= new Slugger());
+            const raw = ctx.textContent(node);
+            id = slugger.slug(raw.includes('frontmatter') ? headingText(node, ctx.data.astro?.frontmatter) : raw);
+            ctx.setProperty(node, 'id', id);
+          }
+          /* No anchor on h1 (the page title lives in the hero) or on a heading
+             with no text to slug: href="#" would scroll to the top. Hugo's
+             hook guards both the same way. */
+          if (node.tagName !== 'h1' && id) ctx.appendChild(node, anchorNode(id));
+        },
+      },
     ],
   };
 }
 
 /* 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. */
+   coerces into one). A plain recursive walk, no unist-util-visit. */
 function rehypeMarkdownHooks(prefix) {
-  const walk = (node) => {
-    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);
+  return () => (tree, file) => {
+    /* One slugger per document, like Astro's own rehypeHeadingIds (which runs
+       after user plugins and keeps an id that is already set). */
+    const slugger = new Slugger();
+    const frontmatter = file?.data?.astro?.frontmatter;
+    const walk = (node) => {
+      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);
+        if (HEADINGS.includes(node.tagName)) {
+          if (typeof props.id !== 'string') props.id = slugger.slug(headingText(node, frontmatter));
+          if (node.tagName !== 'h1' && props.id) (node.children ??= []).push(anchorNode(props.id));
+        }
       }
-      if (node.tagName === 'a') props.href = prefixPath(props.href, prefix);
-    }
-    (node.children || []).forEach(walk);
+      (node.children || []).forEach(walk);
+    };
+    walk(tree);
   };
-  return () => (tree) => walk(tree);
 }
 
 function registerMarkdownHooks(config, logger) {

package/package.json

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

package/src/components/CalendarSubscribe.astro

@@ -0,0 +1,24 @@
+---
+/** Calendar subscribe buttons for the events feed: a webcal link that opens
+ *  the user's calendar app subscribed to the live feed (Apple Calendar,
+ *  Outlook, Thunderbird), a Google Calendar deep link (Google registers no
+ *  webcal handler on the web or Android), and the plain .ics download as the
+ *  universal fallback for "add calendar from URL" flows. webcal needs an
+ *  absolute URL, so the feed path goes through absoluteUrl. Mirrors Hugo's
+ *  partials/calendar-subscribe.html; callers supply the wrapping .g-row. */
+import { STRINGS } from 'popular:config';
+import { withBase, absoluteUrl } from '../lib/url';
+
+interface Props {
+  small?: boolean;
+}
+const { small = false } = Astro.props;
+
+const feedPath = '/events/calendar.ics';
+const webcal = absoluteUrl(feedPath, Astro.site ?? Astro.url).replace(/^https?:/, 'webcal:');
+const google = `https://calendar.google.com/calendar/render?cid=${encodeURIComponent(webcal)}`;
+const size = small ? ' g-btn--sm' : '';
+---
+<a class={`g-btn g-btn--outline${size}`} href={webcal}><i class="fa-solid fa-calendar-plus" aria-hidden="true"></i> {STRINGS.subscribeCalendar}</a>
+<a class={`g-btn g-btn--outline${size}`} href={google} rel="noopener" target="_blank"><i class="fa-brands fa-google" aria-hidden="true"></i> {STRINGS.subscribeGoogle}</a>
+<a class={`g-btn g-btn--ghost${size}`} href={withBase(feedPath)} download><i class="fa-solid fa-download" aria-hidden="true"></i> {STRINGS.downloadCalendar}</a>

package/src/components/EventsEmpty.astro

@@ -1,26 +1,24 @@
 ---
 /** 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. */
+ *  (if SITE.community.chat is set, §4) and the calendar-subscribe buttons.
+ *  The calendar feed mirrors Hugo's OutputFormats "Calendar" endpoint. */
 import { SITE, STRINGS } from 'popular:config';
 import { withBase } from '../lib/url';
+import CalendarSubscribe from './CalendarSubscribe.astro';
 
 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={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={withBase(calendar)}><i class="fa-solid fa-calendar-plus" aria-hidden="true"></i> {STRINGS.subscribeCalendar}</a>
-    </div>
-  )}
+  <div class="g-row" style="justify-content:center">
+    {chat?.url && (
+      <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>
+    )}
+    <CalendarSubscribe />
+  </div>
 </div>

package/src/lib/ical.ts

@@ -11,7 +11,7 @@ function ymd(d: Date): string {
 }
 
 export function icsEscape(s: string): string {
-  return s.replace(/\\/g, '\\\\').replace(/;/g, '\;').replace(/,/g, '\\,').replace(/\n/g, '\\n');
+  return s.replace(/\\/g, '\\\\').replace(/;/g, '\\;').replace(/,/g, '\\,').replace(/\n/g, '\\n');
 }
 
 /** One content line, CRLF-terminated, folded at 75 octets (continuations
@@ -61,6 +61,10 @@ export function buildIcs(
   L.push(fold('CALSCALE:GREGORIAN'));
   L.push(fold('METHOD:PUBLISH'));
   L.push(fold(`X-WR-CALNAME:${opts.siteTitle} events`));
+  /* Subscription refresh hints (RFC 7986 + the Apple/Outlook legacy twin).
+     Google Calendar ignores both and polls on its own schedule. */
+  L.push(fold('REFRESH-INTERVAL;VALUE=DURATION:PT12H'));
+  L.push(fold('X-PUBLISHED-TTL:PT12H'));
   for (const e of events) {
     L.push(fold('BEGIN:VEVENT'));
     L.push(fold(`UID:${e.permalink}`));

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

@@ -4,7 +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 CalendarSubscribe from '../../components/CalendarSubscribe.astro';
 import EventsEmpty from '../../components/EventsEmpty.astro';
 import { SECTIONS, STRINGS, PAGINATION } from 'popular:config';
 
@@ -54,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={withBase('/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)"><CalendarSubscribe small /></div>
       </div>
       <div class="g-stack" style="margin-top:var(--space-4);gap:var(--space-3)">
         {groupByYear(upcoming).map((group) => (

package/src/styles/base.css

@@ -97,6 +97,17 @@ pre code { font-size: inherit; background: none; padding: 0; border-radius: 0; }
 .g-prose > * + * { margin-top: 1.1rem; }
 .g-prose ul, .g-prose ol { padding-left: 1.2rem; display: flex; flex-direction: column; gap: 0.5rem; }
 .g-prose h2 { margin-top: 1.8rem; }
+/* Section permalinks: every markdown h2-h6 ends in a "#" anchor (Hugo:
+   _markup/render-heading.html; Astro: the markdown hook) so a section has a
+   URL a reader can copy. Shown while the heading is hovered; where there is
+   no hover (touch) it stays faintly visible so it can still be tapped. The
+   glyph is generated content: the anchor itself is empty so summaries, feeds
+   and plain-text excerpts of the body never pick up a stray "#". */
+.g-anchor::before { content: "#"; }
+.g-anchor { margin-left: 0.35em; font-weight: var(--weight-regular); color: var(--text-muted); text-decoration: none; opacity: 0; transition: opacity 0.15s; }
+:is(h2, h3, h4, h5, h6):hover > .g-anchor { opacity: 1; }
+.g-anchor:hover { color: var(--color-primary); }
+@media (hover: none) { .g-anchor { opacity: 0.5; } }
 .g-prose img { border-radius: var(--radius-xl); box-shadow: var(--shadow-sm); }
 /* One background for every fenced block, whatever the highlighter did.
    !important beats the inline background-color that Chroma (Hugo) and

package/src/styles/components.css

@@ -258,7 +258,9 @@ pre:hover .g-copy, .g-copy:focus-visible { opacity: 1; }
 .g-doc-toc a.is-active { color: var(--gold-700); background: var(--gold-50); border-left-color: var(--color-primary); font-weight: var(--weight-semibold); }
 .g-doc__content { min-width: 0; }
 .g-doc__content h2 { margin-top: 2.5rem; }
-.g-doc__content h2, .g-doc__content h3, .g-doc__content h4 { scroll-margin-top: 108px; }
+/* A fragment target stops clear of the sticky header. Every prose heading,
+   not only docs: blog posts and event pages carry section anchors too. */
+.g-prose :is(h2, h3, h4, h5, h6) { scroll-margin-top: 108px; }
 .g-doc__content h2:first-child { margin-top: 0; }
 
 /* ---------- Callout ---------- */