blume 2.0.2 → 2.1.0

package/src/components/layout/Search.astro

@@ -1,9 +1,13 @@
 ---
+import data from "blume:data";
+
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
 import type { Navigation } from "../../core/types.ts";
+import { scopesVersions } from "../../search/adapters/version-scope.ts";
 import { resolvePopularIconMarkup } from "../../search/popular-icon.ts";
 import Icon from "../Icon.astro";
+import { withBase, withMountedBase } from "../islands/base-path.ts";
 import { flattenPages } from "./nav-utils.ts";
 
 // The provider-specific loader is generated per project into `blume:search-client`
@@ -21,7 +25,8 @@ interface Props {
   locale?: string;
   /**
    * Docs version to filter results to (`""` = the current docs — a meaningful
-   * value, so `null`/omitted is what disables version filtering).
+   * value, so `null`/omitted is what disables version filtering). Ignored when
+   * the configured provider can't scope by version.
    */
   version?: string | null;
 }
@@ -32,27 +37,41 @@ const {
   popularPages,
   strings,
   locale,
-  version = null,
+  version: viewedVersion = null,
 } = Astro.props;
+// Pagefind, Orama Cloud, and Mixedbread search every version whatever the
+// dialog asks, so on those an "All versions" toggle would change nothing:
+// treat the site as unversioned for search instead.
+const version = scopesVersions(data.config.search.provider)
+  ? viewedVersion
+  : null;
 // Merge over the English baseline per key (rather than `strings ?? …`) so a
 // partial — or empty `{}` — strings object still resolves every label to a
 // default, matching the pattern PageActions uses for its own dictionary.
 const s = { ...EN_UI.search, ...strings };
 
 // Resolve popular icons to markup here (icon set is server-only). Unknown
-// names fall through to the island's file glyph.
+// names fall through to the island's file glyph. Each entry's served href is
+// resolved here too: a configured entry is authored, so a base written by hand
+// is kept (`withBase`); the sidebar fallback links generated routes, which
+// always go under the base (`withMountedBase`).
 const popular =
   popularPages && popularPages.length > 0
     ? popularPages.map((page) => ({
+        href: withBase(page.route),
         icon: resolvePopularIconMarkup(
           page.icon,
           import.meta.env.BASE_URL ?? "/"
         ),
         label: page.label,
-        route: page.route,
       }))
     : navigation
-      ? flattenPages(navigation.sidebar).slice(0, 6)
+      ? flattenPages(navigation.sidebar)
+          .slice(0, 6)
+          .map((page) => ({
+            href: withMountedBase(page.route),
+            label: page.label,
+          }))
       : [];
 
 const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
@@ -74,23 +93,19 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
   data-version={version ?? undefined}
   data-versioned={version === null ? undefined : ""}
 >
-  {/* The label and shortcut hint wait until `lg`: below it the hamburger and
-      inline tab bar share the header row, and a full-width search field would
-      press into the language switcher. */}
+  {/* An icon button like the theme toggle beside it, named with its shortcut
+      by the header's tooltip. The chord reads left to right in every locale
+      ("⌘K", never "K⌘"), and the script swaps in Ctrl off Apple devices. */}
   <button
+    aria-keyshortcuts="Meta+K Control+K"
     aria-label={s.button}
-    class="inline-flex h-9 cursor-pointer items-center gap-2 rounded-full border border-border bg-background px-3 text-muted-foreground text-sm transition-colors hover:border-foreground hover:text-foreground lg:min-w-40"
+    class="inline-flex size-9 shrink-0 cursor-pointer items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
     data-blume-search-open
+    data-blume-tooltip={`${s.button} (\u2066⌘K\u2069)`}
+    data-label={s.button}
     type="button"
   >
-    <Icon name="search" size={16} />
-    <span class="flex-1 text-start max-lg:hidden">{s.button}</span>
-    {/* A key chord reads left to right in every locale ("⌘K", never "K⌘"). */}
-    <kbd
-      class="font-mono text-[0.7rem] max-lg:hidden"
-      data-blume-search-kbd
-      dir="ltr">⌘K</kbd
-    >
+    <Icon name="search" size={18} />
   </button>
 
   <dialog
@@ -220,9 +235,11 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
   <script>
     import { navigate } from "astro:transitions/client";
     import { chromeIcons as icons } from "../../theme/chrome-icons.ts";
-    import { prefixBase } from "../islands/base-path.ts";
+    import { mountBase } from "../islands/base-path.ts";
     import { escape as escapeHtml } from "html-escaper";
 
+    import { track } from "./analytics-client.ts";
+    import { createSearchTracker } from "./search/analytics.ts";
     import { highlight, matchSnippet } from "./search/types.ts";
     import type { SearchFn, SearchHit } from "./search/types.ts";
 
@@ -234,10 +251,11 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
     }
 
     interface PopularPage {
+      /** The served URL, base included (resolved server-side). */
+      href: string;
       /** Pre-resolved inline SVG from the server; absent falls back to `file`. */
       icon?: string;
       label: string;
-      route: string;
     }
 
     const GRID_COLS = "md:grid-cols-[22rem_minmax(0,1fr)]";
@@ -306,6 +324,8 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       message!: HTMLElement;
       preview!: HTMLElement;
       searchFn: SearchFn | null = null;
+      /** Records settled queries and picked results (search/analytics.ts). */
+      tracker = createSearchTracker(track);
       loaded = false;
       loadFailed = false;
       /** First-open client/index load still in flight. */
@@ -450,11 +470,13 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         }
 
         // The handlers accept both ⌘ and Ctrl chords; show the right modifier
-        // per platform on the button hint and the footer's preview hint.
+        // per platform in the button's tooltip and the footer's preview hint.
         const isApple = /mac|iphone|ipad|ipod/iu.test(navigator.platform);
-        const hint = this.querySelector("[data-blume-search-kbd]");
-        if (hint) {
-          hint.textContent = isApple ? "⌘K" : "Ctrl K";
+        const trigger = this.querySelector<HTMLElement>(
+          "[data-blume-search-open]"
+        );
+        if (trigger && !isApple) {
+          trigger.dataset.blumeTooltip = `${trigger.dataset.label ?? ""} (\u2066Ctrl K\u2069)`;
         }
         const previewHint = this.querySelector(
           "[data-blume-search-preview-kbd]"
@@ -474,7 +496,10 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         this.dialog.addEventListener("keydown", (event) =>
           this.onKeydown(event)
         );
-        this.dialog.addEventListener("close", () => this.unlockPageScroll());
+        this.dialog.addEventListener("close", () => {
+          this.unlockPageScroll();
+          this.tracker.closed();
+        });
         this.dialog.addEventListener("click", (event) => {
           if (event.target === this.dialog) {
             this.dialog.close();
@@ -658,6 +683,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
           this.setMessage(this.noResultsMsg);
         }
 
+        this.tracker.settled(query, result.hits.length);
         this.finishRender();
       }
 
@@ -671,7 +697,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         if (this.popular.length > 0) {
           const group = this.addGroup(this.popularMsg);
           for (const page of this.popular) {
-            const item = this.createLinkRow(page.route, page.label, page.icon);
+            const item = this.createLinkRow(page.href, page.label, page.icon);
             group.appendChild(item.el);
             this.selectables.push(item);
           }
@@ -755,9 +781,10 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
 
       createHitRow(hit: SearchHit, query: string): Selectable {
         const el = document.createElement("a");
-        // Index URLs are base-less logical routes; prefix the deployment base so
-        // clicking a result lands on the page's real served URL.
-        const href = prefixBase(import.meta.env.BASE_URL, hit.url);
+        // Index URLs are base-less logical routes; mount them under the
+        // deployment base so clicking a result lands on the page's real served
+        // URL, even when the route starts with the base's own name.
+        const href = mountBase(import.meta.env.BASE_URL, hit.url);
         el.href = href;
         el.className = `${ROW_CLASS} ${MARK}`;
         // `line-clamp-2` already sets `display`, so no `block` here (it would
@@ -782,9 +809,8 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         return item;
       }
 
-      createLinkRow(url: string, label: string, icon?: string): Selectable {
+      createLinkRow(href: string, label: string, icon?: string): Selectable {
         const el = document.createElement("a");
-        const href = prefixBase(import.meta.env.BASE_URL, url);
         el.href = href;
         el.className = ROW_CLASS;
         // `icon` is server-resolved markup (built-in Lucide, `<img>`, or
@@ -881,6 +907,14 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
             new CustomEvent("blume:open-assistant", { detail: { query } })
           );
         } else if (item.url) {
+          if (item.hit) {
+            const hits = this.selectables.filter((row) => row.hit);
+            this.tracker.selected(
+              this.input.value.trim(),
+              hits.indexOf(item) + 1,
+              item.url
+            );
+          }
           // Close first so the dialog isn't left open over the transition;
           // navigate() rides the client router (and falls back to a normal
           // full load on pages without it).

package/src/components/layout/SiteFooter.astro

@@ -0,0 +1,124 @@
+---
+// The site footer, below the content on every page: one row, as tall as the
+// header, with `footer.links` on one side and the social profile icons on the
+// other. The site's repository (`github`, unless `navigation.repo` hides it)
+// is the first icon; the footer is the only place it's linked. With `consent` configured the links end with the
+// Cookie settings link, which reopens the reader's consent choices. Renders
+// nothing when there's none of these; a `components.ts` `Footer` replaces it.
+import data from "blume:data";
+
+import type { BlumeDataConfig } from "../../core/data.ts";
+import type { Navigation } from "../../core/types.ts";
+import { EN_UI } from "../../core/i18n-ui.ts";
+import type { UIStrings } from "../../core/i18n-ui.ts";
+import { routeSetFor } from "../../core/locale-links.ts";
+import { newTabAttrs } from "../../core/new-tab.ts";
+import Icon from "../Icon.astro";
+import { withBase } from "../islands/base-path.ts";
+import { footerLinks } from "./footer-links.ts";
+import { footerSocialLinks } from "./footer-socials.ts";
+
+interface Props {
+  footer?: BlumeDataConfig["footer"];
+  /**
+   * Active locale of the page: labels written as per-locale maps show its
+   * entry, and internal links move into it (see `footer-links.ts`).
+   */
+  locale?: string;
+  /** The page's navigation: its `repoUrl` is the repository link. */
+  navigation?: Navigation;
+  /** Localized UI strings; the Cookie settings label comes from `consent`. */
+  ui?: UIStrings;
+}
+
+const { footer, locale, navigation, ui } = Astro.props;
+// `github`, as `navigation.repo` leaves it: hidden, or pointed elsewhere.
+const repoUrl = navigation?.repoUrl;
+const socials = footerSocialLinks(
+  footer?.socials ?? {},
+  repoUrl
+    ? { href: repoUrl, label: { ...EN_UI.nav, ...ui?.nav }.githubRepository }
+    : null
+);
+const links = footerLinks(footer?.links ?? [], {
+  basePath: data.config.basePath,
+  i18n: data.config.i18n,
+  locale,
+  routes: routeSetFor(data.routes),
+});
+const consentSettings = data.config.consent
+  ? { ...EN_UI.consent, ...ui?.consent }.settings
+  : null;
+const linkClass =
+  "text-muted-foreground transition-colors hover:text-foreground focus-visible:text-foreground";
+// Round icon buttons, like the header's.
+const iconButton =
+  "inline-flex size-9 shrink-0 cursor-pointer items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-muted hover:text-foreground focus-visible:text-foreground";
+const hasLinks = links.length > 0 || consentSettings !== null;
+---
+
+{
+  (hasLinks || socials.length > 0) && (
+    <footer class="border-border border-t px-4 md:px-6" data-blume-footer>
+      <div class="flex min-h-16 flex-wrap items-center justify-between gap-x-6 gap-y-3 py-3">
+        {hasLinks && (
+          <ul class="flex flex-wrap items-center gap-x-5 gap-y-2 text-sm">
+            {links.map((link) => (
+              <li>
+                <a
+                  class={linkClass}
+                  href={withBase(link.href)}
+                  {...newTabAttrs(link.href)}
+                >
+                  {link.label}
+                </a>
+              </li>
+            ))}
+            {consentSettings && (
+              <li>
+                <button
+                  class:list={[linkClass, "cursor-pointer"]}
+                  data-blume-consent-open
+                  type="button"
+                >
+                  {consentSettings}
+                </button>
+              </li>
+            )}
+          </ul>
+        )}
+        {/* Pulled out by the buttons' padding, so the glyphs line up with the
+            footer's edge, and pushed to the far side even with no links. */}
+        {socials.length > 0 && (
+          <ul class="-me-[9px] -my-[9px] ms-auto flex flex-wrap items-center gap-1">
+            {socials.map((social) => (
+              <li>
+                <a
+                  aria-label={social.label}
+                  class={iconButton}
+                  href={withBase(social.href)}
+                  title={social.label}
+                  {...newTabAttrs(social.href)}
+                >
+                  {social.path ? (
+                    <svg
+                      aria-hidden="true"
+                      fill="currentColor"
+                      height="18"
+                      viewBox="0 0 24 24"
+                      width="18"
+                    >
+                      <path d={social.path} />
+                    </svg>
+                  ) : (
+                    <Icon name={social.icon} size={18} />
+                  )}
+                </a>
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+    </footer>
+  )
+}

package/src/components/layout/SiteMetatags.astro

@@ -0,0 +1,16 @@
+---
+import { metatagAttributes } from "../../seo/metatags.ts";
+
+/**
+ * The site's own `seo.metatags` in a page's head, after the tags Blume
+ * writes (see seo/metatags.ts). Every layout renders it, so a verification
+ * token or `theme-color` reaches every page.
+ */
+interface Props {
+  tags: Record<string, string> | null | undefined;
+}
+
+const { tags } = Astro.props;
+---
+
+{metatagAttributes(tags).map((attributes) => <meta {...attributes} />)}

package/src/components/layout/VersionBanner.astro

@@ -1,5 +1,5 @@
 ---
-import { withBase } from "../islands/base-path.ts";
+import { withMountedBase } from "../islands/base-path.ts";
 import Icon from "../Icon.astro";
 
 // The "you're viewing an old version" notice, shared by RootLayout and
@@ -29,7 +29,7 @@ const { notice } = Astro.props;
       <span>{notice.message}</span>
       <a
         class="inline-flex items-center gap-1 font-medium underline underline-offset-2"
-        href={withBase(notice.latestHref)}
+        href={withMountedBase(notice.latestHref)}
       >
         {notice.latestLabel}
         <Icon name="arrow-right" size={14} />

package/src/components/layout/analytics-client.ts

@@ -40,6 +40,9 @@ interface AnalyticsWindow {
   pirsch?: (event: string, options?: { meta?: TrackProps }) => void;
   plausible?: (event: string, options?: { props?: TrackProps }) => void;
   posthog?: { capture?: (event: string, props?: TrackProps) => void };
+  stonks?: {
+    event?: (event: string, props?: Record<string, string>) => void;
+  };
 }
 
 /** Run one provider call; its failure must not reach the others or the caller. */
@@ -85,6 +88,15 @@ const trackGlobals = (
   attempt(() => w.plausible?.(event, { props }));
   attempt(() => w.databuddy?.track?.(event, props));
   attempt(() => w.fathom?.trackEvent?.(event));
+  // OneDollarStats only takes string property values.
+  attempt(() =>
+    w.stonks?.event?.(
+      event,
+      Object.fromEntries(
+        Object.entries(props).map(([key, value]) => [key, String(value)])
+      )
+    )
+  );
   // Pirsch stringifies `meta` values in place, so it gets its own copy and
   // the `blume:track` listeners still see the original types.
   attempt(() => w.pirsch?.(event, { meta: { ...props } }));

package/src/components/layout/consent/native.ts

@@ -0,0 +1,79 @@
+/**
+ * `native()`'s browser module: Blume's own banner. The generated
+ * `blume:consent-client` brings it in when `native()` is the configured
+ * consent adapter (see `consent/clients.ts`). It reports the reader's stored
+ * answer, shows the banner (`ConsentBanner.astro`) until they pick one, stores
+ * the pick, and makes the footer's Cookie settings link bring the banner back.
+ */
+import type { NativeOptions } from "../../../consent/native.ts";
+import type { BlumeConsent, ConsentClientStart } from "./types.ts";
+
+/** Where `native()` keeps the reader's answer. */
+export const CONSENT_STORAGE_KEY = "blume-consent";
+
+const BANNER = "[data-blume-consent-banner]";
+const CHOICE = "[data-blume-consent-choice]";
+
+/** The stored answer, or `null` before one (or without storage). */
+export const storedChoice = (): boolean | null => {
+  try {
+    const value = localStorage.getItem(CONSENT_STORAGE_KEY);
+    if (value === "granted" || value === "denied") {
+      return value === "granted";
+    }
+  } catch {
+    // Storage blocked: ask again on every page rather than fail.
+  }
+  return null;
+};
+
+const storeChoice = (granted: boolean): void => {
+  try {
+    localStorage.setItem(CONSENT_STORAGE_KEY, granted ? "granted" : "denied");
+  } catch {
+    // Storage blocked: the answer holds for this page load only.
+  }
+};
+
+const banner = (): HTMLElement | null =>
+  document.querySelector<HTMLElement>(BANNER);
+
+/**
+ * Wire this page's banner: show it while the reader hasn't answered, and
+ * store and report an answer. Runs again after every client-router swap,
+ * which brings a fresh, hidden banner.
+ */
+const syncBanner = (consent: BlumeConsent): void => {
+  const element = banner();
+  if (!element) {
+    return;
+  }
+  element.hidden = storedChoice() !== null;
+  for (const button of element.querySelectorAll<HTMLElement>(CHOICE)) {
+    button.addEventListener("click", () => {
+      const granted = button.dataset.blumeConsentChoice === "accept";
+      storeChoice(granted);
+      element.hidden = true;
+      consent.set({ analytics: granted });
+    });
+  }
+};
+
+/**
+ * Report the stored answer, and wire the banner on this page and every page
+ * the client router swaps in. The options (the banner's privacy link) are
+ * rendered into the banner itself, so there's nothing to read here.
+ */
+export const start: ConsentClientStart<NativeOptions> = (consent) => {
+  consent.open = () => {
+    const element = banner();
+    if (element) {
+      element.hidden = false;
+    }
+  };
+  syncBanner(consent);
+  consent.set({ analytics: storedChoice() === true });
+  document.addEventListener("astro:after-swap", () => {
+    syncBanner(consent);
+  });
+};

package/src/components/layout/consent/types.ts

@@ -0,0 +1,37 @@
+/**
+ * The consent contract every adapter talks to, shared by the consent runtime
+ * (`consent/client.ts`) and each adapter's browser module (like `native.ts`
+ * here). `window.blumeConsent` is created by the inline init script
+ * (`consent/init.ts`) before any adapter loads.
+ */
+
+/** What a consent adapter reports: whether the reader allows analytics. */
+export interface ConsentState {
+  analytics: boolean;
+}
+
+/** `window.blumeConsent`, created by the inline init script. */
+export interface BlumeConsent {
+  /** `null` until an adapter reports, then the reader's choice. */
+  analytics: boolean | null;
+  /** The configured adapter's kind. */
+  kind: string;
+  /** Reopen the reader's consent choices; set by the adapter. */
+  open?: () => void;
+  /** Report the reader's choice; fires `blume:consent` when it changes. */
+  set: (state: ConsentState) => void;
+}
+
+/**
+ * A consent adapter's browser module entry point, which the generated
+ * `blume:consent-client` calls once per real page load, after the runtime is
+ * listening. It gets the consent state and the adapter's options from
+ * `blume.config.ts`, and must report the reader's answer with
+ * `consent.set({ analytics })` (on load, and again whenever it changes) and
+ * set `consent.open` to reopen the adapter's preferences. Anything it does per
+ * page, it redoes on `astro:after-swap`.
+ */
+export type ConsentClientStart<Options> = (
+  consent: BlumeConsent,
+  options: Options
+) => void;

package/src/components/layout/footer-links.ts

@@ -0,0 +1,53 @@
+import type { LocaleRouting } from "../../core/i18n.ts";
+import { localizeHref } from "../../core/locale-links.ts";
+import type { RouteSet } from "../../core/locale-links.ts";
+import { resolveLocalizable } from "../../core/localizable.ts";
+import type { ResolvedConfig } from "../../core/schema.ts";
+
+/** The configured `footer.links`. */
+type FooterLinks = NonNullable<ResolvedConfig["footer"]>["links"];
+
+/** A footer link, ready to render. */
+export interface FooterLinkItem {
+  href: string;
+  label: string;
+}
+
+/** What resolving needs from the site and the page. */
+export interface FooterContext {
+  basePath: string;
+  /** The site's locales, when it has more than one. */
+  i18n: LocaleRouting | null;
+  /** The locale of the page being rendered. */
+  locale?: string;
+  routes: RouteSet;
+}
+
+/**
+ * The footer's links in the page's locale: a label written as a per-locale
+ * map shows that locale's entry (see `core/localizable.ts`), and an internal
+ * link moves into the locale when it serves that page, the way content and
+ * header links do, so a reader on `/fr/…` stays in French.
+ */
+export const footerLinks = (
+  links: FooterLinks,
+  context: FooterContext
+): FooterLinkItem[] => {
+  const { i18n, locale } = context;
+  const defaultLocale = i18n?.defaultLocale;
+  const localize = (href: string): string =>
+    i18n && locale
+      ? localizeHref(href, {
+          basePath: context.basePath,
+          // The layout mounts the deployment base afterwards.
+          deployBase: "",
+          i18n,
+          locale,
+          routes: context.routes,
+        })
+      : href;
+  return links.map((link) => ({
+    href: localize(link.href),
+    label: resolveLocalizable(link.label, locale, defaultLocale),
+  }));
+};

package/src/components/layout/footer-socials.ts

@@ -0,0 +1,87 @@
+import {
+  siBluesky,
+  siDiscord,
+  siFacebook,
+  siGithub,
+  siInstagram,
+  siMedium,
+  siReddit,
+  siTelegram,
+  siThreads,
+  siX,
+  siYcombinator,
+  siYoutube,
+} from "simple-icons";
+
+import type { FooterSocial } from "../../core/footer.ts";
+
+/**
+ * How a `footer.socials` platform is shown: its name, for the link's label,
+ * and either a filled brand mark or a Lucide icon.
+ */
+export interface SocialIcon {
+  label: string;
+  /** A Lucide icon name, where simple-icons carries no mark for the brand. */
+  icon?: string;
+  /** A simple-icons path on a 24×24 viewBox, drawn filled. */
+  path?: string;
+}
+
+/**
+ * Each platform's icon. Brand marks come from simple-icons; LinkedIn and
+ * Slack had theirs removed there at the brands' request, so they take
+ * Lucide's glyphs, as do the generic website and podcast links.
+ */
+export const SOCIAL_ICONS: Record<FooterSocial, SocialIcon> = {
+  bluesky: { label: "Bluesky", path: siBluesky.path },
+  discord: { label: "Discord", path: siDiscord.path },
+  facebook: { label: "Facebook", path: siFacebook.path },
+  github: { label: "GitHub", path: siGithub.path },
+  "hacker-news": { label: "Hacker News", path: siYcombinator.path },
+  instagram: { label: "Instagram", path: siInstagram.path },
+  linkedin: { icon: "linkedin", label: "LinkedIn" },
+  medium: { label: "Medium", path: siMedium.path },
+  podcast: { icon: "podcast", label: "Podcast" },
+  reddit: { label: "Reddit", path: siReddit.path },
+  slack: { icon: "slack", label: "Slack" },
+  telegram: { label: "Telegram", path: siTelegram.path },
+  threads: { label: "Threads", path: siThreads.path },
+  website: { icon: "globe", label: "Website" },
+  x: { label: "X", path: siX.path },
+  youtube: { label: "YouTube", path: siYoutube.path },
+};
+
+/** A configured social link, with the icon it's shown by. */
+export interface FooterSocialLink extends SocialIcon {
+  href: string;
+}
+
+const isFooterSocial = (key: string): key is FooterSocial =>
+  Object.hasOwn(SOCIAL_ICONS, key);
+
+/** The site's repository, as the footer links it. */
+export interface FooterRepoLink {
+  href: string;
+  /** Its accessible name, in the page's language ("GitHub repository"). */
+  label: string;
+}
+
+/**
+ * The footer's social links, in the order written, each with its icon. The
+ * footer is the only place the site links its repository, so `repo` (from
+ * `github` in the config) leads as the GitHub link, unless `socials.github`
+ * names one itself.
+ */
+export const footerSocialLinks = (
+  socials: Partial<Record<FooterSocial, string>>,
+  repo?: FooterRepoLink | null
+): FooterSocialLink[] => {
+  const links = Object.entries(socials).flatMap(([platform, href]) =>
+    isFooterSocial(platform) && href
+      ? [{ ...SOCIAL_ICONS[platform], href }]
+      : []
+  );
+  return repo && !socials.github
+    ? [{ ...SOCIAL_ICONS.github, ...repo }, ...links]
+    : links;
+};