DEV Community: Roger Rajaratnam

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.

Designing the blog card and post hero

Roger Rajaratnam — Thu, 16 Apr 2026 21:15:22 +0000

Original post: Designing the blog card and post hero

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

The blog listing is the front door to most posts — it's what someone sees when they
land on /blog, and it should communicate enough about each post that they can
decide whether to click. Getting the card right matters.

There are also some practical decisions baked into the implementation that are
worth documenting: where reading time is calculated, how cover and thumbnail
assets move through the site, how the card stays visually consistent in a grid,
and how the same content contract scales from the listing card to the full post
hero. Draft handling exists too, but mostly as a development convenience rather
than a core product feature.

Scope note: this article stays focused on the contract between two UI
surfaces: the blog card and the page hero. A few supporting features appear
along the way, and they will be covered in later articles in the series:
reading time, tag architecture, Pagefind thumbnails and search
metadata, breadcrumb markup, the share widget, and the draft-to-publish flow.

Diagram fallback for Dev.to. View the canonical article for the original SVG: https://sourcier.uk/blog/blog-card-hero-design

The card component

BlogPost.astro is a pure presentational component, and its contract includes
readingTime as well as the original card data. The listing pages compute
reading time upstream and pass it in so the card itself stays presentational:

---
const {
  description,
  title,
  subTitle,
  url,
  cover,
  pubDate,
  draft,
  readingTime,
} = Astro.props;
const formattedDate = pubDate
  ? new Date(pubDate).toLocaleDateString("en-GB", {
      year: "numeric",
      month: "short",
      day: "numeric",
      timeZone: "Europe/London",
      timeZoneName: "short",
    })
  : null;
---

<a href={url} class={`card card__blog${draft ? " card__blog--draft" : ""}`}>
  {draft && (
    <span class="card__draft-badge" aria-label="Draft">Draft</span>
  )}
  {cover && (
    <div class="card__cover">
      <img src={cover.image.src} alt={cover.image.alt} />
      <div class="card__cover-overlay" aria-hidden="true" />
    </div>
  )}
  <div class="card__body">
    {formattedDate && (
      <p class="card-meta">
        {formattedDate}
        {readingTime && ` · ${readingTime}`}
      </p>
    )}
    <p class="card__title">{title}</p>
    {subTitle && <p class="card__subtitle">{subTitle}</p>}
    <p class="card__description">{description}</p>
  </div>
  <div class="card__cta">
    <span>Read Post</span>
    <span aria-hidden="true">→</span>
  </div>
</a>

The entire card is a single <a> — the click target is the full card surface, not
just a button inside it. That keeps the interaction model simple, but it also means
the card should not grow secondary interactive controls inside it. If the design
ever needs a bookmark button, menu, or other separate action, the structure should
change rather than nesting another interactive element inside the link.

The card__cta at the bottom ("Read Post →") is decorative — it's not needed for
accessibility because the outer <a> carries the destination, but it's a clear
visual affordance that the card is clickable.

Reading time is deliberately calculated outside the component. BlogGrid.astro
and the homepage grid both call readingTime(post.body ?? "").text and pass the
result down. That keeps the card focused on rendering, not content parsing.

That split is deliberate: date formatting stays in the component because it is
display logic, but reading time is derived from body content and belongs upstream.

Reading time is one of the places where this article deliberately stops short.
The important part here is the handoff into the card and hero. The word-count
calculation itself, and the decisions behind the exact string formatting, belong
in a separate article about reading time as a site-wide concern.

Keeping the grid balanced

Cards in a listing need to feel like they belong to the same system even when the
content varies. Some posts have longer subtitles, some have longer descriptions,
and some have cover images with very different compositions.

The card layout handles that by fixing the cover area, using a vertical flex
layout for the body, and clamping the description so one verbose post does not
stretch an entire row.

The description clamp is doing most of the balancing work:

.card__description {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: initial;
  display: -webkit-box;
  -webkit-line-clamp: 3;
  -webkit-box-orient: vertical;
}

That keeps the card heights from drifting too far apart while still letting the
description feel like real copy rather than a one-line stub.

The hover treatment then adds feedback without changing the structure. The card
lifts, the cover image scales slightly, and the overlay fades in:

.card.card__blog {
  transition: transform 0.18s ease, box-shadow 0.18s ease, border-color 0.18s ease;

  &:hover {
    transform: translateY(-4px);
    box-shadow: 0 10px 32px rgba(232, 0, 106, 0.18);
    border-color: var(--color-pink);

    .card__cover img {
      transform: scale(1.04);
    }

    .card__cover-overlay {
      opacity: 1;
    }
  }
}

Those details matter because the listing is dense. Small motion and consistent
heights help it read as a curated grid rather than a stack of unrelated links.

Passing the same contract into the hero

The post page uses the same content fields as the card, but with different
emphasis. The route computes the reading time and passes it into the layout:

import { getCollection, render } from "astro:content";
import { isPublished } from "../../utils/drafts";
import readingTime from "reading-time";

const { post } = Astro.props;
const { Content, headings } = await render(post);
const postReadingTime = readingTime(post.body ?? "").text;
---

MarkdownPostLayout.astro then forwards the same core metadata into
PageHero.astro as coverImage, so the card and the hero stay visually aligned.

<PageHero
  title={frontmatter.title}
  subtitle={frontmatter.subTitle}
  coverImage={frontmatter.cover?.image && {
    src: frontmatter.cover.image.src,
    alt: frontmatter.cover.alt,
  }}
  tags={frontmatter.tags}
  author={frontmatter.author}
  date={formattedDate}
  readingTime={readingTime}
  crumbs={crumbs}
  shareUrl={shareUrl}
  shareTitle={frontmatter.title}
/>

That shared contract is the important architectural decision. The card and the
hero are not two unrelated components that happen to show some of the same data.
They are two views over the same content model.

The hero component

Every post page uses PageHero.astro as its header. For blog posts, the
interesting part is not just that it can show a cover image, but that it can do
that while still handling breadcrumbs, metadata, tags, and sharing without
turning into a one-off page template.

The prop interface shows the scope clearly:

interface Props {
  kicker?: string;
  title: string;
  subtitle?: string;
  coverImage?: { src: string; alt?: string };
  tags?: string[];
  author?: string;
  date?: string;
  readingTime?: string;
  crumbs?: Crumb[];
  shareUrl?: string;
  shareTitle?: string;
}

That gives the hero enough information to work for post pages, listing pages,
and any future landing page that wants the same visual treatment.

If crumbs is omitted, PageHero.astro can derive breadcrumbs from the URL. Post
pages pass them explicitly, but the fallback keeps the component self-sufficient
in other contexts.

The cover image is optional. If it exists, the hero switches into a heavier,
image-led mode with a dark gradient overlay. If not, it still renders as a clean
text-first hero on a dark background.

Subtle movement and shared share UI

The hero background gets a small parallax effect when a cover image is present.
This is the entire script:

const hero = document.querySelector<HTMLElement>(
  ".page-hero[data-has-cover='true']",
);
if (hero) {
  const update = () => {
    const offset = window.scrollY;
    hero.style.backgroundPositionY = `calc(50% + ${offset * 0.4}px)`;
  };
  window.addEventListener("scroll", update, { passive: true });
  update();
}

It's enough to stop the hero feeling static, without turning it into a showy
effect that competes with the title.

The share widget is not a separate hero-only implementation. PageHero.astro
renders the shared SharePost component, then restyles it in place so it fits
the darker surface:

.page-hero__share {
  :global(.share-post__btn) {
    color: rgba(255, 255, 255, 0.55);
    border-color: rgba(255, 255, 255, 0.18);
    background-color: rgba(255, 255, 255, 0.06);

    &:hover {
      color: var(--color-pink);
      border-color: rgba(232, 0, 106, 0.5);
      background-color: rgba(232, 0, 106, 0.12);
    }
  }
}

The kicker prop is part of the component API, but MarkdownPostLayout.astro
does not pass it for article pages. It is used in other contexts such as the
blog index hero, which is a good example of why keeping the component contract
slightly broader than any single caller is useful.

The result is a consistent pair of surfaces: the card does the work of getting a
reader to click, and the hero takes the same ingredients and gives them enough
weight to anchor the full article.

Draft badge and overlay for local development

This is the one part of the card system that exists mainly for the author rather
than the reader.

When a post has draft: true, two things happen visually. A pink badge appears
in the top-left corner of the card:

.card__draft-badge {
  position: absolute;
  top: 0.625rem;
  left: 0.625rem;
  z-index: 2;
  padding: 0.2rem 0.55rem;
  background-color: var(--color-pink);
  color: #ffffff;
  font-family: "Barlow Condensed", sans-serif;
  font-size: 0.65rem;
  font-weight: 700;
  text-transform: uppercase;
  letter-spacing: 0.1em;
}

And a semi-transparent overlay covers the entire card:

.card__blog--draft::after {
  content: "";
  position: absolute;
  inset: 0;
  background-color: var(--color-paper);
  opacity: 0.55;
  pointer-events: none;
  z-index: 1;
}

The overlay is a ::after pseudo-element so it doesn't add DOM noise. pointer-events: none
ensures it doesn't intercept clicks — the underlying <a> remains clickable.
The z-index: 1 keeps it below the badge (z-index: 2) so the badge label
stays readable.

This is really a convenience feature for local development, not a production
content pattern. Draft posts are filtered out by the publishing logic unless
drafts are explicitly enabled, so the badge and overlay mainly exist to make
draft-heavy local sessions easier to scan at a glance.

That broader publishing logic is out of scope for this article. The draft
flag itself comes from the content model, and the rules that decide whether a
post is visible belong to the publishing workflow rather than the card design.

Full component listings

If you want to inspect the finished components end to end, expand the listings
below. They show the complete BlogPost.astro and PageHero.astro
implementations in one place while you read.

src/components/BlogPost.astro

---
const {
  description,
  title,
  subTitle,
  url,
  cover,
  pubDate,
  draft,
  readingTime,
} = Astro.props;
const formattedDate = pubDate
  ? new Date(pubDate).toLocaleDateString("en-GB", {
      year: "numeric",
      month: "short",
      day: "numeric",
      timeZone: "Europe/London",
      timeZoneName: "short",
    })
  : null;
---

<a href="{url}">
  {
    draft &amp;&amp; (
      <span>
        Draft
      </span>
    )
  }
  {
    cover &amp;&amp; (

        <img src="{cover.image.src}" alt="{cover.image.alt}">


    )
  }

    {
      formattedDate &amp;&amp; (
        <p>
          {formattedDate}
          {readingTime &amp;&amp; ` · ${readingTime}`}
        </p>
      )
    }
    <p>{title}</p>
    {subTitle &amp;&amp; <p>{subTitle}</p>}
    <p>{description}</p>


    <span>Read Post</span>
    <span>→</span>

</a>


  .card__description {
    overflow: hidden;
    text-overflow: ellipsis;
    white-space: initial;
    display: -webkit-box;
    -webkit-line-clamp: 3;
    -webkit-box-orient: vertical;
  }

  .card__draft-badge {
    position: absolute;
    top: 0.625rem;
    left: 0.625rem;
    z-index: 2;
    padding: 0.2rem 0.55rem;
    background-color: var(--color-pink);
    color: #ffffff;
    font-family: "Barlow Condensed", sans-serif;
    font-size: 0.65rem;
    font-weight: 700;
    text-transform: uppercase;
    letter-spacing: 0.1em;
    line-height: 1;
  }

  .card__blog--draft {
    position: relative;

    &amp;::after {
      content: "";
      position: absolute;
      inset: 0;
      background-color: var(--color-paper);
      opacity: 0.55;
      pointer-events: none;
      z-index: 1;
    }
  }

PageHero.astro imports Breadcrumb.astro and SharePost.astro, so this
listing keeps those supporting components as imports instead of inlining them.

src/components/PageHero.astro

---
import { tagSlug } from "../utils/tags";
import Breadcrumb from "./Breadcrumb.astro";
import SharePost from "./SharePost.astro";

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

interface Props {
  kicker?: string;
  title: string;
  subtitle?: string;
  coverImage?: { src: string; alt?: string };
  tags?: string[];
  author?: string;
  date?: string;
  readingTime?: string;
  crumbs?: Crumb[];
  shareUrl?: string;
  shareTitle?: string;
}

const {
  kicker,
  title,
  subtitle,
  coverImage,
  tags,
  author,
  date,
  readingTime,
  crumbs,
  shareUrl,
  shareTitle,
} = Astro.props;

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

const resolvedCrumbs: Crumb[] = crumbs ?? autoCrumbs(Astro.url.pathname);
---




      {
        resolvedCrumbs.length &gt; 0 &amp;&amp; (

        )
      }
      {kicker &amp;&amp; <p>{kicker}</p>}
      <h1>{title}</h1>
      {subtitle &amp;&amp; <p>{subtitle}</p>}
      {
        (author || date || readingTime || (tags &amp;&amp; tags.length &gt; 0)) &amp;&amp; (

            {author &amp;&amp; <span>By {author}</span>}
            {date &amp;&amp; <span>{date}</span>}
            {readingTime &amp;&amp; (
              <span>{readingTime}</span>
            )}
            {(date || readingTime) &amp;&amp; tags &amp;&amp; tags.length &gt; 0 &amp;&amp; (
              <span></span>
            )}
            {tags &amp;&amp; tags.length &gt; 0 &amp;&amp; (

                {tags.map((tag: string) =&gt; (
                  <a href="{`/tags/${tagSlug(tag)}`}">
                    {tag}
                  </a>
                ))}

            )}

        )
      }
      {
        shareUrl &amp;&amp; shareTitle &amp;&amp; (



        )
      }





  const hero = document.querySelector&lt;HTMLElement&gt;(
    ".page-hero[data-has-cover='true']",
  );
  if (hero) {
    const update = () =&gt; {
      const offset = window.scrollY;
      // Move the background at 40% of scroll speed for a subtle parallax
      hero.style.backgroundPositionY = `calc(50% + ${offset * 0.4}px)`;
    };
    window.addEventListener("scroll", update, { passive: true });
    update();
  }



  .page-hero {
    min-height: 320px;
    display: flex;
    align-items: flex-end;
    padding: 5rem 1.5rem 4rem;
    background:
      radial-gradient(
        ellipse 80% 60% at 70% 0%,
        rgba(232, 0, 106, 0.18) 0%,
        transparent 65%
      ),
      #0a0a0a;
    color: #ffffff;
    position: relative;
    isolation: isolate;
    overflow: hidden;

    &amp;::before {
      content: "";
      position: absolute;
      inset: 0;
      z-index: -1;
      background-image: radial-gradient(
        circle,
        rgba(255, 255, 255, 0.18) 1px,
        transparent 1px
      );
      background-size: 28px 28px;
      mask-image: radial-gradient(
        ellipse 90% 90% at 50% 50%,
        black 30%,
        transparent 90%
      );
      -webkit-mask-image: radial-gradient(
        ellipse 90% 90% at 50% 50%,
        black 30%,
        transparent 90%
      );
      pointer-events: none;

      @media (prefers-reduced-motion: no-preference) {
        animation: dot-grid-breathe 4s ease-in-out infinite;
      }
    }

    @keyframes dot-grid-breathe {
      0%,
      100% {
        opacity: 0.5;
      }
      50% {
        opacity: 1;
      }
    }

    &amp;[data-has-cover="true"] {
      min-height: 420px;
      padding: 5rem 1.5rem 4rem;
      background-image: var(--cover-image);
      background-size: cover;
      background-position: center;

      &amp;::after {
        content: "";
        position: absolute;
        inset: 0;
        z-index: -2;
        background: linear-gradient(
          to bottom,
          rgba(0, 0, 0, 0.35) 0%,
          rgba(0, 0, 0, 0.7) 55%,
          rgba(0, 0, 0, 0.92) 100%
        );
        pointer-events: none;
      }

      .page-hero__tag {
        background-color: rgba(255, 255, 255, 0.1);
        border-color: rgba(255, 255, 255, 0.25);
        color: rgba(255, 255, 255, 0.7);

        &amp;:hover {
          background-color: rgba(232, 0, 106, 0.12);
          border-color: rgba(232, 0, 106, 0.5);
          color: var(--color-pink);
        }
      }
    }

    .container {
      position: relative;
      z-index: 1;
      width: 100%;
    }
  }

  .page-hero__inner {
    max-width: 780px;
  }

  .page-hero__title {
    font-size: clamp(2.25rem, 6vw, 4rem);
    font-weight: 800;
    line-height: 1.05;
    letter-spacing: -0.02em;
    margin-bottom: 1rem;
    color: #ffffff;
  }

  .page-hero__subtitle {
    font-size: 1.25rem;
    line-height: 1.5;
    color: rgba(255, 255, 255, 0.65);
    margin-bottom: 1.5rem;
    font-weight: 300;
  }

  .page-hero__meta {
    display: flex;
    flex-wrap: wrap;
    align-items: center;
    gap: 0.75rem 1rem;
    font-size: 0.875rem;
    font-family: "Barlow Condensed", sans-serif;
    text-transform: uppercase;
    letter-spacing: 0.08em;
    color: rgba(255, 255, 255, 0.5);
  }

  .page-hero__author {
    color: rgba(255, 255, 255, 0.85);
  }

  .page-hero__date {
    &amp;::before {
      content: "·";
      margin-right: 1rem;
      color: var(--color-pink);
    }
  }

  .page-hero__divider {
    &amp;::before {
      content: "·";
      color: var(--color-pink);
    }

    @media (max-width: 639px) {
      display: none;
    }
  }

  .page-hero__tags {
    display: flex;
    flex-wrap: wrap;
    gap: 0.5rem;
  }

  .page-hero__tag {
    display: inline-block;
    font-family: "Barlow Condensed", sans-serif;
    font-size: 0.75rem;
    font-weight: 600;
    text-transform: uppercase;
    letter-spacing: 0.1em;
    color: rgba(255, 255, 255, 0.55);
    border: 1px solid rgba(255, 255, 255, 0.18);
    border-radius: 4px;
    padding: 0.25rem 0.6rem;

    @media (max-width: 639px) {
      font-size: 0.8rem;
      padding: 0.4rem 0.75rem;
    }
    transition:
      background-color 0.15s ease,
      color 0.15s ease,
      border-color 0.15s ease;

    &amp;:hover {
      background-color: rgba(232, 0, 106, 0.12);
      border-color: rgba(232, 0, 106, 0.5);
      color: var(--color-pink);
    }
  }

  .hero-kicker {
    display: inline-block;
    font-size: 0.8125rem;
    font-weight: 700;
    text-transform: uppercase;
    letter-spacing: 0.12em;
    color: var(--color-pink);
    margin-bottom: 0.75rem;
  }

  .page-hero__share {
    margin-top: 1.5rem;

    :global(.share-post) {
      border-color: rgba(255, 255, 255, 0.15);
      border-bottom: none;
      padding: 1.25rem 0 0;
      margin: 0;
    }

    :global(.share-post__label) {
      color: rgba(255, 255, 255, 0.4);
    }

    :global(.share-post__btn) {
      color: rgba(255, 255, 255, 0.55);
      border-color: rgba(255, 255, 255, 0.18);
      background-color: rgba(255, 255, 255, 0.06);

      &amp;:hover {
        color: var(--color-pink);
        border-color: rgba(232, 0, 106, 0.5);
        background-color: rgba(232, 0, 106, 0.12);
      }
    }
  }

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

Building a dark/light theme toggle in Astro

Roger Rajaratnam — Tue, 14 Apr 2026 10:04:45 +0000

A dark/light toggle is one of those features that sounds trivial and isn't. Get it
wrong and you ship the flash of wrong theme — the page loads light, then flickers
dark if that was the user's stored preference. Or you ship a toggle that forgets
its state on every page load.

This blog's implementation avoids all of those. There's also a third option that
most implementations skip: a "System" mode that tracks the OS preference in
real time, without touching localStorage.

Diagram fallback for Dev.to. View the canonical article for the full version: https://sourcier.uk/blog/dark-light-theme-toggle

The colour system

All colours are defined as CSS custom properties on :root and overridden under
[data-theme='dark']. There's no separate dark-mode stylesheet, no class-swapping
on individual elements — just two variable sets and one attribute:

:root {
  --color-pink: #e8006a;
  --color-ink: #0f0f0f;
  --color-paper: #ffffff;
  --color-muted: #6b6b6b;
  --color-surface: #ffffff;
  --color-border: rgba(0, 0, 0, 0.1);
}

[data-theme='dark'] {
  --color-ink: #f0f0f0;
  --color-paper: #111111;
  --color-muted: #999999;
  --color-surface: #1c1c1c;
  --color-border: rgba(255, 255, 255, 0.1);
}

Switching between themes is a single setAttribute call on document.documentElement.
Every element on the page that uses a custom property updates instantly.

The pink accent (--color-pink) doesn't change between themes — it's a
fixed identity colour, not a semantic one.

The toggle component

The toggle lives in the navbar's social icon group inside a dedicated ThemeToggle.astro
component. It's a single icon button that opens a small dropdown menu with System,
Light, and Dark options:

<div class="theme-toggle">
  <button
    class="theme-toggle__trigger social-icon"
    aria-label="Theme preference"
    aria-expanded="false"
    aria-haspopup="true"
  >
    <span class="theme-toggle__trigger-icon theme-toggle__trigger-icon--system">
      <!-- half-stroke circle icon -->
    </span>
    <span class="theme-toggle__trigger-icon theme-toggle__trigger-icon--light">
      <!-- sun icon -->
    </span>
    <span class="theme-toggle__trigger-icon theme-toggle__trigger-icon--dark">
      <!-- moon icon -->
    </span>
  </button>

  <div class="theme-toggle__dropdown" role="menu" aria-label="Theme preference" hidden>
    <button class="theme-toggle__option" data-theme-select="system"
            role="menuitem" aria-pressed="true">
      <!-- half-stroke circle --> System
    </button>
    <button class="theme-toggle__option" data-theme-select="light"
            role="menuitem" aria-pressed="false">
      <!-- sun --> Light
    </button>
    <button class="theme-toggle__option" data-theme-select="dark"
            role="menuitem" aria-pressed="false">
      <!-- moon --> Dark
    </button>
  </div>
</div>

The trigger carries aria-haspopup="true" and aria-expanded (toggled by the
script). The dropdown starts hidden; the script removes that attribute to reveal it.

Three icon spans live inside the trigger — only one visible at a time. CSS targets
data-theme-current on the wrapper div (set by the script) to show the right icon:

.theme-toggle__trigger-icon { display: none; }

.theme-toggle[data-theme-current="system"] .theme-toggle__trigger-icon--system,
.theme-toggle[data-theme-current="light"]  .theme-toggle__trigger-icon--light,
.theme-toggle[data-theme-current="dark"]   .theme-toggle__trigger-icon--dark {
  display: flex;
}

This makes the trigger reflect the user's chosen preference, not the resolved
OS theme. If someone selects System and their OS is dark, the trigger shows the
half-stroke circle — not the moon.

The script

The toggle script handles two concerns: dropdown open/close state, and theme
selection. Both live inside the <script> block in ThemeToggle.astro. Astro
bundles component scripts automatically:

const wrapper = document.querySelector<HTMLElement>(".theme-toggle")!;
const trigger = wrapper.querySelector<HTMLButtonElement>(".theme-toggle__trigger")!;
const dropdown = wrapper.querySelector<HTMLElement>(".theme-toggle__dropdown")!;
const options = wrapper.querySelectorAll<HTMLButtonElement>("[data-theme-select]");
const html = document.documentElement;

function setTheme(mode: string) {
  wrapper.dataset.themeCurrent = mode;
  options.forEach((btn) =>
    btn.setAttribute("aria-pressed", btn.dataset.themeSelect === mode ? "true" : "false"),
  );
  if (mode === "system") {
    localStorage.removeItem("theme");
    html.setAttribute(
      "data-theme",
      window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light",
    );
  } else {
    localStorage.setItem("theme", mode);
    html.setAttribute("data-theme", mode);
  }
}

function openMenu() {
  dropdown.removeAttribute("hidden");
  trigger.setAttribute("aria-expanded", "true");
}

function closeMenu() {
  dropdown.setAttribute("hidden", "");
  trigger.setAttribute("aria-expanded", "false");
}

trigger.addEventListener("click", () => {
  if (dropdown.hasAttribute("hidden")) openMenu();
  else closeMenu();
});

document.addEventListener("click", (e) => {
  if (!wrapper.contains(e.target as Node)) closeMenu();
});

document.addEventListener("keydown", (e) => {
  if (e.key === "Escape") closeMenu();
});

options.forEach((btn) =>
  btn.addEventListener("click", () => {
    setTheme(btn.dataset.themeSelect!);
    closeMenu();
  }),
);

const stored = localStorage.getItem("theme");
setTheme(stored === "dark" || stored === "light" ? stored : "system");

window.matchMedia("(prefers-color-scheme: dark)").addEventListener("change", (e) => {
  if (!localStorage.getItem("theme")) {
    html.setAttribute("data-theme", e.matches ? "dark" : "light");
  }
});

A few things worth noting:

setTheme is the single source of truth — it updates data-theme-current on the wrapper (for trigger icon visibility), aria-pressed on each option, and localStorage and data-theme on <html>.
openMenu/closeMenu keep the hidden attribute and aria-expanded in sync. Using the HTML hidden attribute (rather than a CSS class) means the closed state works even before styles load.
Clicking outside the wrapper or pressing Escape closes the menu — standard dropdown behaviour users expect.
System mode removes the localStorage key rather than storing "system". Only "dark" or "light" are ever written.
The matchMedia change listener fires when the OS theme switches while the page is open. It only acts when no explicit preference is stored — i.e. the user is in System mode.

Preventing the flash of wrong theme

If you read localStorage in a script that loads after the page renders, you'll
see the default theme briefly before the script applies the stored preference. The
fix is to run the theme-reading code synchronously in <head>, before the body
is parsed. In BaseLayout.astro:

<html lang="en" data-theme="light">
  <head>
    <!-- ... meta, links ... -->
    <script is:inline>
      const stored = localStorage.getItem("theme");
      if (stored === "dark") {
        document.documentElement.setAttribute("data-theme", "dark");
      } else if (stored === "light") {
        document.documentElement.setAttribute("data-theme", "light");
      } else if (window.matchMedia("(prefers-color-scheme: dark)").matches) {
        document.documentElement.setAttribute("data-theme", "dark");
      }
    </script>

The priority order is:

Stored explicit preference ("dark" or "light")
OS prefers-color-scheme: dark
Fallback — the data-theme="light" already on the <html> tag

The is:inline directive tells Astro not to bundle or defer this script — it
stays as a literal inline <script> tag and runs immediately, before the browser
paints anything.

Expressive Code alignment

Expressive Code — the syntax highlighting library — needs to know to follow the
data-theme attribute rather than the OS prefers-color-scheme media query.
Without this, code blocks would follow the system preference even when the user
has picked an explicit theme — they'd be out of sync:

expressiveCode({
  useDarkModeMediaQuery: false,
  themeCssSelector: (theme) =>
    theme.type === "dark"
      ? '[data-theme="dark"]'
      : ':root:not([data-theme="dark"])',
})

useDarkModeMediaQuery: false disables the default @media (prefers-color-scheme)
approach. themeCssSelector maps each Expressive Code theme variant to a CSS
selector that matches the data-theme attribute instead.

Typed content collections in Astro

Roger Rajaratnam — Mon, 13 Apr 2026 19:19:13 +0000

SeriesPart of How this blog was built — documenting every decision that shaped this site.

One of the things I wanted to get right early on this blog was the content model.
Markdown is flexible to the point of being dangerous — nothing stops you from
publishing a post with a missing title, a malformed date, or a cover image path
that leads nowhere. On a small site this sounds manageable. In practice, these
problems compound.

Astro content collections solve this with Zod schema validation at build time.
If the content doesn't match the schema, the build fails loudly instead of
deploying silently broken content.

How the collection is defined

Everything lives in src/content.config.ts. The defineCollection call takes a
loader (which describes where to find the files) and a schema:

import { defineCollection } from "astro:content";
import { glob } from "astro/loaders";
import { z } from "astro/zod";

const posts = defineCollection({
  loader: glob({ pattern: ["**/*.md", "!README.md"], base: "./collections/posts" }),
  schema: ({ image }) =>
    z.object({
      title: z.string(),
      subTitle: z.string(),
      description: z.string(),
      pubDate: z.coerce.date(),
      author: z.string(),
      cover: z
        .object({
          image: image(),
          alt: z.string(),
        })
        .optional(),
      tags: z.array(z.string()),
      draft: z.boolean().default(false),
      history: z
        .array(
          z.object({
            datetime: z.coerce.date(),
            note: z.string(),
          }),
        )
        .optional(),
      credits: z
        .array(
          z.object({
            label: z.string(),
            text: z.string(),
            url: z.string().url().optional(),
          }),
        )
        .optional(),
    }),
});

export const collections = { posts };

A few things worth noting:

z.coerce.date() means a YAML string like 2026-03-26T00:00:00 is automatically coerced to a JavaScript Date object. You get proper date comparison and formatting in templates without any manual parsing.
image() is a special helper provided by Astro's schema context. It validates that the referenced file exists on disk and returns a typed object with the processed src. Astro passes this through its image optimisation pipeline.
draft: z.boolean().default(false) means the draft field is optional in frontmatter — omitting it defaults to false, so only posts that explicitly declare draft: true need the field.
credits URLs use z.string().url(), so a malformed URL will fail the build rather than silently render a broken link.

Where the posts live

The glob loader uses a base path outside src/ — the posts are in
collections/posts/ at the project root. Each post gets its own directory:

collections/
  posts/
    why-astro/
      index.md
    comments-system/
      index.md
      comments-system-cover.jpg

Co-locating the cover image with the Markdown file is simpler than managing a
separate public/ directory for post images. Astro's image pipeline picks them up
automatically when the schema uses image().

The post id that Astro assigns is derived from the directory structure — why-astro
for the post above. That becomes the URL slug via the [id].astro dynamic route.

Querying the collection

In any .astro file or API route, getCollection("posts") returns a typed array
of posts whose data property matches the schema:

import { getCollection } from "astro:content";

const allPosts = await getCollection("posts");

Every access to post.data.title, post.data.pubDate, or post.data.tags is
fully typed. If the schema changes, TypeScript catches every reference that no
longer lines up.

The draft flag and scheduled publishing

The draft field alone isn't the full picture. The blog uses a small utility
in src/utils/drafts.ts that combines draft status, publish date, and an
environment 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;
  if (post.data.draft) return false;
  return post.data.pubDate <= new Date();
}

Every collection query that feeds the public site passes posts through
isPublished() rather than a bare draft check:

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

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

This gives three distinct states:

draft: true — never visible on the public site, regardless of pubDate.
draft: false, future pubDate — not yet published; filtered out until the date passes.
draft: false, past pubDate — live.

The SHOW_DRAFTS=true environment variable short-circuits the filter entirely,
which is how the preview branch deploy works — it shows everything, including
drafts and scheduled posts, behind a passcode wall.

Posts filtered out by isPublished() are excluded from listings, tag pages, the
RSS feed, and getStaticPaths() — so their URLs return a 404 in production even
if someone guesses the slug.

Optional fields and TypeScript

The cover, history, and credits fields are all .optional(). In templates
this means you get types like ({ image: ImageMetadata; alt: string } | undefined).
TypeScript will refuse to let you access cover.image.src without first checking
that cover exists.

That's the intended behaviour — it forces every template that uses these fields to
handle the case where they're absent, which is exactly the kind of bug that slips
through without a type system.

What this gives you

Build-time validation. A malformed date, a missing required field, or a cover
image pointing to a nonexistent file stops the build immediately. You find content
errors locally, not after deploying.

Full TypeScript coverage across templates. Every .astro component that
touches post.data gets accurate types. Rename a field in the schema and
TypeScript surfaces every broken reference.

Scheduled publishing without a CMS. Because pubDate is a typed Date and
the isPublished() filter compares it to the current time, setting a future date
is enough to schedule a post. The daily build picks it up automatically. There's
a dedicated post on how this works coming 8 May.

Drafts with a preview workflow. draft: true keeps work-in-progress content
off the live site, while the SHOW_DRAFTS flag lets you review it fully rendered
on a separate deploy before it goes public.

Working on something similar?

If you're setting up a content pipeline, designing a typed content model, or
building publish workflows into your Astro site — I'm available for consulting.

Get in touch via the contact page and tell me what you're working on.

Keeping your zsh config out of Copilot's terminals

Roger Rajaratnam — Mon, 13 Apr 2026 18:57:36 +0000

If you use GitHub Copilot in VS Code and have a heavily configured zsh — Powerlevel10k,
a bunch of aliases, nvm or pyenv hooks — you've probably noticed the agent making a
mess of its terminal output, or occasionally failing because something in your
.zshrc conflicts with what it's trying to run.

The problem is simple: Copilot spins up non-interactive shells to execute commands.
Your .zshrc loads anyway, because that's what .zshrc does. The agent doesn't
need your prompt theme; it just needs to run git status and get on with its life.
Your customisations are noise at best, a source of failures at worst.

Suppressing them without also killing them in your regular VS Code terminal is the
tricky part.

The naive fix and why it breaks things

The obvious approach is to skip customisations for all VS Code terminals:

if [[ "$TERM_PROGRAM" != "vscode" ]]; then
  # load powerlevel10k, aliases, nvm, etc.
fi

VS Code sets TERM_PROGRAM=vscode in every terminal it opens — including the ones
you open yourself. So this guard works for the agent, but it also strips your prompt
and aliases from your regular integrated terminal. Not what you want.

Why PATH isn't a reliable signal

The next idea is to detect the Copilot agent via $PATH, since the extension injects
its CLI tools into it. The problem: VS Code injects those PATH entries into all
terminals — integrated and agent alike. You can't use it to tell them apart.

The fix: a custom env var

VS Code has a per-platform setting that injects environment variables into terminals
the user opens — terminal.integrated.env.osx, terminal.integrated.env.linux, and
terminal.integrated.env.windows. Critically, these settings do not apply to
terminals that extensions spin up programmatically. This is the clean signal we need.

In VS Code settings.json, add whichever keys match your platform(s):

"terminal.integrated.env.osx": { "VSCODE_USER_TERMINAL": "1" },
"terminal.integrated.env.linux": { "VSCODE_USER_TERMINAL": "1" },
"terminal.integrated.env.windows": { "VSCODE_USER_TERMINAL": "1" }

Then in .zshrc, update the guard:

if [[ "$TERM_PROGRAM" != "vscode" || -n "$VSCODE_USER_TERMINAL" ]]; then
  # load powerlevel10k, aliases, nvm, etc.
fi

The logic reads: load customisations if this is not a VS Code terminal, or if it is
one that the user opened (as confirmed by the injected var).

Why this works

Terminal	`TERM_PROGRAM`	`VSCODE_USER_TERMINAL`	Customisations load?
Any terminal outside VS Code	app-specific or unset	unset	Yes — first condition passes
VS Code integrated terminal	`vscode`	`1`	Yes — second condition passes
Copilot agent terminal	`vscode`	unset	No — both conditions fail

Diagram fallback for Dev.to. View the canonical article for the full version: https://sourcier.uk/blog/vscode-copilot-terminal-zsh

The key is that terminal.integrated.env.* is a VS Code UI concern — it only kicks
in when a human is on the other end of the terminal. Agent terminals bypass it
entirely, giving you a reliable, low-friction way to distinguish the two situations.

That's it

The guard is a single if condition and the env var is harmless to everything else
in your environment. Add only the platform keys you need — if you only ever work on
macOS, one line is enough.

Choosing the tech stack

Roger Rajaratnam — Mon, 13 Apr 2026 18:57:19 +0000

SeriesPart of How this blog was built — twenty posts on every decision that shaped this site.

Before writing a single line of code for this blog, I spent some time thinking
about the stack. It is a personal site — nobody is paying me to make good
architectural decisions here — but that is exactly when it is worth being honest
about what you actually need rather than defaulting to whatever you already know.

The requirements were simple: write posts in Markdown, serve fast static HTML,
add the odd interactive feature without shipping a full JavaScript runtime, and
host it somewhere cheap with minimal ongoing maintenance. No CMS, no database,
no server.

Here is what I landed on, and the thinking behind each choice.

Diagram fallback for Dev.to. View the canonical article for the full version: https://sourcier.uk/blog/choosing-the-tech-stack

Tech

The technical side covers the framework, the language, the build pipeline, the
hosting, and the services that handle email.

TypeScript

Before going into each tool: one choice runs through all of them. Everything
here is TypeScript. For a solo project where there are no code reviews to catch
mistakes, having the compiler surface errors early is genuinely useful — types
flow through the codebase, refactoring is safe, and mistakes that would otherwise
show up at runtime get caught at build time instead.

All the tools below have first-class TypeScript support, which made it a
non-decision.

Astro

Astro describes itself as "the web framework for content-driven websites" — which
is a fair summary. You write .astro components with a template syntax that sits
close to HTML, with a TypeScript frontmatter block at the top for any logic. The
output is static HTML by default. JavaScript only reaches the browser when you
explicitly include a <script> block or use a client directive.

That trade-off suited this project well. Most of the pages here are articles. They
do not need a JavaScript runtime — they need to load quickly and be readable.

Content collections

Content collections were the feature that made Astro the obvious choice. You
define a collection in src/content.config.ts, give it a Zod schema, and point
it at a directory of Markdown files. Every piece of frontmatter is then typed,
validated at build time, and queryable via getCollection().

const posts = defineCollection({
  loader: glob({ pattern: ["*.md", "**/*.md"], base: "./collections/posts" }),
  schema: ({ image }) =>
    z.object({
      title: z.string(),
      pubDate: z.coerce.date(),
      tags: z.array(z.string()),
      draft: z.boolean().default(false),
    }),
});

A missing title or malformed pubDate fails the build rather than silently
producing a broken page. That is the right behaviour for a content site.

Zero JS by default

The features I wanted — syntax-highlighted code blocks, a dark/light toggle, a
scroll-tracked table of contents, Mermaid diagrams — do not require a framework
runtime. In Astro, each is a <script> block in a component, bundled at build
time and only shipped when the component is used. The Mermaid library is the
heaviest dependency on the page, and even that only loads on posts that actually
contain a diagram.

The build pipeline

Plugging in Expressive Code for syntax highlighting, a custom remark plugin for
Mermaid, and emoji support was a few lines in astro.config.mjs:

export default defineConfig({
  site: "https://sourcier.uk",
  integrations: [expressiveCode({ /* ... */ })],
  markdown: {
    remarkPlugins: [remarkMermaid, [emoji, { emoticon: true, accessible: true }]],
    syntaxHighlight: false,
  },
});

syntaxHighlight: false disables Astro's built-in Shiki so it doesn't conflict
with Expressive Code, which runs its own highlighting pipeline.

Remark Emoji

Posts on this blog support emoji shortcodes — writing :rocket: in Markdown
produces 🚀, and emoticons like :-) are converted too. This is handled
by remark-emoji, a remark plugin that
runs as part of the Astro markdown pipeline.

It is a small thing, but it means emoji work consistently across editors and
operating systems without relying on platform-specific input methods. The
shortcode syntax is also easier to read in raw Markdown than pasting a Unicode
character directly.

The plugin takes two options worth knowing about:

[emoji, { emoticon: true, accessible: true }]

emoticon: true enables the ASCII emoticon conversion. accessible: true wraps
each emoji in a <span> with a role="img" and aria-label, so screen readers
announce them rather than reading out the raw Unicode character name.

Netlify

The blog has two requirements that go beyond static files: a comment system and a
mailing list. Both need server-side logic. Netlify handles this through serverless
functions — Node.js handlers in netlify/functions/ that run without a
provisioned server. The comment approval flow, subscriber handling, and
transactional email via Resend all run this way.

The rest of what Netlify provides is straightforward: git push triggers a build,
the output lands on a CDN, and every pull request gets a preview URL. For a site
like this, the free tier covers everything comfortably.

Resend

The mailing list and comment notifications both send transactional email.
Resend handles that.

The main alternatives were SendGrid, Postmark, and AWS SES. All of them work, but
they each carry some friction — verbose SDKs, legacy dashboard UIs, or IAM
configuration in the case of SES. Resend is newer and has been built with
developers in mind: the API is simple, the SDK is small, and the free tier (3,000
emails per month) is generous enough for a personal site.

The integration is a few lines in a Netlify function:

import { Resend } from "resend";

const resend = new Resend(process.env.RESEND_API_KEY);

await resend.emails.send({
  from: "Sourcier <hello@sourcier.uk>",
  to: subscriber.email,
  subject: "New post: " + post.title,
  html: emailBody,
});

One thing worth noting: Resend requires a verified sending domain. That means
adding DNS records and waiting for propagation, which is a slightly annoying
one-time setup. After that it is transparent.

Design

The visual side is handled by three tools: a CSS framework for layout and
components, an icon library, and a photography source for cover images.

Bulma CSS

I wanted a CSS framework that would give me a reasonable baseline — grid, spacing,
components — without requiring a JavaScript runtime, a PostCSS configuration, or
a purge step. Bulma fits that description. It is a pure CSS framework with no
JavaScript at all.

I import it once and override what I need in global.scss using CSS custom
properties. The visual layer is entirely predictable at build time, which keeps
things simple. Bulma's modifier class convention (is-*, has-*) also composes
well with Astro's scoped component styles — global tokens in one file, component
styles in the component.

It is not the most fashionable choice in 2026, but it does the job without getting
in the way.

Font Awesome

Icons on the site — the theme toggle, social links, the navbar burger, share
buttons, and the tech stack grid on the about page — all come from
Font Awesome. The free tier covers everything used here.

The integration is through the SVG core package rather than a web font or a
<script> tag:

import { faGithub } from "@fortawesome/free-brands-svg-icons";
import { faMoon } from "@fortawesome/free-solid-svg-icons";

Each icon is an array of metadata — dimensions, path data — that a small helper
converts to an inline SVG string. That string is then passed to Astro's
set:html directive:

<span set:html={faIcon(faMoon, { size: 18 })} />

The reason for this approach over a web font or CDN-loaded script is that no
extra network request is needed and no characters-as-glyphs trick is involved.
The SVG paths are tree-shaken at build time — only the icons actually imported
end up in the output. On a page that uses three icons, three icons ship.

The one downside is that it is slightly more verbose than dropping in an <i>
tag. For a component-based setup that is a reasonable trade.

Unsplash

Photography on this blog comes from Unsplash — a library
of freely licensed photography. The licence allows use in commercial and
non-commercial projects without attribution, though I include credits anyway as a
matter of courtesy to the photographers.

The practical reason for Unsplash over commissioning or sourcing images elsewhere
is straightforward: the selection is large, the quality is high, and there is no
licensing friction. For a personal blog, that is the right trade.

Testing

Testing is a deliberate omission from this stack description — not because it isn't important, but because it deserves its own treatment. A content-driven Astro site has different testing concerns to a standard web application: build-time validation through Zod schemas catches a category of errors before they reach production, but there is still meaningful ground to cover around unit testing utilities, integration testing serverless functions, and end-to-end testing the rendered output.

That will be the subject of a dedicated series. This series focuses on building the thing — the testing series will focus on verifying it.

AI

AI is also absent from this stack description — and for the same reason: it deserves its own series, not a footnote.

The tooling is moving fast enough that anything specific I write today would be out of date within months. What I can say is that AI-assisted development is not going away, and treating it as a gimmick at this point is a choice with real consequences. A dedicated series on how to work with AI effectively — in code review, in architecture, in the day-to-day mechanics of building software — is coming.

What I do want to say here is this: the rise of AI makes human judgement more important, not less. The engineers who will get the most out of these tools are the ones who already understand what good looks like — who can read generated code and spot the subtle wrong, who know when an abstraction is heading somewhere problematic, who understand the trade-offs well enough to push back when the tool confidently picks the wrong one. AI amplifies whatever understanding you bring to it. It does not replace the need to actually understand.

That's part of why this blog exists. The skills worth preserving aren't the mechanical ones — those are exactly what AI is good at. The skills worth preserving are the ones that require experience to develop: knowing what to build, knowing why, and knowing when not to.

When this stack falls short

For a project with complex client-side state, a real-time feed, or a heavily
interactive UI, this stack would be the wrong choice. Astro is not set up for
that, and Netlify Functions are not a substitute for a proper backend. Those
projects are better served by a framework with client-side routing and a dedicated
API layer.

But for a blog, it is a good fit. The build is fast, the output is simple, and
there is very little to maintain. That is roughly what I was after.

The rest of this series goes into each part in more detail — starting with
typed content collections and working through everything from dark mode to the comment system.

Need help choosing your stack?

If you're at the early stages of a project and want a second opinion on the
architecture — or you've already built something and want a review — I'm
available for consulting.

Get in touch via the contact page and tell me what you're working on.

DEV Community: Roger Rajaratnam

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

OpenGraph, Twitter Cards, and article metadata in Astro

Centralising metadata in BaseLayout

The OpenGraph block

Article-specific tags

Twitter Cards

Canonical URLs

Passing metadata from post pages

Playwright E2E testing AI skills: JavaScript London talk

Why this talk is framed around AI skills

Where E2E fits in the testing pyramid

Why Playwright is still the right foundation

What the playwright-explore-website skill is

How I would use it for E2E testing

What E2E tests are good at

Codegen and exploration are different tools

Keeping tests reliable

Let Playwright wait for you

Use selectors that survive refactoring

Treat waitForTimeout as a smell

Make the await match the business signal

Page objects are a scaling tool

Other useful jobs for the same skill

Running Playwright in CI and debugging failures

When not to write an E2E test

A pragmatic place to start

The playwright-explore-website Copilot skill

What the skill is for

The original awesome-copilot example

My local setup

Playwright MCP setup

The enhancements I added

1. Self-bootstrapping setup instructions

2. A serial exploration rule

3. Rendered UI review

4. Visual audit prompts

5. Screenshot cleanup

6. Stronger output requirements

Where this fits

Building a tag system in Astro

Slug normalisation

Publication-aware tag counts

The weighted cloud on the blog archive

The concentric ring layout on /tags

Tag archive pages

The sidebar browser

Pulling the system together

Improving the tag pages

Tag descriptions

Featured post highlight

Related topics row

Stats bar

Beyond the foundations

Full code listings

Designing the blog card and post hero

Treat `waitForTimeout` as a smell

The concentric ring layout on `/tags`