DEV Community: Roger Rajaratnam

Adding a mailing list to a static Astro blog with Resend

Roger Rajaratnam — Thu, 21 May 2026 09:48:48 +0000

Original post: Adding a mailing list to a static Astro blog with Resend

Series: Part of How this blog was built — documenting every decision that shaped this site.

Adding a mailing list to a static site is one of those features that looks like
it needs a whole backend — a database of subscribers, a queue, an unsubscribe
flow. In practice, if you're already on Netlify and already using
Resend for transactional email, you can bolt on a working
subscription form in an afternoon.

Here's exactly how I did it on this site.

What we're building

A MailingListCTA Astro component that:

Renders an email input and a subscribe button
Submits via fetch to a Netlify Function
Shows inline success or error feedback without a page reload
Includes a honeypot field to block bot submissions

The Netlify Function:

Validates the email server-side
Silently discards bot submissions (honeypot check)
Calls the Resend Segments API to add the contact

Diagram fallback for Dev.to. View the canonical article for the full version: https://sourcier.uk/blog/mailing-list-astro

Setting up Resend Segments

Resend recently migrated from Audiences to
Segments — Audiences
still work but are deprecated and will be removed. The concept is the same: a
named list of contacts you can send broadcasts to.

Create a segment in the Resend dashboard. Once created, copy the segment ID —
you'll need it as an environment variable.

The Netlify Function

Create netlify/functions/subscribe.ts. The function receives a POST with
{ email, website } in the body. The website field is the honeypot.

import type { HandlerEvent } from "@netlify/functions";

const ALLOWED_ORIGIN = process.env.SITE_URL?.replace(/\/$/, "") ?? "";

function isValidEmail(email: string): boolean {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
}

export const handler = async (event: HandlerEvent) => {
  const corsHeaders = {
    "Access-Control-Allow-Origin": ALLOWED_ORIGIN,
    "Access-Control-Allow-Methods": "POST, OPTIONS",
    "Access-Control-Allow-Headers": "Content-Type",
  };

  if (event.httpMethod === "OPTIONS") {
    return { statusCode: 204, headers: corsHeaders, body: "" };
  }

  if (event.httpMethod !== "POST") {
    return { statusCode: 405, headers: corsHeaders, body: JSON.stringify({ error: "Method not allowed" }) };
  }

  const apiKey = process.env.RESEND_API_KEY;
  const segmentId = process.env.RESEND_SEGMENT_ID;

  if (!apiKey || !segmentId) {
    console.error("subscribe: RESEND_API_KEY or RESEND_SEGMENT_ID is not set");
    return { statusCode: 500, headers: corsHeaders, body: JSON.stringify({ error: "Server configuration error" }) };
  }

  let body: { email?: unknown; website?: unknown };
  try {
    body = JSON.parse(event.body ?? "{}");
  } catch {
    return { statusCode: 400, headers: corsHeaders, body: JSON.stringify({ error: "Invalid request body" }) };
  }

  const email = (typeof body.email === "string" ? body.email : "")
    .trim()
    .toLowerCase();
  const honeypot = body.website ?? "";

  if (honeypot) {
    return { statusCode: 200, headers: corsHeaders, body: JSON.stringify({ success: true }) };
  }

  if (!email || !isValidEmail(email)) {
    return { statusCode: 400, headers: corsHeaders, body: JSON.stringify({ error: "A valid email address is required" }) };
  }

  const res = await fetch(`https://api.resend.com/contacts`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ email, unsubscribed: false, segments: [{ id: segmentId }] }),
  });

  if (!res.ok) {
    const errorBody = await res.text();
    console.error(`subscribe: Resend API error ${res.status}: ${errorBody}`);
    return { statusCode: 502, headers: corsHeaders, body: JSON.stringify({ error: "Could not subscribe. Please try again later." }) };
  }

  return {
    statusCode: 200,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
    body: JSON.stringify({ success: true }),
  };
};

A few things worth noting:

No Resend SDK — calling the REST API directly with fetch keeps the function dependency-free and fast to cold-start.
CORS headers — the function sets Access-Control-Allow-Origin to SITE_URL from environment, with an OPTIONS preflight handler.
Honeypot is silently accepted — returning 200 when the honeypot is filled means bots get no signal that they were caught. Returning 400 would tell them to try again without the field.

Welcome email

After the contact is successfully added, the function sends a welcome email
using POST /emails. The send is done with .catch() so a failure doesn't
break the subscription response.

Rather than embedding HTML directly in the function, the welcome email is stored
as a Resend template.
This means you can edit the email copy in the Resend dashboard without touching
or redeploying the function.

When RESEND_WELCOME_TEMPLATE_ID is set, the function sends via the template.
Otherwise it falls back to inline HTML, so the function keeps working before
you've set up the template.

const emailPayload = welcomeTemplateId
  ? {
      from: `Sourcier <${fromEmail}>`,
      to: [email],
      template: {
        id: welcomeTemplateId,
        variables: { BLOG_URL: `${siteUrl}/blog` },
      },
    }
  : {
      from: `Sourcier <${fromEmail}>`,
      to: [email],
      subject: "You're subscribed to Sourcier",
      html: `<div style="font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;max-width:560px;margin:0 auto;padding:2rem 1.5rem;color:#0f0f0f">
  <p style="font-size:1.5rem;font-weight:800;text-transform:uppercase;letter-spacing:0.02em;margin:0 0 1rem">Welcome to Sourcier</p>
  <p style="margin:0 0 1rem;line-height:1.6">Thanks for signing up. You'll get an email whenever I publish something new — engineering deep-dives, lessons from the field, and the occasional opinion.</p>
  <p style="margin:0 0 1.5rem;line-height:1.6">In the meantime, browse the <a href="${siteUrl}/blog" style="color:#e8006a">blog</a> to see what's already there.</p>
  <p style="margin:0;color:#6b6b6b;font-size:0.875rem">You can unsubscribe at any time by replying to this email.</p>
</div>`,
    };

await fetch("https://api.resend.com/emails", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(emailPayload),
}).catch((err) => console.error("subscribe: welcome email failed:", err));

Note that template and html are mutually exclusive — Resend returns a
validation error if you include both. The template must also be published in
the Resend dashboard before it can be used; draft templates won't send.

The fromEmail guard means the function still works in local dev without
NOTIFY_FROM_EMAIL set — it simply skips the welcome email.

Creating the template with a script

Rather than manually creating the template in the Resend dashboard, the repo
includes a setup script at scripts/create-welcome-template.js. Run it once
after cloning:

RESEND_API_KEY=re_xxx node scripts/create-welcome-template.js

The script:

Checks whether a template with the alias sourcier-welcome already exists
If it does — updates it with PATCH /templates/:id and re-publishes
If it doesn't — creates it with POST /templates and publishes
Prints the template ID to copy into your Netlify env vars

The alias acts as a stable lookup key, so running the script again on future
edits updates the template in-place rather than creating duplicates. After
publishing via the script, email sends using the template will immediately use
the updated version.

The Astro component

Diagram fallback for Dev.to. View the canonical article for the original SVG: https://sourcier.uk/blog/mailing-list-astro

Click the expand icon to view it fullscreen.

The MailingListCTA component is a dark card that sits at content width on any
page. The submit logic lives in a shared subscribeForm.ts utility so both the
full-width card and the sidebar component use the same behaviour without
duplicating code.

Honeypot field

The honeypot is a text input that is visually hidden using CSS — positioned
off-screen, not just display: none, because some bots skip fields hidden that
way.

<p class="mailing-cta__honeypot" aria-hidden="true">
  <label for="mailing-cta-website">Leave this blank</label>
  <input id="mailing-cta-website" name="website" type="text" tabindex="-1" autocomplete="off" />
</p>

.mailing-cta__honeypot {
  position: absolute;
  left: -9999px;
  width: 1px;
  height: 1px;
  overflow: hidden;
  opacity: 0;
  pointer-events: none;
}

tabindex="-1" ensures keyboard users and screen readers can't reach it.
aria-hidden="true" on the wrapper removes it from the accessibility tree
entirely.

Shared form utility

The submit handler lives in src/utils/subscribeForm.ts. Both MailingListCTA
and MailingListCTASidebar call bindSubscribeForm() with a config object that
maps DOM IDs to CSS class names and copy:

interface SubscribeFormConfig {
  formId: string;
  emailId: string;
  feedbackClass: string;
  feedbackSuccessClass: string;
  feedbackErrorClass: string;
  successLabel: string;
  defaultButtonLabel: string;
  source?: string;
}

export function bindSubscribeForm(config: SubscribeFormConfig): void {
  const form = document.getElementById(config.formId) as HTMLFormElement | null;
  const feedback = form?.querySelector<HTMLElement>("[aria-live]") ?? null;
  const input = document.getElementById(config.emailId) as HTMLInputElement | null;

  if (!form || !feedback || !input) return;

  form.addEventListener("submit", async (e) => {
    e.preventDefault();

    const email = input.value.trim();
    if (!email) return;

    const btn = form.querySelector<HTMLButtonElement>("button[type=submit]");
    if (!btn) return;

    btn.disabled = true;
    btn.textContent = "Subscribing…";
    feedback.hidden = true;
    feedback.className = config.feedbackClass;

    try {
      const res = await fetch("/.netlify/functions/subscribe", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          email,
          website: (form.elements.namedItem("website") as HTMLInputElement | null)?.value ?? "",
          ...(config.source ? { source: config.source } : {}),
        }),
      });

      const data = await res.json();

      if (res.ok) {
        feedback.textContent = config.successLabel;
        feedback.classList.add(config.feedbackSuccessClass);
        form.reset();
        btn.textContent = "You're in";
        btn.disabled = true;
      } else {
        feedback.textContent = (data as { error?: string }).error ?? "Something went wrong. Please try again.";
        feedback.classList.add(config.feedbackErrorClass);
        btn.disabled = false;
        btn.textContent = config.defaultButtonLabel;
      }
    } catch {
      feedback.textContent = "Something went wrong. Please try again.";
      feedback.classList.add(config.feedbackErrorClass);
      btn.disabled = false;
      btn.textContent = config.defaultButtonLabel;
    } finally {
      feedback.hidden = false;
    }
  });
}

A few things worth noting:

feedback.className is reset on each submission so a previous success or error class doesn't carry over if the user submits again.
btn.textContent = "You're in" on success locks the button with a confirmation label so the user knows the action was recorded.
source is an optional field passed through to the function body, giving a hook for tracking which page the subscriber came from.
The feedback element has aria-live="polite" so screen readers announce the outcome. It starts hidden so it takes up no space until there's something to show.

Environment variables

Add these in the Netlify dashboard under Site configuration → Environment
variables:

Variable	Value
`RESEND_API_KEY`	Your Resend API key
`RESEND_SEGMENT_ID`	The segment ID from the Resend dashboard
`NOTIFY_FROM_EMAIL`	Verified sender address, e.g. `hello@sourcier.uk`
`SITE_URL`	Your public site URL, e.g. `https://sourcier.uk`
`RESEND_WELCOME_TEMPLATE_ID`	Template ID printed by `scripts/create-welcome-template.js`
`RESEND_TOPIC_ID`	Optional — scopes broadcasts to a specific topic

RESEND_API_KEY is likely already set if you're using Resend for other
notifications on the same site. RESEND_WELCOME_TEMPLATE_ID and RESEND_TOPIC_ID
are optional — the function falls back to inline HTML if the template ID is absent.

Adding the component to pages

Import and drop the component wherever you want the CTA to appear:

---
import MailingListCTA from "../components/MailingListCTA.astro";
---

<!-- rest of page -->
<MailingListCTA />

I added it to blog posts, guide pages, tag pages, and the standalone pages —
home, blog index, about, and contact.

Sidebar variant

Blog post pages have a sticky sidebar that shows the table of contents. A
full-width card below the article felt like too much repetition, so I also built
a compact MailingListCTASidebar component that sits below the ToC and shares
the same Netlify Function.

The sidebar variant is a self-contained dark card with the same form logic,
but uses display: block; width: 100% for the input and button rather than a
side-by-side layout.

---
import MailingListCTASidebar from "../components/MailingListCTASidebar.astro";
---

<aside class="post__sidebar">
  <nav class="toc"><!-- ... --></nav>
  <MailingListCTASidebar />
</aside>

Dark mode theming

The card background is hardcoded to #0f0f0f rather than
var(--color-ink). This is intentional — --color-ink flips to #f0f0f0 in
dark mode (it's the text colour token), so using it for a background produces a
near-white card. The footer on this site has the same issue and uses the same
fix.

To make the card visible in dark mode where the page background is #111111, I
added a pink top border and a subtle edge border:

.mailing-cta__card {
  background-color: #0f0f0f;
  border-radius: 8px;
  padding: 2.5rem;
  border-top: 3px solid var(--color-pink);
  border-left: 1px solid rgba(255, 255, 255, 0.06);
  border-right: 1px solid rgba(255, 255, 255, 0.06);
  border-bottom: 1px solid rgba(255, 255, 255, 0.06);
}

The pink top border serves as the primary visual anchor in both modes. In light
mode the contrast between in the dark card and white page does the work; in dark
mode the subtle borders define the card edges.

What Resend handles for you

Once a contact is in your audience, Resend takes care of the rest:

Duplicate contacts — adding the same email again updates the existing record rather than creating a duplicate.
Unsubscribe management — you can send broadcasts with unsubscribe links built in, and Resend updates the contact's unsubscribed flag automatically.
Broadcasts — send to the full audience from the Resend dashboard or via the POST /broadcasts API.

The free tier covers 3,000 emails per month and 100 contacts in audiences, which
is plenty for a personal blog getting started.

Wrap-up

The full implementation is around 200 lines across three files: subscribe.ts,
subscribeForm.ts, and the two Astro components. Resend handles deduplication,
unsubscribe management, and broadcast delivery, keeping the site code lean.

If you're already using Resend for comment notifications, the only new piece is
subscribe.ts. The welcome email script is a one-off setup, and the components
drop in wherever a CTA makes sense.

Scheduled publishing in Astro on Netlify

Roger Rajaratnam — Thu, 21 May 2026 09:48:39 +0000

Original post: Scheduled publishing in Astro on Netlify

Series: Part of How this blog was built — documenting every decision that shaped this site.

Static sites have an elegant deployment story right up until you need to publish
something on a specific date. A CMS solves this with a "schedule" button. A
database-backed blog solves this with a query clause. A static site rebuilds once
at deploy time — after that, nothing changes until the next deploy.

For most personal blogs that's fine. Mine has posts queued weeks ahead with
deliberate publish dates, so letting it drift wasn't an option.

The solution has three parts: a helper that knows whether a post is visible right
now, a scheduled function that triggers a daily rebuild, and a cron expression
chosen so the build always fires before 9am UK time. None of it requires a CMS or
a database.

The problem with `draft: false` alone

The draft field already keeps in-progress posts off the live site. But draft
is a binary flag set at write time — you have to remember to flip it, and the post
goes live on the next deploy, not at a predictable time.

What's needed is a second condition: the post's pubDate must be in the past
before it appears. The build already has access to the current time, so this is a
straightforward filter.

`isPublished()` — one filter to rule them all

Every page and component that calls getCollection("posts") needs to apply the
same logic. The cleanest way to enforce this is a shared helper in
src/utils/drafts.ts:

// Drafts are hidden by default. `pnpm dev` enables them locally via SHOW_DRAFTS=true.
// Also enabled in production when SHOW_DRAFTS=true (used by the preview branch deploy).
export const showDrafts: boolean = import.meta.env.SHOW_DRAFTS === "true";

type PublicationData = { draft: boolean; pubDate: Date };

export type PublicationStatus = "draft" | "scheduled" | "published";

function getPublicationData(
  input: { data: PublicationData } | PublicationData,
): PublicationData {
  return "data" in input ? input.data : input;
}

export function getPublicationStatus(
  input: { data: PublicationData } | PublicationData,
): PublicationStatus {
  const data = getPublicationData(input);

  if (data.draft) return "draft";
  if (data.pubDate > new Date()) return "scheduled";
  return "published";
}

export function isPubliclyPublished(post: {
  data: { draft: boolean; pubDate: Date };
}): boolean {
  return getPublicationStatus(post) === "published";
}

// Returns true for posts that should be visible at build/request time.
// Hides drafts (unless showDrafts) and posts whose pubDate is in the future.
export function isPublished(post: {
  data: { draft: boolean; pubDate: Date };
}): boolean {
  if (showDrafts) return true;
  return isPubliclyPublished(post);
}

isPublished replaces every inline draft check across the codebase. Before
this, each call site had a slightly different spelling of the same test — and
none of them checked the date:

// Before — only checked draft, missed pubDate entirely
.filter((post) => !post.data.draft)

// After — consistent and date-aware
.filter(isPublished)

The call sites appear in pages, paginated routes, tag pages, and sidebar
components — nine files in total. Replacing them all at once means there is no
path through the build where a future-dated post can slip through.

Two functions in drafts.ts are worth keeping straight:

isPublished — use this for rendering post lists. When SHOW_DRAFTS=true (set by default when you run pnpm dev), it passes through drafts and scheduled posts so you can preview queued content locally. On production builds it hides both.
isPubliclyPublished — use this anywhere that must reflect strict public state regardless of preview mode: RSS feeds, post counts, sitemaps. It always behaves as if SHOW_DRAFTS is off.

Setting `pubDate` values

For the filter to work predictably, pubDate values need to be straightforward
UTC timestamps with no offset:

pubDate: 2026-04-13T00:00:00

A date like 2026-04-13T09:00:00+01:00 evaluates to 08:00 UTC. If the build
fires at 07:45 UTC, the post will not appear until the following day's build —
one day late and silently wrong. Midnight UTC removes this class of error entirely.

If two posts share the same date and you care about their sort order, a short
offset keeps them before the build window and in the intended sequence:

# Appears first in descending sort (higher timestamp)
pubDate: 2026-03-30T00:10:00

# Appears second
pubDate: 2026-03-30T00:00:00

The scheduled Netlify function

Astro builds the site once at deploy time. To have it pick up newly-eligible posts
each day, we need to trigger a fresh deploy on a schedule.

Netlify supports this natively: a function declared with a schedule in
netlify.toml runs as a cron job. Our function's only job is to call the Netlify
build hook API:

export default async function handler() {
  const hookId = process.env.BUILD_HOOK_ID;

  if (!hookId) {
    console.error("BUILD_HOOK_ID is not set — skipping scheduled build.");
    return;
  }

  const url = `https://api.netlify.com/build_hooks/${encodeURIComponent(hookId)}`;
  const res = await fetch(url, { method: "POST" });

  if (res.ok) {
    console.log("Scheduled build triggered successfully.");
  } else {
    console.error(`Failed to trigger build: ${res.status} ${res.statusText}`);
  }
}

No npm packages needed — the function uses the standard fetch and an environment
variable for the hook ID.

netlify.toml configuration

The schedule is declared alongside the function configuration in netlify.toml.

[functions]
  directory = "netlify/functions"
  node_bundler = "esbuild"

# Rebuild daily so future-dated posts go live automatically.
# Requires BUILD_HOOK_ID env var — see netlify/functions/scheduled-build.mjs.
[functions."scheduled-build"]
  schedule = "45 7 * * *" # always before 09:00 UK time: 07:45 GMT in winter, 08:45 BST in summer

Netlify's cron syntax is always UTC. 45 7 * * * fires at 07:45 UTC — before
09:00 in both BST (UTC+1) and GMT (UTC+0). If you'd rather guarantee 08:45 BST
and accept 07:45 GMT in winter, the expression is the same — there is no
timezone-aware option in cron, so you pick the UTC value that satisfies your
worst case.

Dashboard setup

One step in the Netlify dashboard is required:

Site configuration → Build & deploy → Build hooks — create a hook named "Scheduled publish". Netlify generates a URL ending in a unique ID.
Copy just the ID from the URL (the path segment after /build_hooks/).
Site configuration → Environment variables — add a new variable:
- Key: BUILD_HOOK_ID
- Value: the ID you copied
Add BUILD_HOOK_ID to your local .env.example (without a value) so it's documented for anyone cloning the repository.

The function reads this variable and constructs the full URL itself, so the secret
is never hardcoded in the repository.

Verifying the setup

Before waiting for the next scheduled run, confirm everything is wired up
correctly.

Trigger a build manually. POST to the hook URL directly from your terminal:

curl -X POST "https://api.netlify.com/build_hooks/YOUR_HOOK_ID"

Replace YOUR_HOOK_ID with the ID you copied. Netlify responds with {} and a
200 — check the Deploys tab in the dashboard to confirm a build starts within a
few seconds.

Check function logs after a scheduled run. Once the cron fires, Netlify logs
the function's output under Functions in the dashboard. Select
scheduled-build and look for Scheduled build triggered successfully. in the
invocation log. If BUILD_HOOK_ID is missing or misconfigured, the error message
from the early return will appear there instead.

How it fits together

A post ready to publish looks like this:

---
title: "My next post"
pubDate: 2026-04-20T00:00:00
draft: false
---

Push to main. Netlify deploys immediately — because pubDate is in the future,
isPublished returns false and the post is excluded from every page. On the
morning of April 20th, the scheduled-build function fires at 07:45 UTC, triggers
a new deploy, and isPublished returns true. The post goes live without any
manual intervention.

Diagram fallback for Dev.to. View the canonical article for the full version: https://sourcier.uk/blog/scheduled-publishing-astro

Where `draft` still fits in

With scheduled publishing in place, draft and pubDate serve two distinct roles.

draft: true means the post isn't ready — you're still writing it, it might
be half-finished, and you don't want it visible even in a deploy preview. It hides
the post indefinitely regardless of its date. Running pnpm dev reveals it locally
(SHOW_DRAFTS=true is set by default in the dev script). Nothing goes live until
you explicitly flip the flag.

draft: false with a future pubDate means the post is complete and queued.
You're done writing, you're happy with it, and you want it to go live on a specific
date without any further action from you.

The practical workflow:

Start writing → draft: true, no pubDate needed yet
Finish writing → draft: false, set a future pubDate
Push → the post sits invisibly in the repository until its date arrives
Morning of the publish date → the scheduled build picks it up automatically

The only thing to be careful about: if you push draft: false with a past
pubDate, the post goes live immediately on that deploy rather than waiting for
the next scheduled build. Past dates are treated as "already due", not scheduled.

What this doesn't do

Minute-precision timing. Builds take a minute or two, so "publish on April
20th" means "publish sometime between 07:45 and ~08:00 UTC on April 20th". For a
personal blog that's entirely fine.

Build deduplication. If you push a code change on the same morning, Netlify
may queue two builds back to back. Both would produce the correct result — the
second one is just redundant. You could add a check in the function to skip the
trigger if a recent deploy already exists, but it's rarely worth the complexity.

Unpublishing. Moving a post's pubDate forward while keeping draft: false
will not remove it from the live site because Netlify serves the last successful
build until a new one is deployed. Drafts (draft: true) are the right tool for
keeping content off the site.

Wrapping up

With the three pieces in place, scheduled publishing runs without any manual
intervention. drafts.ts gives you isPublished for filtering post lists and
isPubliclyPublished for feeds and counts. The scheduled function fires daily
at the time you configured and triggers a fresh build. The build hook in the
Netlify dashboard is the only setup step that lives outside the repository.

The authoring workflow reduces to: write the post, set draft: false with a
future pubDate, push, and walk away. The scheduled build on publish day takes
care of the rest.

Working on something similar?

If you're building a content pipeline, a scheduled job, or anything that needs
reliable deploy automation — I'm available for consulting. Get in touch via the
contact page and tell me what you're working on.

Sending new post notifications with Resend

Roger Rajaratnam — Fri, 15 May 2026 13:48:00 +0000

Original post: Sending new post notifications with Resend

Series: Part of How this blog was built — documenting every decision that shaped this site.

When a new post goes live, I want subscribers to know about it. The mailing list
runs through Resend — subscribers are stored in a Resend
Segment, and broadcasting to them means calling the Resend Broadcasts API. The
question was: how do I trigger that broadcast as part of the publish flow, without
adding complexity to the build pipeline?

The answer is a standalone Node.js script — scripts/notify-new-post.js — that
runs manually after publishing. It reads frontmatter directly, builds an HTML email,
previews it in the terminal, and asks for confirmation before sending.

Diagram fallback for Dev.to. View the canonical article for the full version: https://sourcier.uk/blog/new-post-notifications-resend

Why a script rather than a build hook

There are a few reasons.

A build hook would run on every deploy, including deploys for unrelated changes like
CSS fixes or draft work. Broadcasts should only happen for new public posts —
triggering them from the build process would require additional logic to detect
whether anything post-worthy had actually changed, which gets complicated quickly.

Running the script manually is intentional friction. It forces a moment of review
before an email goes out to every subscriber. That's the right default.

Dependencies

The script uses one external dependency: @inquirer/prompts
for interactive select and confirmation prompts. Everything else is Node.js built-ins —
readFileSync, readdirSync, path utilities. No Astro, no Zod, no content collections.

Reading frontmatter without a build

The script includes a minimal frontmatter parser rather than pulling in a YAML library:

function parseFrontmatter(content) {
  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
  if (!match) return {};
  const yaml = match[1];
  const result = {};

  for (const line of yaml.split(/\r?\n/)) {
    const m = line.match(/^(\w+):\s*["'>]?(.*?)["']?\s*$/);
    if (m) result[m[1]] = m[2].trim();
  }

  // Handle YAML block scalar for description (>- or >)
  const descBlock = yaml.match(/^description:\s*>-?\r?\n((?:[ \t]+.+\r?\n?)*)/m);
  if (descBlock) {
    result.description = descBlock[1]
      .split(/\r?\n/)
      .map((l) => l.trim())
      .filter(Boolean)
      .join(" ");
  }

  return result;
}

This only handles simple key: value lines and the >- block scalar for
description. It's intentionally minimal — the script doesn't need to parse
the full YAML AST.

The listPostIds function finds posts published in the past week that aren't drafts.
Each directory read is wrapped in a try/catch so unreadable or malformed posts are
silently skipped rather than crashing the script:

function listPostIds() {
  const postsDir = join(root, "collections", "posts");
  const oneWeekAgo = Date.now() - 7 * 24 * 60 * 60 * 1000;

  return readdirSync(postsDir, { withFileTypes: true })
    .filter((d) => d.isDirectory())
    .map((d) => {
      try {
        const content = readFileSync(join(postsDir, d.name, "index.md"), "utf8");
        const fm = parseFrontmatter(content);
        const pubDate = fm.pubDate ? new Date(fm.pubDate).getTime() : 0;
        const isDraft = fm.draft === "true";
        return { id: d.name, pubDate, isDraft };
      } catch {
        return null;
      }
    })
    .filter((p) => p && !p.isDraft && p.pubDate >= oneWeekAgo)
    .sort((a, b) => b.pubDate - a.pubDate)
    .map((p) => p.id);
}

Environment variables

The script reads secrets from a .env file in the project root (using Node 20.12's
process.loadEnvFile) or from shell environment variables — shell variables take
precedence:

const envFile = join(root, ".env");
if (existsSync(envFile)) {
  if (typeof process.loadEnvFile === "function") {
    process.loadEnvFile(envFile);
  }
}

Required variables:

RESEND_API_KEY — Resend API key with broadcast send permissions
RESEND_SEGMENT_ID — the Segment ID to broadcast to
SITE_URL — base URL used to construct post links (defaults to https://sourcier.uk)

Optional variables:

NOTIFY_FROM_EMAIL — the From: address in the broadcast (defaults to Roger @ Sourcier <hello@sourcier.uk>)
RESEND_TOPIC_ID — if set, attaches a topic to the broadcast for unsubscribe granularity

The email content

The broadcast is sent with both an HTML body and a plain-text fallback. Email clients
that can't render HTML receive the plain-text version; everything else gets the styled one.

The HTML is built as an inline-styled string. Email clients don't support external
stylesheets or CSS custom properties — everything needs to be inline and use safe font stacks:

function buildHtml() {
  return `
<div style="font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;max-width:560px;margin:0 auto;padding:2rem 1.5rem;color:#0f0f0f">
  <p style="margin:0 0 1.5rem;line-height:1.6">Hi — I just published something new on Sourcier.</p>
  <p style="font-size:1.5rem;font-weight:800;letter-spacing:-0.01em;margin:0 0 1rem;line-height:1.2">${title}</p>
  ${excerpt ? `<p style="margin:0 0 1.5rem;line-height:1.6;color:#444">${excerpt}</p>` : ""}
  <a href="${url}" style="display:inline-block;background:#e8006a;color:#fff;text-decoration:none;padding:0.65rem 1.5rem;font-weight:700;font-size:0.875rem;letter-spacing:0.04em;text-transform:uppercase">Read the post →</a>
  <p style="margin:1.5rem 0 0;line-height:1.6;color:#444">If it sparks any thoughts, I'd love to hear them — there's a comments section at the bottom of the post.</p>
  <p style="margin:1rem 0 0;line-height:1.6">— Roger</p>
  <hr style="margin:2rem 0;border:none;border-top:1px solid #e5e5e5">
  <p style="margin:0;color:#999;font-size:0.8125rem;line-height:1.5">
    You're receiving this because you subscribed at sourcier.uk.<br>
    <a href="{{{RESEND_UNSUBSCRIBE_URL}}}" style="color:#999">Unsubscribe</a>
  </p>
</div>`.trim();
}

The {{{RESEND_UNSUBSCRIBE_URL}}} placeholder is Resend's broadcast template
variable — it's replaced at send time with a personalised unsubscribe link for each
recipient. It's required by anti-spam regulations (CAN-SPAM, GDPR).

Confirmation before sending

The script uses @inquirer/prompts for both the post selection and the send confirmation.
After printing the preview, it asks:

const shouldSend = await confirm({
  message: "Send this to all subscribers?",
  default: false,
});

if (!shouldSend) {
  console.log("Aborted — nothing was sent.");
  process.exit(0);
}

The default is false, so pressing Enter without typing y aborts safely.

If the post has draft: true in its frontmatter, the script surfaces a warning
and asks a second confirmation before continuing. It doesn't block sending outright —
there are legitimate reasons to test-send a draft — but it makes the state explicit.

The two-step API call

Sending a broadcast is two separate calls to the Resend API. The first creates the
broadcast and returns an ID:

const createRes = await fetch(`${RESEND_API}/broadcasts`, {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
  body: JSON.stringify({ name: title, from: FROM, subject: SUBJECT, html, text, segment_id: segmentId }),
});
const { id } = await createRes.json();

The second dispatches it to the segment:

await fetch(`${RESEND_API}/broadcasts/${id}/send`, {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}` },
});

Separating creation from dispatch is useful — it means the broadcast exists in the
Resend dashboard before it's sent, so you can inspect or cancel it if something looks wrong.

Running the script

node scripts/notify-new-post.js

The script lists posts published in the past week, prompts to select one, shows a
preview, and waits for confirmation. Pass --debug to log the full API request
payload and response status to the terminal without sending anything.

Total runtime is a few seconds.

The approach here is deliberately low-tech: no build integration, no CI step, no
webhook. A standalone script with a confirmation prompt is the right level of
automation for something that goes out to every subscriber. The friction is the
feature.

The full script is in the
sourcier.uk repository.

Deploying an Astro blog to Netlify

Roger Rajaratnam — Thu, 14 May 2026 09:03:24 +0000

Original post: Deploying an Astro blog to Netlify

Series: Part of How this blog was built — documenting every decision that shaped this site.

This blog runs entirely on Netlify's free tier. Static HTML goes out over the CDN,
serverless functions handle comments and the mailing list, and an edge function gates
deploy previews — all without any infrastructure to manage.

This post covers the configuration details: what goes in netlify.toml, how
functions are set up, which environment variables are required, and how the deploy
preview workflow integrates with the draft post system.

Diagram fallback for Dev.to. View the canonical article for the full version: https://sourcier.uk/blog/deploying-astro-netlify

netlify.toml

Everything Netlify needs to know about building and running the site is in
netlify.toml at the project root:

[dev]
  framework = "astro"
  command = "astro dev"
  targetPort = 4321
  autoLaunch = false

[build]
  command = "astro build"
  publish = "dist"

[functions]
  directory = "netlify/functions"
  node_bundler = "esbuild"

[[headers]]
  for = "/*"
  [headers.values]
    Cache-Control = "public, max-age=0, must-revalidate"

[[headers]]
  for = "/_astro/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

The [dev] section configures Netlify Dev — netlify dev in the terminal starts
both the Astro dev server and the function runtime together, so you can test
serverless functions against the local site. autoLaunch = false prevents Netlify
Dev from opening a browser tab automatically.

[build] points to the Astro build command and the output directory. Astro outputs
to dist/ by default.

[functions] tells Netlify where to find the serverless functions and which
bundler to use. esbuild is significantly faster than webpack for bundling Node.js
functions and handles ES module imports correctly.

Cache headers

The two [[headers]] blocks implement a split caching strategy:

/* — HTML pages get max-age=0, must-revalidate. The browser caches the response but revalidates on every request. When a new deploy lands, Netlify invalidates the CDN edge cache, so clients pick up the new version immediately.
/_astro/* — Astro outputs hashed filenames for all JS and CSS bundles (e.g. _astro/index.B1fJkLmN.js). Because the hash changes whenever the content changes, these assets can be cached indefinitely with max-age=31536000, immutable.

Without the second rule, browsers would re-fetch unchanged bundles on every page load. Without the first, stale HTML pages could reference bundle URLs that no longer exist.

The functions directory

Netlify Functions are TypeScript files in netlify/functions/. Each file is a
separate function, accessible at /.netlify/functions/{filename}:

netlify/
  functions/
    approve-comment.ts   → /.netlify/functions/approve-comment
    comment-handler.ts   → /.netlify/functions/comment-handler
    get-comments.ts      → /.netlify/functions/get-comments
    subscribe.ts         → /.netlify/functions/subscribe

Functions are not bundled with the site — Netlify deploys them separately. The
node_bundler = "esbuild" setting handles tree-shaking and resolves import
statements so each function file can use npm packages.

Edge functions

Edge functions run at Netlify's CDN edge — before the response is served — rather
than as on-demand Lambda invocations. They live in netlify/edge-functions/ and
are configured through the exported config object in each file:

export const config: Config = { path: "/*" };

preview-auth.ts runs on every request. It reads the PREVIEW_PASSCODE
environment variable. When no passcode is configured (production), the function
calls context.next() immediately and is a transparent pass-through. When a
passcode is set (preview deploys), it gates the entire site behind a passcode form
and sets an HttpOnly; Secure; SameSite=Strict session cookie on success.

This is how draft posts are safely visible on deploy previews without being
publicly accessible. The SHOW_DRAFTS=true build variable makes the Astro build
include draft posts; the edge function ensures only someone with the passcode can
reach them.

Environment variables

None of the secrets are stored in netlify.toml. Environment variables split into
two groups depending on when they are consumed.

Build-time variables

These are read by astro build and baked into the generated HTML. Any variable
referenced via import.meta.env falls into this category and must be present when
the build runs:

Variable	What it is
`SHOW_DRAFTS`	Set to `"true"` on preview branch deploys to include draft and scheduled posts

Runtime variables

These are read by serverless and edge functions at request time and are never
embedded in the built HTML. Keep them in the Netlify dashboard only
(Site configuration → Environment variables):

Variable	Used by	What it is
`PREVIEW_PASSCODE`	`preview-auth.ts`	Passcode protecting deploy previews — leave unset in production

For local development, copy these into a .env file in the project root. The
functions read them via process.env. Never commit .env — add it to .gitignore.

PREVIEW_PASSCODE note: Leave this unset in the production site context. When
unset, preview-auth.ts is a transparent pass-through and adds no overhead.
Generate a strong value with:

openssl rand -hex 32

Deploy previews and draft posts

Netlify automatically generates a deploy preview URL for every pull request and
branch push. The URL takes the form https://deploy-preview-{n}--{site-name}.netlify.app.

Draft posts are hidden by default. The isPublished() helper in
src/utils/drafts.ts reads the SHOW_DRAFTS build-time variable:

export const showDrafts: boolean = import.meta.env.SHOW_DRAFTS === "true";

export function isPublished(post: {
  data: { draft: boolean; pubDate: Date };
}): boolean {
  if (showDrafts) return true;
  return isPubliclyPublished(post);
}

Setting SHOW_DRAFTS=true on the preview branch context in the Netlify dashboard
makes the build include draft and scheduled posts. The preview-auth edge function
then gates that deploy behind a passcode, so the preview URL is not publicly accessible.

This is more reliable than temporarily setting draft: false in frontmatter and
remembering to reset it before merging. There is no risk of accidentally publishing
a post that was only meant to be previewed.

One-time Netlify dashboard setup for comments

The comments webhook isn't in netlify.toml — it's a one-time setup in the
Netlify dashboard:

Go to Forms → blog-comments → Form notifications
Add notification → Outgoing webhook
URL: https://your-site.netlify.app/.netlify/functions/comment-handler

This wires up the webhook that triggers the moderation email whenever a new comment
arrives. It only needs to be configured once per site, which is why it's not in the
TOML file.

Wrapping up

With netlify.toml in place, the deployment configuration is declarative and version-controlled alongside the site code. The split caching strategy — aggressive immutable caching for hashed assets, revalidate-always for HTML — keeps the site fast without ever serving stale pages after a deploy.

The functions and edge-functions directories draw a clear line between work that happens at request time on the server and at the CDN edge. preview-auth in particular is what makes safe draft previewing possible — SHOW_DRAFTS controls what gets built, and the passcode gate controls who can see it.

All the secrets stay in the Netlify dashboard, nothing sensitive is in the repository, and a fresh deploy of the whole setup is reproducible from the TOML file and the environment variable list above.

Page history and credits on a static blog

Roger Rajaratnam — Wed, 13 May 2026 19:13:56 +0000

Original post: Page history and credits on a static blog

Series: Part of How this blog was built: documenting every decision that shaped this site.

Most blog posts operate on an implicit contract: once published, they don't change.
Or if they do change, the change is invisible. This is fine for minor edits, but
when you correct something meaningful — a wrong date, a misattributed quote, broken
code — readers who've already seen the post have no way of knowing.

This blog has two optional features that address this: a page history log and a
credits section. Both are schema-validated fields in the content collection and
rendered at the bottom of post pages.

Architecture overview

Diagram fallback for Dev.to. View the canonical article for the full version: https://sourcier.uk/blog/page-history-credits

UI mockup

The wireframe below shows the presentation intent for both metadata surfaces: a
timeline-style history block and compact, pill-style credits.

Diagram fallback for Dev.to. View the canonical article for the original SVG: https://sourcier.uk/blog/page-history-credits

Page history

The history field in a post's frontmatter is an optional array of revision entries:

history:
  - datetime: 2026-03-26T00:00:00
    note: Initial publish.
  - datetime: 2026-03-27T12:00:00
    note: >-
      Corrected the HMAC algorithm description — it&#39;s SHA-256, not SHA-1.

Each entry has a datetime (coerced to a Date by Zod) and a note string.
Notes support inline HTML, so links to related pages and emphasis are possible.

The Zod schema definition:

history: z
  .array(
    z.object({
      datetime: z.coerce.date(),
      note: z.string(),
    }),
  )
  .optional(),

PageHistory.astro renders the entries as an <ol> — a chronological list where
each <li> pairs a <time> element with a <span> for the note:

<div class="page-history">
  <p class="page-history__heading">Page history</p>
  <ol class="page-history__log">
    {entries.map((entry) => (
      <li class="page-history__entry">
        <time
          class="page-history__time"
          datetime={entry.datetime.toISOString()}
        >
          {formatDatetime(entry.datetime)}
        </time>
        <span class="page-history__note" set:html={entry.note} />
      </li>
    ))}
  </ol>
</div>

The <time> element carries the machine-readable ISO 8601 datetime in its
datetime attribute. The human-readable text is formatted with toLocaleDateString
using the en-GB locale.

set:html is used for the note rather than {entry.note} because notes can
contain inline HTML. This is an intentional tradeoff — the content is
author-controlled in a static repository, not user-submitted, so the XSS risk
is the same as any other HTML in the site.

Visually, the history block is rendered at reduced opacity (0.65) and with
a left border — it's clearly secondary information, present for transparency
rather than as a primary content element.

Credits

The credits field follows the same pattern — an optional array, validated by Zod,
with label, text, and an optional URL:

credits:
  - label: Cover image
    text: Kelly Sikkema on Unsplash
    url: https://unsplash.com/@kellysikkema
  - label: Diagram library
    text: Mermaid
    url: https://mermaid.js.org/

credits: z
  .array(
    z.object({
      label: z.string(),
      text: z.string(),
      url: z.string().url().optional(),
    }),
  )
  .optional(),

PageCredits.astro renders them as a <ul>. Each <li> pairs the label with
either an anchor or a plain <span> depending on whether a URL is present. URLs
use target="_blank" with rel="noopener noreferrer".

Attribution is a first-class concern here, not an afterthought. Every Unsplash cover
image has its photographer credited. Libraries and tools that made a feature possible
are listed. When a post is directly inspired by another person's work, that's
acknowledged explicitly. This isn't just good etiquette — it's consistent with how
I'd want my own work credited.

Both components share the same visual treatment: muted, compact, below the main
content and the share widget. They're there for the reader who cares about the
detail, invisible to the reader who doesn't.

Why both belong in the schema

It would be easy to treat history and credits as presentational concerns — markdown
at the bottom of a post, maintained by hand. Putting them in the schema instead
means they're validated on every build, available to any component or page that
needs them, and impossible to malform silently. The discipline of typing them enforces
consistency: every credit has a label, every history entry has a datetime.

Neither field is required. A post with no meaningful revision history doesn't need
a history block. A post with no external sources doesn't need credits. The optionality
is intentional — adding boilerplate entries just to fill a section would dilute the
signal these features are meant to carry.

Building a share widget with the Clipboard API

Roger Rajaratnam — Tue, 05 May 2026 10:59:07 +0000

Original post: Building a share widget with the Clipboard API

Series: Part of How this blog was built — documenting every decision that shaped this site.

Sharing a post is one of those interactions that looks trivial to implement, yet has
a few subtle corners once you get into it, particularly around the copy-to-clipboard
flow and URL construction for each channel.

SharePost.astro is a small component that covers four share targets: LinkedIn,
Reddit, email, and a copy-link button. It has no external dependencies, no JavaScript
frameworks, and no tracking.

The component props

interface Props {
  title: string;
  url: string;
  vertical?: boolean;
  variant?: "default" | "hero" | "sidebar" | "menu";
}

url is the fully qualified canonical URL of the post, passed in from
PageHero.astro as Astro.url.href. vertical flips the layout to a
column stack for sidebar placement. variant applies a modifier class that
controls spacing and sizing for the different contexts the widget appears in.

LinkedIn share URL

LinkedIn's share endpoint accepts a url parameter:

const linkedinUrl =
  `https://www.linkedin.com/sharing/share-offsite/?url=${encodeURIComponent(url)}`;

encodeURIComponent is essential here. A raw URL with query parameters would
break the LinkedIn endpoint's own query string parsing. The component doesn't
pass the title separately: LinkedIn scrapes the OG tags from the shared URL and
uses those for the preview. As long as og:title and og:description are set
correctly (they are: see the OpenGraph post), the
preview will be accurate.

The link uses target="_blank" with rel="noopener noreferrer". noopener
prevents the opened tab from accessing window.opener (a known XSS vector).
noreferrer prevents the referrer header from being sent, which also implies
noopener, but including both is explicit and safe.

Reddit share URL

Reddit's submission endpoint accepts both url and title parameters:

const redditUrl =
  `https://www.reddit.com/submit?url=${encodeURIComponent(url)}&title=${encodeURIComponent(title)}`;

Unlike LinkedIn, Reddit doesn't scrape OG tags to pre-fill the submission title,
so the title is passed explicitly. The submission form still lets the user edit
both fields before posting.

Email share URL

Email sharing uses a mailto: URI with pre-populated subject and body:

const emailBody =
  `I thought you might find this interesting:\n\n"${title}"\n\n${url}`;
const emailUrl =
  `mailto:?subject=${encodeURIComponent(title)}&body=${encodeURIComponent(emailBody)}`;

Both the subject and body are encodeURIComponent-encoded. Without encoding,
special characters in the title (ampersands, quotes, question marks) would
corrupt the mailto: URI. The pre-populated body includes a brief framing line,
the title in quotes, and the URL on its own line. This reads naturally when the
recipient receives it.

Copy link with the Clipboard API

The copy button uses the asynchronous Clipboard API, which requires a secure
context (HTTPS or localhost):

document
  .querySelectorAll("[data-copy-link-btn]")
  .forEach((btn) => {
    if (btn.dataset.bound === "true") return;
    btn.dataset.bound = "true";

    btn.addEventListener("click", async () => {
      const url = btn.dataset.url ?? window.location.href;

      try {
        await navigator.clipboard.writeText(url);
      } catch {
        window.prompt("Copy this link", url);
      }

      const label = btn.querySelector(".copy-link-label");
      if (label) {
        btn.setAttribute("aria-label", "Link copied");
        btn.setAttribute("title", "Link copied");
        label.textContent = "Copied!";
        setTimeout(() => {
          label.textContent = "Copy link";
          btn.setAttribute("aria-label", "Copy link");
          btn.setAttribute("title", "Copy link");
        }, 2000);
      }
    });
  });

The URL to copy is stored in data-url on the button element, set at render time
from the url prop. Falling back to window.location.href is a sensible
defensive default.

The data-bound guard prevents double-binding when the component is rendered
twice on the same page (once in the page hero, once in the sidebar). Without it,
each click would fire two listeners.

After writing to the clipboard, the label text switches to "Copied!" for two
seconds. This is a deliberate choice over a checkmark icon or a toast notification:
a minimal in-place feedback mechanism that needs no additional UI state or animation
complexity. The two-second timeout is long enough to be noticeable but short enough
to reset before a user might click again.

The aria-label and title attributes are updated in sync with the label text so
assistive technology announces the correct state.

If navigator.clipboard.writeText rejects (insecure context, permission denied),
the catch block falls back to window.prompt, which pre-fills the URL so the user
can copy it manually. document.execCommand('copy') is not used as a fallback
because it is deprecated and inconsistently supported across modern browsers.

Placement in the post layout

Diagram fallback for Dev.to. View the canonical article for the original SVG: https://sourcier.uk/blog/share-post-clipboard

The share widget appears twice on a post page. The two placements serve different
reading stages: the hero slot catches readers the moment they arrive, before they
have committed to the article; the sidebar slot catches them while they are reading
or after they finish, without requiring them to scroll back to the top.

In PageHero.astro, the widget sits horizontally below the post metadata, visible
immediately without scrolling. In MarkdownPostLayout.astro, a vertical variant
appears in the sidebar, staying in view as the reader moves through the content:

<SharePost
  url={Astro.url.href}
  title={frontmatter.title}
  vertical={true}
/>

The vertical prop simply toggles a CSS modifier class that changes flex-direction
from row to column and adjusts alignment. No logic changes, just layout.

Putting it together

Four share targets, no dependencies, and fewer than 120 lines including the styles.
The share URLs follow the same pattern: encode the inputs, assemble the query string,
let the platform handle the rest. The clipboard interaction is the only part that
requires JavaScript, and even that is a single async handler with a window.prompt
fallback for the rare case where the API is unavailable.

The subtlest part of the implementation is the data-bound guard. The widget
appears twice on every post page and the Astro script block runs once per page
load, so without the guard each button would accumulate duplicate listeners on
every render. It is a one-liner that is easy to miss and quietly breaks the UX
if you do.

Next up: page history and credits, covering transparent revision logs and why
attribution deserves to be a first-class concern rather than an afterthought.

Breadcrumb navigation with Schema.org markup

Roger Rajaratnam — Fri, 01 May 2026 13:21:58 +0000

Original post: Breadcrumb navigation with Schema.org markup

Series: Part of How this blog was built — documenting every decision that shaped this site.

Breadcrumbs are one of those components that look simple but have several layers
of correctness: the visual trail, the accessible markup, and the structured data
for search engines. All three matter and only one of them is visible to users.

Breadcrumb.astro handles all three, and it does so with a fallback auto-generation
system that derives the crumb list from the URL path when no explicit list is provided.

Diagram fallback for Dev.to. View the canonical article for the original SVG: https://sourcier.uk/blog/breadcrumb-schema-astro

The component interface

interface Crumb {
  label: string;
  href?: string;
}

interface Props {
  crumbs: Crumb[];
  inverted?: boolean;
  noContainer?: boolean;
}

crumbs is an array of label/href pairs. The final crumb in the list should have
no href — it represents the current page and shouldn't be a link. The inverted
prop flips the colour scheme for placement on dark backgrounds (like the post hero).
The noContainer prop skips the .container wrapper, used when the breadcrumb
sits inside a layout that already handles max-width constraints.

The component prepends a "Home" crumb automatically so callers don't have to include
it in every usage:

const allCrumbs = [{ label: "Home", href: "/" }, ...crumbs];

Auto-generation from URL path

In PageHero.astro, if no explicit crumbs prop is passed, the component falls
back to deriving them from the URL:

function autoCrumbs(path: string): Crumb[] {
  const segments = path.split("/").filter(Boolean);
  const meaningful = segments.filter(
    (s) => s !== "page" && !/^\d+$/.test(s)
  );
  return meaningful.map((seg, i) => ({
    label: seg.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase()),
    href: "/" + meaningful.slice(0, i + 1).join("/"),
  }));
}

The filter strips the literal "page" segment and any purely numeric segments —
so /blog/page/2 produces crumbs for "Blog" but not "Page" or "2". This is the
right behaviour: pagination is a structural detail, not a meaningful content level.

Labels are formatted by replacing hyphens with spaces and capitalising each word.
"why-astro" becomes "Why Astro". It's not perfect for every slug — a post
titled "Using MDX" with slug using-mdx would render as "Using Mdx" — but it's
good enough for this site's naming conventions.

Schema.org BreadcrumbList

Search engines use BreadcrumbList structured data
to display a breadcrumb trail in search results. The markup sits inline in the
rendered HTML using itemscope and itemprop attributes:

<ol
  class="breadcrumb__list"
  itemscope
  itemtype="https://schema.org/BreadcrumbList"
>
  {items.map(({ label, href, isLast, position }) => (
    <li
      class="breadcrumb__item"
      itemprop="itemListElement"
      itemscope
      itemtype="https://schema.org/ListItem"
    >
      {!isLast && href ? (
        <a href={href} class="breadcrumb__link" itemprop="item">
          <span itemprop="name">{label}</span>
        </a>
      ) : (
        <span
          class="breadcrumb__current"
          aria-current="page"
          itemprop="name"
        >
          {label}
        </span>
      )}
      <meta itemprop="position" content={String(position)} />
    </li>
  ))}
</ol>

The <meta itemprop="position"> tag carries the 1-based index for each crumb.
Google uses this to understand the hierarchy — it won't infer the order from
DOM order alone when using microdata.

Accessibility

The <nav> element has an aria-label="Breadcrumb" attribute to distinguish it
from other navigation landmarks on the page (the main navbar also uses <nav>):

<nav aria-label="Breadcrumb" class="breadcrumb-nav">

The current page crumb uses aria-current="page" and is rendered as <span>
rather than <a> — it's the page the user is already on, so making it a link
would be misleading. Screen readers announce aria-current="page" explicitly,
giving users the context they need.

The complete component and its integration in PageHero.astro are in the
sourcier.uk repository.

Full code listing

---
interface Crumb {
  label: string;
  href?: string;
}

interface Props {
  crumbs: Crumb[];
  inverted?: boolean;
  noContainer?: boolean;
}

const { crumbs, inverted = false, noContainer = false } = Astro.props;
const allCrumbs = [{ label: "Home", href: "/" }, ...crumbs];

const items = allCrumbs.map((crumb, index) => ({
  ...crumb,
  isLast: index === allCrumbs.length - 1,
  position: index + 1,
}));
---

<nav
  aria-label="Breadcrumb"
  class:list={["breadcrumb-nav", { "breadcrumb-nav--inverted": inverted }]}
>
  {
    noContainer ? (
      <ol
        class="breadcrumb__list"
        itemscope
        itemtype="https://schema.org/BreadcrumbList"
      >
        {items.map(({ label, href, isLast, position }) => (
          <li
            class="breadcrumb__item"
            itemprop="itemListElement"
            itemscope
            itemtype="https://schema.org/ListItem"
          >
            {!isLast && href ? (
              <a href={href} class="breadcrumb__link" itemprop="item">
                <span itemprop="name">{label}</span>
              </a>
            ) : (
              <span
                class="breadcrumb__current"
                aria-current="page"
                itemprop="name"
              >
                {label}
              </span>
            )}
            <meta itemprop="position" content={String(position)} />
          </li>
        ))}
      </ol>
    ) : (
      <div class="container is-max-desktop">
        <ol
          class="breadcrumb__list"
          itemscope
          itemtype="https://schema.org/BreadcrumbList"
        >
          {items.map(({ label, href, isLast, position }) => (
            <li
              class="breadcrumb__item"
              itemprop="itemListElement"
              itemscope
              itemtype="https://schema.org/ListItem"
            >
              {!isLast && href ? (
                <a href={href} class="breadcrumb__link" itemprop="item">
                  <span itemprop="name">{label}</span>
                </a>
              ) : (
                <span
                  class="breadcrumb__current"
                  aria-current="page"
                  itemprop="name"
                >
                  {label}
                </span>
              )}
              <meta itemprop="position" content={String(position)} />
            </li>
          ))}
        </ol>
      </div>
    )
  }
</nav>

<style lang="scss">
  .breadcrumb-nav {
    padding: 0.6rem 1.5rem;
    background-color: var(--surface-elevated);
    border-bottom: 1px solid var(--border-subtle);

    &--inverted {
      padding: 0;
      background-color: transparent;
      border-bottom: none;
      margin-bottom: 1.25rem;

      .breadcrumb__link {
        color: var(--text-on-strong-alpha-45);

        &:hover,
        &:focus-visible {
          color: var(--accent-primary);
        }
      }

      .breadcrumb__current {
        color: var(--text-on-strong-alpha-75);
      }

      .breadcrumb__item:not(:last-child)::after {
        color: var(--text-on-strong-alpha-25);
      }
    }
  }

  .breadcrumb__list {
    display: flex;
    flex-wrap: wrap;
    align-items: center;
    gap: 0;
    list-style: none;
    margin: 0;
    padding: 0;

    font-family: "Barlow Condensed", sans-serif;
    font-size: 0.8rem;
    font-weight: 600;
    text-transform: uppercase;
    letter-spacing: 0.06em;
  }

  .breadcrumb__item {
    display: flex;
    align-items: center;

    &:not(:last-child)::after {
      content: "›";
      margin: 0 0.4em;
      color: var(--text-muted);
      font-weight: 400;
    }
  }

  .breadcrumb__link {
    color: var(--text-muted);
    text-decoration: none;
    transition: color 0.15s ease;

    &:hover,
    &:focus-visible {
      color: var(--accent-primary);
    }
  }

  .breadcrumb__current {
    color: var(--text-primary);
  }
</style>

Adding an RSS feed to an Astro blog

Roger Rajaratnam — Tue, 28 Apr 2026 14:58:32 +0000

Original post: Adding an RSS feed to an Astro blog

Series: Part of How this blog was built — documenting every decision that shaped this site.

RSS is the oldest and most reliable way to follow a blog. No algorithm, no
platform dependency, no notification settings. A reader checks the feed URL,
sees new items, shows them. That simplicity is exactly why it's worth supporting.

Adding an RSS feed to an Astro site is straightforward with the @astrojs/rss
package. There are a few things to get right: draft filtering, absolute URLs,
and a self-referencing link that validators expect.

Installing the package

Astro doesn't ship with RSS support out of the box, but the official integration
adds everything needed:

pnpm add @astrojs/rss

The feed endpoint

The feed lives at src/pages/rss.xml.js. Astro treats any .js file in
src/pages/ as a route, and a named GET export marks it as an endpoint that
generates output at build time.

A few parts of this are easy to get wrong.

Draft filtering

The draft flag alone isn't enough. A post with draft: false and a future
pubDate is scheduled, not live. Filtering on !post.data.draft would leak
it into the feed before it's published.

This blog distinguishes three publication states:

State	Condition
`draft`	`draft: true`
`scheduled`	`draft: false`, future `pubDate`
`published`	`draft: false`, past or current `pubDate`

The isPubliclyPublished utility returns true only for the published state:

export function isPubliclyPublished(post: {
  data: { draft: boolean; pubDate: Date };
}): boolean {
  return !post.data.draft && post.data.pubDate <= new Date();
}

If you haven't extracted this into a utility, the inline equivalent is:

const now = new Date();
const posts = (await getCollection("posts"))
  .filter((post) => !post.data.draft && post.data.pubDate <= now)
  .sort(/* ... */);

Do not use import.meta.env.DEV to conditionally include drafts. The RSS feed
should never expose unpublished content, regardless of the build environment.

Sorting

Posts are sorted by pubDate descending so the most recent item appears first.
Most RSS readers display items in the order they appear in the feed XML, so the
sort order matters.

.sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf())

Post links

The link value uses post.id, which in Astro's Content Layer API is the
folder name of each post. For a post at collections/posts/rss-feed-astro/index.md,
post.id is rss-feed-astro. Prefixing it with /blog/ produces the correct
page URL, with no slug manipulation needed.

link: `/blog/${post.id}/`,

Absolute URLs

The site property on the rss() call is context.site, the value set in
astro.config.mjs:

export default defineConfig({
  site: "https://sourcier.uk",
  // ...
});

The @astrojs/rss package uses this to resolve relative link values into
absolute URLs. Without site configured, feed items would have relative URLs
that most RSS readers can't navigate.

atom:link self-reference

RSS validators and some readers expect an <atom:link rel="self"> element in
the channel, pointing back to the feed's own URL. The atom namespace must also
be declared on the root <rss> element, which the @astrojs/rss package handles
via the xmlns option:

xmlns: {
  atom: "http://www.w3.org/2005/Atom",
},
customData: [
  `<language>en-gb</language>`,
  `<atom:link href="${context.site}rss.xml" rel="self" type="application/rss+xml"/>`,
].join(""),

Without this, the W3C validator flags a "missing atom:link" warning and some
readers cannot determine the canonical feed URL.

Validating the feed

Before deploying, it's worth running the built feed through the
W3C Feed Validation Service or
RSS Board's validator. Common
mistakes like missing pubDate, non-absolute link values, and invalid XML
characters in post content all surface here before they cause problems in readers.

Build the site locally and check dist/rss.xml:

pnpm build && open dist/rss.xml

The raw XML should be readable in the browser. If the browser shows a parse
error, something in the feed is malformed.

Adding the feed autodiscovery link

RSS readers look for a <link rel="alternate"> tag in the page <head> to
discover the feed URL automatically. Add it to BaseLayout.astro:

<link
  rel="alternate"
  type="application/rss+xml"
  title="Sourcier RSS Feed"
  href="/rss.xml"
/>

With this in place, browsers and readers that support RSS autodiscovery will
surface the feed when a user visits any page on the site.

The complete feed endpoint and autodiscovery link are in the
sourcier.uk repository.

Full code listing

import rss from "@astrojs/rss";
import { getCollection } from "astro:content";
import { isPubliclyPublished } from "../utils/drafts";

export async function GET(context) {
  const posts = (await getCollection("posts"))
    .filter(isPubliclyPublished)
    .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());

  return rss({
    title: "Sourcier — Blog",
    description:
      "Practical software engineering writing for people transitioning into tech, engineers growing in confidence, and teams improving engineering practice.",
    site: context.site,
    xmlns: {
      atom: "http://www.w3.org/2005/Atom",
    },
    items: posts.map((post) => ({
      title: post.data.title,
      description: post.data.description,
      pubDate: post.data.pubDate,
      link: `/blog/${post.id}/`,
    })),
    customData: [
      `<language>en-gb</language>`,
      `<atom:link href="${context.site}rss.xml" rel="self" type="application/rss+xml"/>`,
    ].join(""),
  });
}

OpenGraph, Twitter Cards, and article metadata in Astro

Roger Rajaratnam — Thu, 23 Apr 2026 17:24:24 +0000

Original post: OpenGraph, Twitter Cards, and article metadata in Astro

Series: Part of How this blog was built — documenting every decision that shaped this site.

When someone shares a link to a blog post, the card that appears in Slack, LinkedIn,
or iMessage is determined by OpenGraph tags in the <head>. Get them wrong and the
shared link is an unformatted URL. Get them right and it shows the post title,
description, and a properly sized cover image.

This is table stakes for any public-facing blog, but the implementation details
matter — specifically, how to handle different content types (articles vs. pages),
where to put canonical URLs, and how to avoid the common mistake of sharing a
relative image path that produces a broken card.

Centralising metadata in BaseLayout

All meta tags are defined once in BaseLayout.astro. Every page passes what it
needs as props; the layout handles the markup. This avoids duplication and ensures
no page accidentally skips essential tags:

interface Props {
  pageTitle: string;
  description?: string;
  ogImage?: string;
  ogType?: "website" | "article";
  canonicalUrl?: string;
  pubDate?: Date;
  author?: string;
  tags?: string[];
}

const {
  pageTitle,
  description = "Practical software engineering guidance from Roger Rajaratnam for people breaking into tech, engineers growing in confidence, and teams improving engineering practice.",
  ogImage = "/og-image.png",
  ogType = "website",
  canonicalUrl = Astro.url.href,
  pubDate,
  author,
  tags,
} = Astro.props;

The default description covers general pages. The default ogType is "website".
Both are overridden for posts. The default canonicalUrl is Astro.url.href —
the fully qualified URL including the site's site value from astro.config.mjs.

The OpenGraph block

<!-- OpenGraph -->
<meta property="og:type"        content={ogType} />
<meta property="og:site_name"   content={siteName} />
<meta property="og:title"       content={pageTitle} />
<meta property="og:description" content={description} />
<meta property="og:url"         content={canonicalUrl} />
<meta property="og:image"       content={new URL(ogImage, Astro.site ?? Astro.url.origin).href} />
<meta property="og:image:width"  content="1200" />
<meta property="og:image:height" content="630" />
<meta property="og:locale"      content="en_GB" />

The og:image value deserves attention. A relative path like /og-image.png
won't work in OG tags — social crawlers need an absolute URL. Constructing it
with new URL(ogImage, Astro.site) handles both cases: if ogImage is already
absolute it passes through unchanged; if it's a root-relative path it's resolved
against the site's configured base URL.

siteName is a plain constant — const siteName = "Sourcier" — defined at the
top of BaseLayout.astro. og:locale uses the IETF language tag for British
English, which matches the site's target audience.

1200×630 is the recommended OG image size that renders well across Facebook,
LinkedIn, and Slack.

Article-specific tags

When ogType is "article", the Open Graph protocol defines additional properties
for structured article metadata. These are conditionally rendered:

{pubDate && (
  <meta
    property="article:published_time"
    content={pubDate.toISOString()}
  />
)}
{author && <meta property="article:author" content={author} />}
{tags && tags.map((tag) => (
  <meta property="article:tag" content={tag} />
))}

article:published_time uses the ISO 8601 format with timezone — Date.toISOString()
provides this. article:tag can appear multiple times, once per tag. Some scrapers
and indexers use these to understand content type and category.

Twitter Cards

X (formerly Twitter) has its own metadata system that runs parallel to OpenGraph. The summary_large_image
card type displays the image at full width above the title and description:

<meta name="twitter:card"        content="summary_large_image" />
<meta name="twitter:title"       content={pageTitle} />
<meta name="twitter:description" content={description} />
<meta name="twitter:image"       content={new URL(ogImage, Astro.site ?? Astro.url.origin).href} />

The property names keep the twitter: prefix — these are a stable protocol standard and won't change regardless of the platform rebrand. X falls back to OpenGraph values for some properties, but it's more reliable to specify them explicitly. The image URL construction is the same as for OG.

Canonical URLs

<link rel="canonical" href={canonicalUrl} />

The canonical tag tells search engines which URL is the authoritative version of a
page, which matters if content appears at multiple URLs or is syndicated elsewhere.
canonicalUrl defaults to Astro.url.href so it's correct without any manual
input, but can be overridden for pages that need a different canonical (for example,
a paginated page that canonicalises to page 1).

Passing metadata from post pages

MarkdownPostLayout.astro extracts the relevant frontmatter fields and passes
them to BaseLayout:

const ogImage = frontmatter.cover?.image?.src ?? undefined;

<BaseLayout
  pageTitle={`${frontmatter.title} — Sourcier`}
  description={frontmatter.description}
  ogImage={ogImage}
  ogType="article"
  pubDate={frontmatter.pubDate}
  author={frontmatter.author}
  tags={frontmatter.tags}
>

The ogImage falls back to undefined if no cover is present, which means
BaseLayout will use the default /og-image.png for posts without cover images.

You can browse the rest of the site code in the
web-sourcier.uk repository.

Playwright E2E testing AI skills: JavaScript London talk

Roger Rajaratnam — Wed, 22 Apr 2026 09:11:56 +0000

Original post: Playwright E2E testing AI skills: JavaScript London talk

This post is the companion article to my JavaScript London talk,
Playwright E2E testing AI skills, hosted in
collaboration with NewDay.

The meetup is on Wednesday 29 April 2026, from 6:00 PM to 9:00 PM BST, at
NewDay's offices on 7 Handyside Street in King's Cross, London. The evening
also includes talks from David Whitney
and Elham Khani, and you can still
register on the event page if you plan to
come along.

If you want the slides alongside the article, you can
download the slide deck (.pptx).

The short version of the talk is this: Playwright is already a strong default
for browser automation. The AI part becomes useful when it helps you explore a
real site, identify the journeys that matter, and turn that exploration into
better tests.

The shortest useful explanation of E2E testing is still the same: unit tests
tell you whether the parts work. End-to-end tests tell you whether the product
works.

If a button is hidden behind a cookie banner, a redirect breaks after login, or
the browser submits the wrong payload, your unit tests can still be green. Your
users will still hit the bug.

That is the gap Playwright helps close.

Why this talk is framed around AI skills

I am not interested in using AI to hide how tests work.

I am interested in using it to shorten the boring parts around test creation:
exploration, note-taking, finding likely locators, spotting missing assertions,
and drafting candidate cases for review.

That is a much better fit for AI than asking it to spray out a huge test suite
and hoping it guessed the right behaviours.

The useful pattern is:

use AI to explore and propose
use Playwright to automate and verify
use humans to decide what is worth keeping

That keeps the browser tests honest.

Where E2E fits in the testing pyramid

You do not want to test everything end to end. That is the fastest route to a
slow, noisy, expensive test suite.

You want a small number of high-value E2E tests that protect the user journeys
that matter most.

Diagram fallback for Dev.to. View the canonical article for the full version: https://sourcier.uk/blog/playwright-e2e-testing-talk

The rule I like is simple: use E2E tests for risk, not for coverage.

If a broken flow would hurt users, revenue, or trust, it deserves E2E coverage.
If it is easy to prove with a unit or integration test, it probably does not.

Why Playwright is still the right foundation

There are other good browser automation tools. Playwright is the one I would
start with today for most web teams because it removes a lot of usual friction.

It gives you:

Chromium, Firefox, and WebKit support out of the box
a clean TypeScript-first API
automatic waiting for elements to become actionable
browser contexts for isolated tests
a built-in trace viewer for debugging failures in CI

That matters because AI suggestions are only useful if the underlying tool is
deterministic enough to turn them into repeatable tests.

What the playwright-explore-website skill is

In my setup, I use a playwright-explore-website GitHub Copilot skill backed by
the Playwright MCP server.

It is a small instruction file that tells Copilot to explore a real site with
Playwright, interact with a handful of important flows, document the relevant
UI elements and expected outcomes, and then propose test cases based on what it
found.

Its job is not to replace a Playwright test file. Its job is to make the step
before test writing more grounded in the real browser.

I wrote up the full setup, the original awesome-copilot example I started
from, and the local enhancements in
The playwright-explore-website Copilot skill.

That write-up stays focused on the skill itself. This post is about how I would
use it in a broader Playwright testing workflow.

That makes it a good fit when you are working with:

an unfamiliar product area
a staging site you need to smoke test quickly
a bug report that is missing exact reproduction steps
a flow where you want candidate locators and assertions before coding the test

A prompt like this is already specific enough to be useful:

Use the playwright-explore-website skill on https://staging.example.com.
Explore sign-in, password reset, and checkout.
For each flow, document the user steps, the likely stable locators,
the expected outcome, and a draft Playwright test case.

The value is not the raw prompt. The value is the output: a clearer map of the
journey you are about to automate.

How I would use it for E2E testing

My preferred workflow is:

Diagram fallback for Dev.to. View the canonical article for the full version: https://sourcier.uk/blog/playwright-e2e-testing-talk

This is where the AI piece earns its keep.

Instead of starting from a blank file, you start with a tested path through the
browser, a list of likely selectors, and a set of outcomes worth asserting. You
still need to clean that up into a proper test, but the exploratory work is
faster.

A good flow looks like this:

Pick one critical journey.
Use the skill to explore it and note what the user actually sees.
Turn the best candidate path into a small Playwright test.
Replace weak selectors with semantic locators or data-testid.
Run it in CI with traces and fix the first flaky edge before adding more.

That is enough to prove the approach without bloating the suite.

What E2E tests are good at

Playwright is excellent at checking the flows where the browser is part of the
problem.

Good targets for E2E tests:

sign in, sign out, and session refresh flows
checkout, booking, or other business-critical user journeys
form submission paths that depend on real navigation or API responses
cross-browser regressions
UI issues that only show up once the page is fully assembled

Poor targets for E2E tests:

pure business logic
small validation rules
isolated component states
anything a fast unit test can already prove clearly

That distinction still matters even when AI is involved. The point is not to
replace the rest of the suite. The point is to protect the seams.

Codegen and exploration are different tools

One of the easiest ways to get moving with Playwright is still to record a flow:

pnpm create playwright@latest
pnpm playwright codegen https://your-app.example

Codegen is useful for capturing raw actions quickly.

The playwright-explore-website skill does a different job. It helps you
understand the flow, identify meaningful assertions, and sketch candidate tests
before you commit to code.

That distinction matters. Codegen gives you interaction history. Exploration
gives you testing intent.

You will usually want both:

use the skill when you need to map the journey
use codegen when you need a quick action scaffold
rewrite the result so the test reads like a real scenario

Keeping tests reliable

Flaky tests are worse than missing tests.

Once a team stops trusting the suite, the suite stops being useful.

Let Playwright wait for you

Playwright automatically waits for elements to be attached, visible, stable, and
ready for interaction before acting on them.

That is one of the main reasons its tests feel less fragile than older browser
automation stacks.

Use selectors that survive refactoring

Prefer the most human-facing locator you can.

Good order of preference:

getByRole
getByLabel
getByText
data-testid when you need a stable testing contract

What you want to avoid is binding tests to styling details like .btn-primary
or deep CSS paths that change every time the UI gets cleaned up.

Treat `waitForTimeout` as a smell

If you ever reach for this:

await page.waitForTimeout(2000);

assume the test still is not right.

It may pass on your machine and fail in CI. It may also slow the suite down
while still being unreliable.

Better choices are explicit signals:

await page.waitForURL("**/confirmation");
await page.waitForResponse(/api\/orders/);
await expect(page.getByText("Order confirmed")).toBeVisible();

Make the await match the business signal

This is the distinction that trips people up.

Playwright already auto-waits for an element to become actionable before it
clicks, fills, or types. Explicit awaits are for the thing that happens after
the action.

That means await page.getByRole("button", { name: "Place order" }).click()
can prove the button was clickable. It does not, on its own, prove the order
was created, the redirect finished, or the confirmation UI appeared.

The right explicit wait depends on the signal that tells you the step is really
done:

wait for a URL change when the flow navigates
wait for a response when the backend side effect matters
wait for a loading state to disappear when the page stays put
wait for the final visible UI state when that is what the user would notice

When the click starts the transition, tie the action and the wait together:

await Promise.all([
  page.waitForURL("**/confirmation"),
  page.getByRole("button", { name: "Place order" }).click(),
]);

await expect(page.getByText("Order confirmed")).toBeVisible();

If the page does not navigate, but the server-side effect is the important
part, wait for that response first and then assert the UI:

await Promise.all([
  page.waitForResponse(
    (response) =>
      response.url().includes("/api/orders") && response.ok(),
  ),
  page.getByRole("button", { name: "Place order" }).click(),
]);

await expect(page.getByText("Order confirmed")).toBeVisible();

That style is more honest about what the test depends on. Instead of hoping a
pause is long enough, you name the signal that proves the journey completed.

Page objects are a scaling tool

I do not start with page objects on day one.

If a suite has one or two tests, a couple of small helper functions are often
enough. Page objects start paying off when multiple tests share the same screen,
the same setup, or the same selectors.

The job of a page object is narrow:

keep selectors in one place
expose repeated user actions in product language
reduce copy-paste when the UI changes

A good page object hides selector plumbing. It should not hide the whole test.
The scenario, the assertions, and the reason the flow matters should usually
stay visible in the test file.

This is the sort of thing I mean:

import { Page } from "@playwright/test";

export class LoginPage {
  constructor(private readonly page: Page) {}

  emailField() {
    return this.page.getByLabel("Email");
  }

  passwordField() {
    return this.page.getByLabel("Password");
  }

  async signIn(email: string, password: string) {
    await this.emailField().fill(email);
    await this.passwordField().fill(password);
    await this.page.getByTestId("login-submit").click();
  }
}

The test that uses it can stay focused on the actual journey:

await loginPage.signIn("alice@example.com", "correct horse battery staple");
await expect(page).toHaveURL(/dashboard/);

The trade-off is worth it when the same login flow appears in a few tests.
It is not worth it when every page object becomes a giant wrapper around every
DOM node on the screen.

My rule of thumb is simple: if two or three tests repeat the same selectors and
actions, extract a small page object. Keep it focused on repeated flows, not on
building a mini framework.

Other useful jobs for the same skill

The interesting part of playwright-explore-website is that it is not limited
to authoring E2E tests.

It is also useful for:

exploratory QA on a staging or preview deployment
reproducing vague browser bugs from support tickets
documenting core flows and their expected outcomes
checking console errors and visible breakage after a deploy
validating navigation, forms, and content on a marketing site before release
identifying which user journeys are worth automating next

I would not use it as a substitute for proper accessibility reviews,
performance testing, or security testing. It is a browser exploration tool, not
a complete quality strategy.

Running Playwright in CI and debugging failures

Running the suite in CI is the obvious part.

The more interesting part is what happens after a failure.

Playwright's trace viewer is one of the best reasons to use it. When a test
fails, you can capture a trace and inspect:

every action
a timeline of the test
screenshots at each step
console output
network requests

The workflow is straightforward:

pnpm playwright test --trace=on-first-retry
pnpm playwright show-trace trace.zip

That turns CI failures from guesswork into evidence.

When not to write an E2E test

If your E2E suite becomes the default answer to every testing question, it will
become slow, brittle, and expensive to maintain.

Good reasons not to write an E2E test:

the behaviour is already covered clearly in a unit test
the test would take a long time to set up for very little risk reduction
the UI state is local and easy to verify at component level
the failure would not matter much in production

If a test takes a long time to run but almost never catches a meaningful bug,
it is probably not earning its place in the suite. Remove it, or replace it
with a cheaper test that gives clearer feedback.

A pragmatic place to start

If you are introducing Playwright, or the AI-assisted workflow around it, this
is a sensible first week plan.

Pick one critical user journey.
Explore it with playwright-explore-website.
Write one clean Playwright test from that exploration.
Use semantic locators first, then data-testid where needed.
Run that test in CI with traces enabled.
Fix flakiness before adding more coverage.

That is enough to learn the tool, prove the value, and build trust in the
approach.

Once that first path is stable, add the next one.

Not everything needs an end-to-end test. The paths that matter do.

If you want the official docs after this overview, start here:

The playwright-explore-website Copilot skill

Roger Rajaratnam — Wed, 22 Apr 2026 09:11:43 +0000

Original post: The playwright-explore-website Copilot skill

This is the standalone write-up behind the workflow I referenced in
my JavaScript London talk companion post.

The short version is that playwright-explore-website is a small GitHub
Copilot skill that tells Copilot to use the Playwright MCP server to open a
site, explore a few important user flows, document what it found, and suggest
candidate test cases.

In the latest version, it also treats Playwright as the source of truth for
rendered UI checks. If the task involves a visible change or regression, the
agent should inspect the current UI first, make the change, verify the updated
state afterwards, and clean up temporary screenshots unless the user asked to
keep them.

I did not invent the starting point from scratch. The initial version was
based on the original
playwright-explore-website example in awesome-copilot.
What I changed was the setup guidance and the execution rules, so it behaves
better in real browser work, especially for regression checks and visual QA,
instead of acting like a generic prompt stub.

This post stays focused on the skill itself: where it came from, how I set it
up locally, and the guardrails I added. The talk companion post covers the
broader Playwright testing workflow around it.

Diagram fallback for Dev.to. View the canonical article for the full version: https://sourcier.uk/blog/playwright-explore-website

What the skill is for

This skill sits in the gap between "open the browser and poke around" and
"write the final Playwright test file".

It is useful when you need to:

understand an unfamiliar product area quickly
smoke test a staging or preview deployment
reproduce a bug report that is missing exact steps
verify rendered UI before and after a visible change
identify candidate locators before writing a Playwright test
turn exploratory browsing into a short list of candidate scenarios

That is why I like it. It makes exploration explicit.

The original awesome-copilot example

The original version in awesome-copilot is deliberately small.

At a high level, it tells Copilot to:

navigate to the provided URL with Playwright MCP
identify and interact with 3 to 5 core user flows
document the interactions, locators, and expected outcomes
close the browser context afterwards
summarise the findings and propose test cases

That is already a good baseline because it forces exploration before test
generation. The model has to look at the real site first instead of guessing
what the UI probably looks like.

My local setup

I keep this as a personal skill rather than a repo-specific one.

That means the file lives at:

~/.copilot/skills/playwright-explore-website/SKILL.md

I prefer that because the same workflow is useful across multiple projects.
Once the skill is there, Copilot can discover it in any repo where browser
exploration makes sense.

The frontmatter stays intentionally simple:

---
name: playwright-explore-website
description: 'Website exploration for testing using Playwright MCP'
---

The important part is not the title. It is that the description contains the
right trigger words, so Copilot can load it when the task is about website
exploration, Playwright, or browser-based testing.

Playwright MCP setup

One of the biggest gaps in the original example is that it assumes the
Playwright MCP tools are already available.

That is fine once your machine is configured. It is less helpful the first time
you try to use the skill and the tools are missing.

I added an explicit setup section so the skill can bootstrap the missing piece
instead of failing vaguely.

The CLI path is the shortest route:

code --add-mcp '{"name":"playwright","command":"pnpm","args":["dlx","@playwright/mcp@latest"]}'

If you prefer to wire it up in settings.json, the equivalent config is:

"mcp": {
  "servers": {
    "playwright": {
      "command": "pnpm",
      "args": ["dlx", "@playwright/mcp@latest"]
    }
  }
}

After that, reload VS Code or the Copilot extension and accept the prompt to
start the MCP server.

This matters because a good skill should not only describe the happy path. It
should also help the agent recover when a prerequisite is missing.

The enhancements I added

I kept the core purpose the same, but I tightened how the skill runs.

1. Self-bootstrapping setup instructions

The added ## MCP Server Setup section gives the agent a concrete fallback when
the Playwright tools are unavailable.

That turns a dead end into a fixable setup problem.

2. A serial exploration rule

I added a rule for multi-page and multi-breakpoint work:

If you need to compare multiple pages or breakpoints, inspect them serially or
in separate tabs. Do not queue parallel navigations and screenshots against the
same Playwright page context.

This is a practical guardrail. Browser exploration becomes noisy very quickly if
you mix multiple navigations and screenshots in one live context.

3. Rendered UI review

The newer version also makes the rendered browser state the thing to trust.

Use Playwright to review the rendered UI directly. For implementation or
regression checks, inspect the current state first, then verify the updated
state after changes instead of relying on code inspection alone.

This is the rule that changed the skill most in practice. CSS, JSX, or Astro
templates are not the final UI. The browser is. If the job is about a visible
change, the skill now pushes Copilot to validate the actual rendered result
before it signs off.

4. Visual audit prompts

I also added an explicit visual review prompt:

For visual audits, explicitly note supporting-label readability,
hero-to-first-section spacing, footer divider spacing, and
last-section-to-footer separation when relevant.

That came from real UI review work. I wanted the skill to be useful not just
for functional exploration, but also for browser-based design checks.

5. Screenshot cleanup

I also added a cleanup rule:

Delete any temporary screenshots you created during the session unless the
user explicitly asked to keep them.

This sounds small, but it matters. Exploration and regression review can leave
behind a pile of disposable screenshots very quickly. If the skill creates
artifacts to reason about the UI, it should also leave the workspace tidy when
those artifacts are no longer needed.

6. Stronger output requirements

The local version is stricter about what the exploration should produce.

It does not stop at "I clicked around and it looked fine". It asks for:

the user interactions that were performed
the relevant UI elements and likely locators
the expected outcomes for each flow
a concise summary of findings
proposed test cases based on the exploration

That output maps much more cleanly to a future Playwright test file.

Where this fits

This post is intentionally about the skill itself.

If you want the wider workflow around it, including how I use it to explore a
risky journey, compare it with codegen, and turn the findings into a real test,
that is in Playwright E2E testing AI skills: JavaScript London talk.

That boundary is deliberate. The skill helps you explore a real browser session
and capture candidate flows, locators, and outcomes. The Playwright test is
still the final artifact.

Building a tag system in Astro

Roger Rajaratnam — Tue, 21 Apr 2026 11:02:24 +0000

Original post: Building a tag system in Astro

Series: Part of How this blog was built — documenting every decision that shaped this site.

Tags do more than connect related posts. They create a second navigation system.
On this site the same tag data powers the blog archive cloud, the dedicated
/tags overview, paginated tag archive pages, and a sidebar browser on
individual post pages.

The key constraint is consistency. If each surface counts tags differently,
builds URLs differently, or decides for itself which posts are visible, the
whole system drifts. The implementation here stays simple by sharing two rules
everywhere: one slug helper and one publication filter.

A later update added per-tag descriptions, a featured post highlight, related
topics, and a stats bar, all covered in the second half of this post.

Diagram fallback for Dev.to. View the canonical article for the original SVG: https://sourcier.uk/blog/tag-system-astro

Slug normalisation

Every tag is displayed as-is, but routed via a URL-safe slug. A small utility in
src/utils/tags.ts handles that conversion:

export function tagSlug(tag: string): string {
  return tag
    .toLowerCase()
    .replace(/\s+/g, "-")
    .replace(/[^a-z0-9-]/g, "");
}

That turns "web development" into "web-development", "Node.js" into
"nodejs", and "C#" into "c". It is intentionally small. A more generic
utility might transliterate Unicode or preserve special cases, but the tag
vocabulary on this site is controlled enough that a simple transform is easier
to reason about.

The important detail is reuse. The cloud component, sidebar, tags index, and tag
archive routes all import the same helper, so every link resolves to the same
path format.

Publication-aware tag counts

Counting tags is trivial. Counting the right tags is the subtle part.

This site does not let each tag surface invent its own visibility rules. It
filters posts through the shared publication helper and only then derives tag
counts:

import { isPublished } from "../utils/drafts";

const allPosts = (await getCollection("posts")).filter(isPublished);

const tagCounts = new Map<string, number>();
for (const post of allPosts) {
  for (const tag of post.data.tags) {
    tagCounts.set(tag, (tagCounts.get(tag) ?? 0) + 1);
  }
}

That matters because isPublished() hides both drafts and future-dated posts
unless SHOW_DRAFTS=true. The weighted cloud, ring layout, tag archives, and
sidebar all stay in sync with the rest of the site because they start from the
same filtered set.

Right now the counting logic is repeated across several files. That is still a
good trade-off: the logic is tiny and the behaviour stays obvious. If the rules
become more complex later, extracting a shared getTagCounts() helper would be
the next clean-up step.

The weighted cloud on the blog archive

The weighted cloud lives on the blog archive: /blog and the paginated
/blog/page/[page] pages both render the same component.

---
import BlogTagCloud from "../../components/BlogTagCloud.astro";
// ...
---

<BlogTagCloud />

Inside BlogTagCloud.astro, counts are converted into three visual tiers:

function tier(count: number): number {
  if (maxCount === minCount) return 2;
  const ratio = (count - minCount) / (maxCount - minCount);
  if (ratio >= 0.66) return 3;
  if (ratio >= 0.33) return 2;
  return 1;
}

Those tiers map to modifier classes such as
tag-cloud__pill--tier-1, tag-cloud__pill--tier-2, and
tag-cloud__pill--tier-3. A stepped system is deliberate here. Continuous
scaling works well on the more expressive /tags page, but in a compact cloud
of pill links it creates visual noise faster than it adds meaning.

Each pill also includes a small count badge, so someone hovering or scanning the
cloud sees both the qualitative weight and the exact number. An "All topics"
link pushes people from the compact archive cloud into the more detailed /tags
overview.

The concentric ring layout on `/tags`

The /tags page is the more exploratory view. It combines two separate signals:

Font size scales continuously with tag frequency.
Tags are placed on concentric rings, with the most common topic in the centre and less common topics pushed outward.

The scaling and ring layout are both calculated at build time in the page
frontmatter:

const MIN_REM = 1.1;
const MAX_REM = 4;

function scale(count: number): number {
  if (maxCount === minCount) return (MIN_REM + MAX_REM) / 2;
  return (
    MIN_REM + ((count - minCount) / (maxCount - minCount)) * (MAX_REM - MIN_REM)
  );
}

const ringConfig = [
  { radiusPct: 0, max: 1, startDeg: 0 },
  { radiusPct: 18, max: 4, startDeg: -90 },
  { radiusPct: 35, max: 7, startDeg: -50 },
  { radiusPct: 48, max: 12, startDeg: 10 },
];

After sorting tags by count descending, the page fills the rings from the inside
out and converts each ring slot into percentage coordinates:

const angleDeg = radiusPct === 0 ? 0 : startDeg + (360 * i) / items.length;
const rad = (angleDeg * Math.PI) / 180;
const x = radiusPct === 0 ? 50 : 50 + radiusPct * Math.cos(rad);
const y = radiusPct === 0 ? 50 : 50 + radiusPct * Math.sin(rad);

That produces an SVG-like layout without SVG. Each tag is still a normal anchor,
just absolutely positioned inside a relative container.

The accessibility model matters here too. The circular cloud is decorative and
marked aria-hidden, while a plain list remains in the accessibility tree and
is also the visual fallback on small screens. The fallback list is shuffled with
a seeded function so it does not read as a rigid alphabetical index, but it
stays deterministic across builds.

Tag archive pages

Each topic gets a clean first-page URL at /tags/[tag] and subsequent archive
pages at /tags/[tag]/2, /tags/[tag]/3, and so on.

Rather than using Astro's paginate() helper, the current implementation keeps
two route files:

src/pages/tags/[tag]/index.astro handles page 1.
src/pages/tags/[tag]/[page].astro emits pages 2 and above.

The second file builds its paths manually:

export async function getStaticPaths() {
  const PAGE_SIZE = 9;
  const allPosts = (await getCollection("posts")).filter(isPublished);
  const tagMap = new Map<string, typeof allPosts>();

  for (const post of allPosts) {
    for (const tag of post.data.tags) {
      const slug = tagSlug(tag);
      if (!tagMap.has(slug)) tagMap.set(slug, []);
      tagMap.get(slug)!.push(post);
    }
  }

  const paths: object[] = [];
  for (const [slug, posts] of tagMap.entries()) {
    const totalPages = Math.ceil(posts.length / PAGE_SIZE);
    const label = posts[0].data.tags.find((t) => tagSlug(t) === slug) ?? slug;

    for (let pageNum = 2; pageNum <= totalPages; pageNum++) {
      paths.push({
        params: { tag: slug, page: String(pageNum) },
        props: { label },
      });
    }
  }

  return paths;
}

Routes use slugs, but page heroes should still display the human-readable tag
text. Looking up the original label from the first matching post preserves
spaces and casing without a separate lookup table.

Both route files sort posts newest first and share the same PAGE_SIZE = 9, so
pagination behaves consistently across every topic.

The sidebar browser

TagsSidebar.astro is the compact version of the same system. It keeps the same
counting and sorting pattern, but renders a simple vertical list with count
badges rather than a cloud:

const tags = [...tagCounts.entries()]
  .sort(([, a], [, b]) => b - a)
  .map(([tag, count]) => ({ tag, count, slug: tagSlug(tag) }));

The sidebar only matters because the post layout mounts it alongside the table
of contents and share controls:

import TagsSidebar from "../components/TagsSidebar.astro";

<aside class="post__sidebar" aria-label="Post sidebar">
  {/* other sidebar blocks */}
  <TagsSidebar />
</aside>

That keeps topic browsing available even when someone lands deep on an
individual article. The UI copy uses "topics" in the reader-facing labels, but
the routes stay under /tags, which keeps the underlying implementation short
and stable.

Pulling the system together

The interesting part of this tag system is not any single surface. It is the
fact that every surface starts from the same visible post set and uses the same
slug transform. Once those two rules are stable, the same dataset can show up as
weighted pills, a ring cloud, paginated archives, or a sidebar list without the
site disagreeing with itself.

Added 23 April 2026

Improving the tag pages

A comment from Fyodor after this post was first published put it directly:

Now try to add description to each tag so that a tag page wouldn't look that generically bland, huh?

Fair point. I went ahead and added four improvements to address exactly that.

Tag descriptions

A tagDescriptions map in src/utils/tags.ts keys a short description to
each tag slug:

export const tagDescriptions: Record<string, string> = {
  astro: "Everything about building with Astro: content collections, islands architecture, SSG, and the surrounding ecosystem.",
  engineering: "Software engineering practice — architecture, trade-offs, and the thinking behind building things well.",
  // ...
};

The full map covering all current tags is in the code listings at the end of this post.

The tag archive page reads the current slug and falls back gracefully if no
description exists:

const description = tagDescriptions[tag];

That value then drives the <meta> description, the hero subtitle, and the
panel copy. One source, three uses. New tags that lack an entry get the old
generic fallback, so nothing breaks.

Featured post highlight

The most recent post was buried in the grid with no visual prominence. The fix
pulls it out entirely and renders it as a full-width two-column card above
the grid:

const featuredPost = allTagPosts[0];
const remainingPosts = allTagPosts.slice(1);
const totalPages = Math.ceil(remainingPosts.length / PAGE_SIZE);
const posts = remainingPosts.slice(0, PAGE_SIZE);

The featured card shows the cover image on the left at desktop size with the
title, description, and a read CTA on the right. totalPages is derived from
remainingPosts, not allTagPosts, so pagination stays honest.

Stats bar

Inside the topic overview panel, a <dl> shows three facts: post count,
average reading time per post, and total reading time across the whole archive.

const totalWords = allTagPosts.reduce(
  (acc, p) => acc + (p.body ? readingTime(p.body).words : 0),
  0,
);
const totalReadMinutes = Math.ceil(totalWords / 200);
const avgReadMinutes = allTagPosts.length > 0
  ? Math.round(totalReadMinutes / allTagPosts.length)
  : 0;

The 200 wpm divisor is deliberately conservative: it errs on the side of
not under-promising. The stat gives a quick sense of how deep the archive goes
before committing to reading any of it.

Beyond the foundations

All four improvements build on the same two rules without touching them. The slug helper
and publication filter stay unchanged. What changes is only what each tag page
does with the data once it has it.

That is a useful sign. When enhancements layer on top without revisiting the
core logic, the foundation was right.

Full code listings

If you want to inspect the finished implementation end to end, expand the
listings below. These are the complete files that make up the tag system
itself. The shared publication helper lives in src/utils/drafts.ts and is
reused across the rest of the site too.

src/utils/tags.ts

export function tagSlug(tag: string): string {
  return tag
    .toLowerCase()
    .replace(/\s+/g, "-")
    .replace(/[^a-z0-9-]/g, "");
}

export const tagDescriptions: Record = {
  analytics: "Tracking, measuring, and making sense of how people use the web — from basic page views to real user metrics.",
  astro: "Everything about building with Astro: content collections, islands architecture, SSG, and the surrounding ecosystem.",
  automation: "Scripts, workflows, and tooling that take the repetitive work off your plate.",
  blogging: "The craft and mechanics of running a blog — structure, workflow, tooling, and keeping the writing habit going.",
  devto: "Cross-posting to DEV.to, syndication strategies, and making the most of the platform.",
  dotfiles: "Shell configs, editor settings, and the art of making a new machine feel like home.",
  engineering: "Software engineering practice — architecture, trade-offs, and the thinking behind building things well.",
  frontend: "HTML, CSS, JavaScript, and everything that shapes what users actually see and interact with.",
  "learning-in-public": "Writing and sharing while you're still figuring things out — the messy, honest, valuable kind.",
  meta: "Posts about the blog itself: how it was built, why decisions were made, and what's changed.",
  netlify: "Deploying, hosting, and extending sites with Netlify — functions, forms, edge, and scheduled builds.",
  tooling: "Developer tools that sharpen the workflow: linters, formatters, bundlers, and the rest.",
  tutorial: "Step-by-step guides with working code, aimed at getting you from zero to done.",
  "web-development": "The broader practice of building for the web — spanning frontend, backend, and everything in between.",
  writing: "Reflections on writing itself: finding a voice, staying consistent, and communicating clearly.",
};

src/components/BlogTagCloud.astro

---
import { getCollection } from "astro:content";
import { isPublished } from "../utils/drafts";
import { tagSlug } from "../utils/tags";

const allPosts = (await getCollection("posts")).filter(isPublished);

const tagCounts = new Map();
for (const post of allPosts) {
  for (const tag of post.data.tags) {
    tagCounts.set(tag, (tagCounts.get(tag) ?? 0) + 1);
  }
}

const counts = [...tagCounts.values()];
const minCount = Math.min(...counts);
const maxCount = Math.max(...counts);

function tier(count: number): number {
  if (maxCount === minCount) return 2;
  const ratio = (count - minCount) / (maxCount - minCount);
  if (ratio &gt;= 0.66) return 3;
  if (ratio &gt;= 0.33) return 2;
  return 1;
}

const tags = [...tagCounts.entries()]
  .sort(([, a], [, b]) =&gt; b - a)
  .map(([tag, count]) =&gt; ({
    tag,
    count,
    slug: tagSlug(tag),
    tier: tier(count),
  }));
---






          <p>Topics</p>
          <h2 id="tag-cloud-heading">
            Browse by topic
          </h2>
          <p>
            Jump straight into the subjects you care about without paging
            through the full archive first.
          </p>

        <a href="/tags">
          All topics →
        </a>

      <ul>
        {
          tags.map(({ tag, count, slug, tier }) =&gt; (
            <li>
              <a href="{`/tags/${slug}`}">
                {tag}
                <span>
                  {count}
                </span>
              </a>
            </li>
          ))
        }
      </ul>





  .tag-cloud {
    padding: 0 1.5rem;
  }

  .tag-cloud__panel {
    position: relative;
    overflow: hidden;
    padding: clamp(1.75rem, 3.5vw, 2.35rem);
    background:
      radial-gradient(
        circle at top right,
        color-mix(in srgb, var(--accent-secondary) 14%, transparent) 0%,
        transparent 34%
      ),
      radial-gradient(
        circle at left bottom,
        var(--accent-primary-alpha-08) 0%,
        transparent 30%
      ),
      linear-gradient(
        145deg,
        color-mix(
          in srgb,
          var(--surface-page) 88%,
          var(--accent-secondary) 12%
        ),
        var(--surface-elevated)
      );
  }

  .tag-cloud__header {
    display: flex;
    align-items: flex-start;
    justify-content: space-between;
    margin-bottom: 1.75rem;
    gap: 1rem;

    @media (max-width: 639px) {
      flex-direction: column;
      align-items: flex-start;
    }
  }

  .tag-cloud__intro {
    min-width: 0;
  }

  .tag-cloud__title {
    margin: 0;
    font-family: "Barlow Condensed", sans-serif;
    font-size: clamp(1.8rem, 4vw, 2.5rem);
    line-height: 1.05;
    text-transform: uppercase;
    color: var(--text-primary);
  }

  .tag-cloud__description {
    margin: 0.5rem 0 0;
    max-width: 48ch;
    line-height: 1.65;
    color: var(--text-muted);
  }

  .tag-cloud__all-link {
    display: inline-flex;
    align-items: center;
    justify-content: center;
    min-height: 2.85rem;
    padding: 0.75rem 1.05rem;
    border: 1px solid
      color-mix(in srgb, var(--accent-secondary) 20%, transparent);
    border-radius: var(--radius-pill);
    background: color-mix(
      in srgb,
      var(--accent-secondary) 9%,
      var(--surface-elevated)
    );
    font-family: "Barlow Condensed", sans-serif;
    font-size: 0.75rem;
    font-weight: 700;
    text-transform: uppercase;
    letter-spacing: 0.08em;
    color: var(--text-muted);
    text-decoration: none;
    transition:
      color 0.15s ease,
      border-color 0.15s ease,
      transform 0.15s ease;

    &amp;:hover {
      color: var(--accent-secondary);
      border-color: var(--accent-secondary-alpha-28);
      transform: translateY(-1px);
    }

    @media (min-width: 640px) {
      align-self: center;
    }
  }

  .tag-cloud__list {
    list-style: none;
    margin: 0;
    padding: 0;
    display: flex;
    flex-wrap: wrap;
    gap: 0.75rem;
    align-items: center;
  }

  .tag-cloud__pill {
    display: inline-flex;
    align-items: center;
    gap: 0.4rem;
    text-decoration: none;
    font-family: "Barlow Condensed", sans-serif;
    font-weight: 700;
    text-transform: uppercase;
    letter-spacing: 0.06em;
    border: 1.5px solid var(--border-subtle);
    border-radius: var(--radius-pill);
    color: var(--text-muted);
    background-color: color-mix(
      in srgb,
      var(--surface-elevated) 78%,
      transparent
    );
    box-shadow: inset 0 1px 0 var(--text-on-strong-alpha-45);
    transition:
      color 0.15s ease,
      border-color 0.15s ease,
      background-color 0.15s ease,
      transform 0.15s ease;

    &amp;:hover {
      color: var(--accent-secondary);
      border-color: var(--accent-secondary-alpha-26);
      background-color: color-mix(
        in srgb,
        var(--accent-secondary) 9%,
        var(--surface-elevated)
      );
      transform: translateY(-1px);
    }

    &amp;--tier-1 {
      font-size: 0.74rem;
      padding: 0.3rem 0.6rem;
    }

    &amp;--tier-2 {
      font-size: 0.9rem;
      padding: 0.35rem 0.72rem;
    }

    &amp;--tier-3 {
      font-size: 1.04rem;
      padding: 0.42rem 0.82rem;
      border-width: 2px;
      color: var(--text-primary);
      border-color: var(--accent-secondary-alpha-18);
    }
  }

  .tag-cloud__count {
    font-size: 0.65em;
    font-weight: 700;
    color: var(--accent-secondary);
    background-color: color-mix(
      in srgb,
      var(--accent-secondary) 12%,
      transparent
    );
    padding: 0.05rem 0.35rem;
    border-radius: var(--radius-pill);
    transition:
      background-color 0.15s ease,
      color 0.15s ease;

    .tag-cloud__pill:hover &amp; {
      background-color: var(--accent-secondary-alpha-16);
      color: var(--accent-secondary);
    }
  }

src/components/TagsSidebar.astro

---
import { getCollection } from "astro:content";
import { isPublished } from "../utils/drafts";
import { tagSlug } from "../utils/tags";

const allPosts = (await getCollection("posts")).filter(isPublished);

const tagCounts = new Map();
for (const post of allPosts) {
  for (const tag of post.data.tags) {
    tagCounts.set(tag, (tagCounts.get(tag) ?? 0) + 1);
  }
}

const tags = [...tagCounts.entries()]
  .sort(([, a], [, b]) =&gt; b - a)
  .map(([tag, count]) =&gt; ({ tag, count, slug: tagSlug(tag) }));
---


  <p id="tags-sidebar-heading">Browse topics</p>
  <ul>
    {
      tags.map(({ tag, count, slug }) =&gt; (
        <li>
          <a href="{`/tags/${slug}`}">
            <span>{tag}</span>
            <span>
              {count}
            </span>
          </a>
        </li>
      ))
    }
  </ul>
  <a href="/tags">All tags →</a>



  .tags-sidebar {
    margin-top: 2rem;
    margin-bottom: 2rem;
  }

  .tags-sidebar__heading {
    font-family: "Barlow Condensed", sans-serif;
    font-size: 0.75rem;
    font-weight: 700;
    text-transform: uppercase;
    letter-spacing: 0.1em;
    color: var(--accent-primary);
    padding-top: 0.75rem;
    border-top: 2px solid var(--accent-primary);
    margin-bottom: 0.75rem;
  }

  .tags-sidebar__list {
    list-style: none;
    margin: 0;
    padding: 0;
    display: flex;
    flex-direction: column;
    gap: 0;
  }

  .tags-sidebar__tag {
    display: flex;
    align-items: center;
    justify-content: space-between;
    gap: 0.5rem;
    padding: 0.45rem 0;
    border-bottom: 1px solid var(--border-subtle);
    text-decoration: none;
    color: var(--text-muted);
    transition:
      color 0.15s ease,
      padding-left 0.15s ease;

    &amp;:hover {
      color: var(--accent-primary);
      padding-left: 0.35rem;
    }
  }

  .tags-sidebar__name {
    font-family: "Barlow Condensed", sans-serif;
    font-size: 0.875rem;
    font-weight: 700;
    text-transform: uppercase;
    letter-spacing: 0.06em;
  }

  .tags-sidebar__count {
    font-family: "Barlow Condensed", sans-serif;
    font-size: 0.7rem;
    font-weight: 700;
    color: var(--text-muted);
    background-color: var(--border-subtle);
    border-radius: var(--radius-tight);
    padding: 0.1rem 0.4rem;
    min-width: 1.4rem;
    text-align: center;
    transition:
      background-color 0.15s ease,
      color 0.15s ease;

    .tags-sidebar__tag:hover &amp; {
      background-color: rgba(var(--accent-primary-rgb), 0.12);
      color: var(--accent-primary);
    }
  }

  .tags-sidebar__all {
    display: block;
    margin-top: 1rem;
    font-family: "Barlow Condensed", sans-serif;
    font-size: 0.75rem;
    font-weight: 700;
    text-transform: uppercase;
    letter-spacing: 0.1em;
    color: var(--text-muted);
    text-decoration: none;
    transition: color 0.15s ease;

    &amp;:hover {
      color: var(--accent-primary);
    }
  }

src/pages/tags/index.astro

---
import { getCollection } from "astro:content";
import { isPublished } from "../../utils/drafts";
import BaseLayout from "../../layouts/BaseLayout.astro";
import PageHero from "../../components/PageHero.astro";
import MailingListCTA from "../../components/MailingListCTA.astro";
import { tagSlug } from "../../utils/tags";

const allPosts = (await getCollection("posts")).filter(isPublished);

const tagCounts = new Map();
for (const post of allPosts) {
  for (const tag of post.data.tags) {
    tagCounts.set(tag, (tagCounts.get(tag) ?? 0) + 1);
  }
}

const counts = [...tagCounts.values()];
const minCount = Math.min(...counts);
const maxCount = Math.max(...counts);

const MIN_REM = 1.1;
const MAX_REM = 4;

function scale(count: number): number {
  if (maxCount === minCount) return (MIN_REM + MAX_REM) / 2;
  return (
    MIN_REM + ((count - minCount) / (maxCount - minCount)) * (MAX_REM - MIN_REM)
  );
}

const sorted = [...tagCounts.entries()]
  .sort(([, a], [, b]) =&gt; b - a)
  .map(([tag, count]) =&gt; ({
    tag,
    count,
    slug: tagSlug(tag),
    fontSize: scale(count),
  }));

const ringConfig = [
  { radiusPct: 0, max: 1, startDeg: 0 },
  { radiusPct: 18, max: 4, startDeg: -90 },
  { radiusPct: 35, max: 7, startDeg: -50 },
  { radiusPct: 48, max: 12, startDeg: 10 },
];

type TagPos = {
  tag: string;
  count: number;
  slug: string;
  fontSize: number;
  x: number;
  y: number;
  ringIdx: number;
};

const positioned: TagPos[] = [];
let si = 0;

for (let ringIdx = 0; ringIdx &lt; ringConfig.length; ringIdx++) {
  if (si &gt;= sorted.length) break;
  const { radiusPct, max, startDeg } = ringConfig[ringIdx];
  const items = sorted.slice(si, si + max);
  si += items.length;
  items.forEach((item, i) =&gt; {
    const angleDeg = radiusPct === 0 ? 0 : startDeg + (360 * i) / items.length;
    const rad = (angleDeg * Math.PI) / 180;
    const x = radiusPct === 0 ? 50 : 50 + radiusPct * Math.cos(rad);
    const y = radiusPct === 0 ? 50 : 50 + radiusPct * Math.sin(rad);
    positioned.push({ ...item, x, y, ringIdx });
  });
}

function seededShuffle(arr: T[]): T[] {
  const out = [...arr];
  let seed = 42;
  const rand = () =&gt; {
    seed = (seed * 1664525 + 1013904223) &amp; 0xffffffff;
    return (seed &gt;&gt;&gt; 0) / 0xffffffff;
  };
  for (let i = out.length - 1; i &gt; 0; i--) {
    const j = Math.floor(rand() * (i + 1));
    [out[i], out[j]] = [out[j], out[i]];
  }
  return out;
}

const shuffled = seededShuffle(sorted);
const totalTags = sorted.length;
const totalPosts = allPosts.length;

const ringStyle = (ringIdx: number) =&gt; {
  if (ringIdx === 0) return "color: var(--accent-primary); opacity: 1";
  if (ringIdx === 1) return "opacity: 1";
  if (ringIdx === 2) return "opacity: 0.85";
  return "opacity: 0.7";
};
---








          <p>Topic map</p>
          <h2 id="tag-summary-heading">
            Explore the writing by theme
          </h2>
          <p>
            Jump straight into the ideas that show up most often across the
            blog, or skim the full map below if you want to browse more broadly.
          </p>

        <ul>
          <li>
            <span>Published</span>
            <span>{totalPosts}</span>
          </li>
          <li>
            <span>Topics</span>
            <span>{totalTags}</span>
          </li>
        </ul>








          <p>
            Each topic links to a collection of related posts. Larger tags mean
            I write about that area more often, so the subjects I return to most
            sit closer to the centre.
          </p>

            <span>fewer posts</span>
            <span>→</span>
            <span>more posts</span>





            {
              positioned.map(({ tag, slug, fontSize, x, y, ringIdx }) =&gt; (
                <a href="{`/tags/${slug}`}">
                  {tag}
                </a>
              ))
            }



        <ul>
          {
            shuffled.map(({ tag, count, slug, fontSize }) =&gt; (
              <li>
                <a href="{`/tags/${slug}`}">
                  {tag}
                </a>
              </li>
            ))
          }
        </ul>








  .tag-summary {
    padding: 0 1.5rem;
  }

  .tag-summary__panel {
    display: grid;
    gap: 1.25rem;
    border-top-color: var(--accent-secondary);
    background:
      radial-gradient(
        circle at top right,
        color-mix(in srgb, var(--accent-secondary) 14%, transparent) 0%,
        transparent 34%
      ),
      linear-gradient(
        150deg,
        color-mix(in srgb, var(--accent-secondary) 8%, var(--surface-elevated))
          0%,
        var(--surface-elevated) 62%
      ),
      var(--surface-elevated);

    @media (min-width: 768px) {
      grid-template-columns: minmax(0, 1.5fr) auto;
      gap: 2rem;
      align-items: center;
    }
  }

  .tag-summary__eyebrow {
    margin: 0 0 0.65rem;
    font-family: "Barlow Condensed", sans-serif;
    font-size: 0.8rem;
    font-weight: 700;
    letter-spacing: 0.1em;
    text-transform: uppercase;
    color: var(--accent-secondary);
  }

  .tag-summary__title {
    margin: 0;
    font-family: "Barlow Condensed", sans-serif;
    font-size: clamp(2rem, 4vw, 2.8rem);
    line-height: 0.98;
    text-transform: uppercase;
    color: var(--text-primary);
  }

  .tag-summary__text {
    margin: 0.85rem 0 0;
    max-width: 58ch;
    line-height: 1.7;
    color: var(--text-muted);
  }

  .tag-summary__stats {
    list-style: none;
    margin: 0;
    padding: 0;
    display: grid;
    gap: 0.75rem;
  }

  .tag-summary__stat {
    display: grid;
    gap: 0.35rem;
    min-width: 9rem;
    padding: 1rem 1.1rem;
    border: 1px solid var(--accent-secondary-alpha-16);
    border-radius: var(--radius-soft);
    background: color-mix(
      in srgb,
      var(--accent-secondary) 8%,
      var(--surface-elevated)
    );
  }

  .tag-summary__label {
    font-size: 0.72rem;
    font-weight: 700;
    letter-spacing: 0.12em;
    text-transform: uppercase;
    color: var(--text-muted);
  }

  .tag-summary__value {
    font-family: "Barlow Condensed", sans-serif;
    font-size: clamp(1.55rem, 4vw, 2.1rem);
    font-weight: 800;
    line-height: 1;
    text-transform: uppercase;
    color: var(--text-primary);
  }

  .cloud-section {
    padding-top: 0;
    padding-bottom: 0;
  }

  .cloud-surface {
    overflow: hidden;
    padding: clamp(1.5rem, 3vw, 2rem);
    background:
      radial-gradient(
        circle at top right,
        color-mix(in srgb, var(--accent-secondary) 10%, transparent) 0%,
        transparent 34%
      ),
      linear-gradient(
        150deg,
        color-mix(in srgb, var(--accent-primary) 3%, var(--surface-elevated)) 0%,
        var(--surface-elevated) 66%
      ),
      var(--surface-elevated);
  }

  .cloud-intro {
    display: flex;
    flex-direction: column;
    gap: 1.5rem;
    margin-bottom: 2.5rem;
    padding-bottom: 2rem;
    border-bottom: 1px solid var(--border-subtle);

    @media (min-width: 768px) {
      flex-direction: row;
      align-items: flex-start;
      justify-content: space-between;
      gap: 4rem;
    }
  }

  .cloud-intro__text {
    margin: 0;
    font-size: 1rem;
    line-height: 1.75;
    color: var(--text-muted);
    max-width: 52ch;
  }

  .cloud-legend {
    flex-shrink: 0;
    display: flex;
    align-items: center;
    gap: 1rem;
  }

  .cloud-legend__arrow {
    color: var(--accent-secondary);
    font-size: 1.25rem;
  }

  .cloud-legend__example {
    font-family: "Barlow Condensed", sans-serif;
    font-weight: 700;
    text-transform: uppercase;
    letter-spacing: 0.05em;
    color: var(--text-primary);
  }

  .cloud-legend__example--sm {
    font-size: 0.875rem;
    opacity: 0.45;
  }

  .cloud-legend__example--lg {
    font-size: 2rem;
    color: var(--accent-secondary);
  }

  .cloud-circle-wrap {
    display: none;
    justify-content: center;
    margin: 0.5rem 0 2rem;

    @media (min-width: 640px) {
      display: flex;
    }
  }

  .cloud-circle {
    position: relative;
    width: min(88vw, 580px);
    aspect-ratio: 1;

    &amp;::before {
      content: "";
      position: absolute;
      inset: 0;
      border-radius: 50%;
      border: 1px solid var(--border-subtle);
      pointer-events: none;
    }

    &amp;::after {
      content: "";
      position: absolute;
      inset: 22%;
      border-radius: 50%;
      border: 1px dashed var(--accent-secondary-alpha-18);
      pointer-events: none;
    }
  }

  .cloud-circle__tag {
    position: absolute;
    transform: translate(-50%, -50%) scale(1);
    font-family: "Barlow Condensed", sans-serif;
    font-weight: 700;
    text-transform: uppercase;
    letter-spacing: 0.04em;
    text-decoration: none;
    color: var(--text-primary);
    white-space: nowrap;
    transition:
      color 0.2s ease,
      opacity 0.2s ease,
      transform 0.2s cubic-bezier(0.34, 1.56, 0.64, 1);

    &amp;:hover {
      color: var(--accent-secondary) !important;
      opacity: 1 !important;
      transform: translate(-50%, -50%) scale(1.18);
      z-index: 1;
    }
  }

  .cloud-circle:has(.cloud-circle__tag:hover) .cloud-circle__tag:not(:hover) {
    opacity: 0.15 !important;
    transform: translate(-50%, -50%) scale(0.95);
  }

  .cloud-list {
    display: flex;
    flex-wrap: wrap;
    justify-content: center;
    align-items: center;
    gap: 0.75rem 1.5rem;
    list-style: none;
    margin: 1rem 0;
    padding: 0;

    @media (min-width: 640px) {
      position: absolute;
      width: 1px;
      height: 1px;
      overflow: hidden;
      clip: rect(0 0 0 0);
      white-space: nowrap;
    }
  }

  .cloud-list__tag {
    font-family: "Barlow Condensed", sans-serif;
    font-weight: 700;
    text-transform: uppercase;
    letter-spacing: 0.04em;
    color: var(--text-primary);
    text-decoration: none;
    opacity: 0.75;
    white-space: nowrap;
    transition:
      color 0.15s ease,
      opacity 0.15s ease;

    &amp;:hover {
      color: var(--accent-secondary);
      opacity: 1;
    }
  }

src/pages/tags/[tag]/index.astro

---
import { getCollection } from "astro:content";
import { isPublished } from "../../../utils/drafts";
import BaseLayout from "../../../layouts/BaseLayout.astro";
import PageHero from "../../../components/PageHero.astro";
import BlogGrid from "../../../components/BlogGrid.astro";
import MailingListCTA from "../../../components/MailingListCTA.astro";
import { tagSlug } from "../../../utils/tags";

export async function getStaticPaths() {
  const allPosts = (await getCollection("posts")).filter(isPublished);
  const tagMap = new Map();
  for (const post of allPosts) {
    for (const tag of post.data.tags) {
      const slug = tagSlug(tag);
      if (!tagMap.has(slug)) tagMap.set(slug, []);
      tagMap.get(slug)!.push(post);
    }
  }
  return [...tagMap.entries()].map(([slug, posts]) =&gt; {
    const label = posts[0].data.tags.find((t) =&gt; tagSlug(t) === slug) ?? slug;
    return { params: { tag: slug }, props: { label } };
  });
}

const PAGE_SIZE = 9;
const { tag } = Astro.params;
const { label } = Astro.props;

const allTagPosts = (await getCollection("posts"))
  .filter(
    (post) =&gt;
      isPublished(post) &amp;&amp; post.data.tags.some((t) =&gt; tagSlug(t) === tag),
  )
  .sort((a, b) =&gt; b.data.pubDate.valueOf() - a.data.pubDate.valueOf());

const totalPages = Math.ceil(allTagPosts.length / PAGE_SIZE);
const posts = allTagPosts.slice(0, PAGE_SIZE);
const nextUrl = totalPages &gt; 1 ? `/tags/${tag}/2` : null;
const postCountLabel =
  allTagPosts.length === 1 ? "1 post" : `${allTagPosts.length} posts`;
---








          <p>Topic archive</p>
          <h2 id="topic-overview-heading">
            {postCountLabel} about {label}
          </h2>
          <p>
            This archive keeps every article filed under this topic in one
            place, newest first, so you can stay with one theme without jumping
            around the rest of the site.
          </p>


          <a href="/tags">All topics</a>
          <a href="/blog">
            Latest writing
          </a>





   1 ? `, across ${totalPages} pages.` : "."}`}
  /&gt;





  .topic-overview {
    padding: 0 1.5rem;
  }

  .topic-overview__panel {
    display: grid;
    gap: 1.25rem;
    border-top-color: var(--accent-secondary);
    background:
      radial-gradient(
        circle at top right,
        color-mix(in srgb, var(--accent-secondary) 14%, transparent) 0%,
        transparent 34%
      ),
      linear-gradient(
        150deg,
        color-mix(in srgb, var(--accent-secondary) 8%, var(--surface-elevated))
          0%,
        var(--surface-elevated) 62%
      ),
      var(--surface-elevated);

    @media (min-width: 768px) {
      grid-template-columns: minmax(0, 1.45fr) auto;
      gap: 2rem;
      align-items: center;
    }
  }

  .topic-overview__eyebrow {
    margin: 0 0 0.65rem;
    font-family: "Barlow Condensed", sans-serif;
    font-size: 0.8rem;
    font-weight: 700;
    letter-spacing: 0.1em;
    text-transform: uppercase;
    color: var(--accent-secondary);
  }

  .topic-overview__title {
    margin: 0;
    font-family: "Barlow Condensed", sans-serif;
    font-size: clamp(1.9rem, 4vw, 2.7rem);
    line-height: 0.98;
    text-transform: uppercase;
    color: var(--text-primary);
  }

  .topic-overview__text {
    margin: 0.85rem 0 0;
    max-width: 58ch;
    line-height: 1.7;
    color: var(--text-muted);
  }

  .topic-overview__actions {
    display: flex;
    flex-wrap: wrap;
    gap: 0.75rem;
  }

  .topic-overview__link {
    display: inline-flex;
    align-items: center;
    justify-content: center;
    min-height: 2.85rem;
    padding: 0.7rem 1rem;
    border: 1px solid var(--accent-secondary-alpha-18);
    border-radius: var(--radius-pill);
    background: color-mix(
      in srgb,
      var(--accent-secondary) 8%,
      var(--surface-elevated)
    );
    font-family: "Barlow Condensed", sans-serif;
    font-size: 0.85rem;
    font-weight: 700;
    letter-spacing: 0.08em;
    text-transform: uppercase;
    color: var(--accent-secondary);
    text-decoration: none;
    transition:
      border-color 0.15s ease,
      transform 0.15s ease;

    &amp;:hover {
      border-color: var(--accent-secondary-alpha-32);
      transform: translateY(-1px);
    }
  }

  .topic-overview__link--secondary {
    border-color: var(--accent-primary-alpha-22);
    background: color-mix(
      in srgb,
      var(--accent-primary) 8%,
      var(--surface-elevated)
    );
    color: var(--accent-primary);
  }

src/pages/tags/[tag]/[page].astro

---
import { getCollection } from "astro:content";
import { isPublished } from "../../../utils/drafts";
import BaseLayout from "../../../layouts/BaseLayout.astro";
import PageHero from "../../../components/PageHero.astro";
import BlogGrid from "../../../components/BlogGrid.astro";
import MailingListCTA from "../../../components/MailingListCTA.astro";
import { tagSlug } from "../../../utils/tags";

export async function getStaticPaths() {
  const PAGE_SIZE = 9;
  const allPosts = (await getCollection("posts")).filter(isPublished);
  const tagMap = new Map();
  for (const post of allPosts) {
    for (const tag of post.data.tags) {
      const slug = tagSlug(tag);
      if (!tagMap.has(slug)) tagMap.set(slug, []);
      tagMap.get(slug)!.push(post);
    }
  }
  const paths: object[] = [];
  for (const [slug, posts] of tagMap.entries()) {
    const totalPages = Math.ceil(posts.length / PAGE_SIZE);
    const label = posts[0].data.tags.find((t) =&gt; tagSlug(t) === slug) ?? slug;
    for (let pageNum = 2; pageNum &lt;= totalPages; pageNum++) {
      paths.push({
        params: { tag: slug, page: String(pageNum) },
        props: { label },
      });
    }
  }
  return paths;
}

const PAGE_SIZE = 9;
const { tag, page } = Astro.params;
const { label } = Astro.props;
const currentPage = Number(page);

const allTagPosts = (await getCollection("posts"))
  .filter(
    (post) =&gt;
      isPublished(post) &amp;&amp; post.data.tags.some((t) =&gt; tagSlug(t) === tag),
  )
  .sort((a, b) =&gt; b.data.pubDate.valueOf() - a.data.pubDate.valueOf());

const totalPages = Math.ceil(allTagPosts.length / PAGE_SIZE);
const posts = allTagPosts.slice(
  (currentPage - 1) * PAGE_SIZE,
  currentPage * PAGE_SIZE,
);
const prevUrl =
  currentPage === 2 ? `/tags/${tag}` : `/tags/${tag}/${currentPage - 1}`;
const nextUrl =
  currentPage &lt; totalPages ? `/tags/${tag}/${currentPage + 1}` : null;
const postCountLabel =
  allTagPosts.length === 1 ? "1 post" : `${allTagPosts.length} posts`;
---








          <p>Topic archive</p>
          <h2 id="topic-overview-heading">
            Page {currentPage} of {totalPages}
          </h2>
          <p>
            {postCountLabel} filed under {label}. This page keeps you inside the
            same topic while you move through older entries in the archive.
          </p>


          <a href="{`/tags/${tag}`}">
            Topic overview
          </a>
          <a href="/blog">
            Latest writing
          </a>











  .topic-overview {
    padding: 0 1.5rem;
  }

  .topic-overview__panel {
    display: grid;
    gap: 1.25rem;
    border-top-color: var(--accent-secondary);
    background:
      radial-gradient(
        circle at top right,
        color-mix(in srgb, var(--accent-secondary) 14%, transparent) 0%,
        transparent 34%
      ),
      linear-gradient(
        150deg,
        color-mix(in srgb, var(--accent-secondary) 8%, var(--surface-elevated))
          0%,
        var(--surface-elevated) 62%
      ),
      var(--surface-elevated);

    @media (min-width: 768px) {
      grid-template-columns: minmax(0, 1.45fr) auto;
      gap: 2rem;
      align-items: center;
    }
  }

  .topic-overview__eyebrow {
    margin: 0 0 0.65rem;
    font-family: "Barlow Condensed", sans-serif;
    font-size: 0.8rem;
    font-weight: 700;
    letter-spacing: 0.1em;
    text-transform: uppercase;
    color: var(--accent-secondary);
  }

  .topic-overview__title {
    margin: 0;
    font-family: "Barlow Condensed", sans-serif;
    font-size: clamp(1.9rem, 4vw, 2.7rem);
    line-height: 0.98;
    text-transform: uppercase;
    color: var(--text-primary);
  }

  .topic-overview__text {
    margin: 0.85rem 0 0;
    max-width: 58ch;
    line-height: 1.7;
    color: var(--text-muted);
  }

  .topic-overview__actions {
    display: flex;
    flex-wrap: wrap;
    gap: 0.75rem;
  }

  .topic-overview__link {
    display: inline-flex;
    align-items: center;
    justify-content: center;
    min-height: 2.85rem;
    padding: 0.7rem 1rem;
    border: 1px solid var(--accent-secondary-alpha-18);
    border-radius: var(--radius-pill);
    background: color-mix(
      in srgb,
      var(--accent-secondary) 8%,
      var(--surface-elevated)
    );
    font-family: "Barlow Condensed", sans-serif;
    font-size: 0.85rem;
    font-weight: 700;
    letter-spacing: 0.08em;
    text-transform: uppercase;
    color: var(--accent-secondary);
    text-decoration: none;
    transition:
      border-color 0.15s ease,
      transform 0.15s ease;

    &amp;:hover {
      border-color: var(--accent-secondary-alpha-32);
      transform: translateY(-1px);
    }
  }

  .topic-overview__link--secondary {
    border-color: var(--accent-primary-alpha-22);
    background: color-mix(
      in srgb,
      var(--accent-primary) 8%,
      var(--surface-elevated)
    );
    color: var(--accent-primary);
  }

You can browse the rest of the site code in the
web-sourcier.uk repository.

DEV Community: Roger Rajaratnam

Adding a mailing list to a static Astro blog with Resend

What we're building

Setting up Resend Segments

The Netlify Function

Welcome email

Creating the template with a script

The Astro component

Honeypot field

Shared form utility

Environment variables

Adding the component to pages

Sidebar variant

Dark mode theming

What Resend handles for you

Wrap-up

Scheduled publishing in Astro on Netlify

The problem with draft: false alone

isPublished() — one filter to rule them all

Setting pubDate values

The scheduled Netlify function

netlify.toml configuration

Dashboard setup

Verifying the setup

How it fits together

Where draft still fits in

What this doesn't do

Wrapping up

Working on something similar?

Sending new post notifications with Resend

Why a script rather than a build hook

Dependencies

Reading frontmatter without a build

Environment variables

The email content

Confirmation before sending

The two-step API call

Running the script

Deploying an Astro blog to Netlify

netlify.toml

Cache headers

The functions directory

Edge functions

Environment variables

Build-time variables

Runtime variables

Deploy previews and draft posts

One-time Netlify dashboard setup for comments

Wrapping up

Page history and credits on a static blog

Architecture overview

UI mockup

Page history

Credits

Why both belong in the schema

Building a share widget with the Clipboard API

The component props

LinkedIn share URL

Reddit share URL

Email share URL

Copy link with the Clipboard API

Placement in the post layout

Putting it together

Breadcrumb navigation with Schema.org markup

The component interface

Auto-generation from URL path

Schema.org BreadcrumbList

Accessibility

Full code listing

Adding an RSS feed to an Astro blog

Installing the package

The feed endpoint

Draft filtering

Sorting

Post links

Absolute URLs

atom:link self-reference

Validating the feed

Adding the feed autodiscovery link

Full code listing

The problem with `draft: false` alone

`isPublished()` — one filter to rule them all

Setting `pubDate` values

Where `draft` still fits in

Treat `waitForTimeout` as a smell

The concentric ring layout on `/tags`