DEV Community: Roger Rajaratnam

Moving blog content to a private repository

Roger Rajaratnam — Fri, 04 Sep 2026 11:34:45 +0000

Original post: Moving blog content to a private repository

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

This site's source code is public. Anyone can see how the layouts work, how the
comment system is wired up, how the scheduled build fires. I want that to stay
open: it's useful to others and it keeps me honest about code quality.

What I don't want public is every unpublished draft sitting in the repository
weeks before it goes live. The content, meaning Markdown files, cover images,
and frontmatter, needed to move somewhere private without changing how the
site builds or deploys.

The constraint

Astro's content collections expect post files at a specific path. The collection
loader in src/content.config.ts points to collections/posts/:

loader: glob({ pattern: ["**/*.md", "!README.md"], base: "./collections/posts" }),

Whatever solution I chose, Astro needed to find Markdown files at that path at
build time. No loader changes, no path rewiring, no special plugins.

Why not a git submodule

The obvious answer is a git submodule: point collections/posts/ at a private
repository and let git handle the rest.

It works locally, but Netlify's build pipeline clones
submodules during its "preparing repo" stage, before the build command runs.
For a private submodule, Netlify needs SSH access to the repository. The way
it authenticates is through a deploy key, and GitHub deploy keys are scoped
to a single repository. The same key cannot be added to two repos.

Since Netlify's deploy key was already registered on the main site repository,
adding it to the content repository returned a "key already in use" error. You
can work around this with machine users or manually managed SSH keys, but it
felt like fighting the tooling rather than working with it.

The build-time clone approach

The simpler solution: skip submodules entirely and clone the private repository
as a build step. The content directory is gitignored in the main repository and
fetched fresh on every build.

The entire change is in netlify.toml:

[build]
  command = "git clone --depth 1 https://${GH_PAT}@github.com/sourcier/sourcier.uk-content.git collections/posts && rm -rf collections/posts/.git && astro build"
  publish = "dist"

Three commands chained together:

Clone the private content repository into collections/posts/ using a GitHub personal access token for authentication. --depth 1 skips history, since we only need the latest files.
Remove .git/ from the cloned directory. Without this, Netlify's secrets scanner detects the token in collections/posts/.git/config and fails the build. Removing the .git directory strips the credential before the scan runs.
Build the Astro site as normal. The content is in place and the collection loader picks it up without any configuration changes.

Diagram fallback for Dev.to. View the canonical article for the full version: https://sourcier.uk/blog/private-content-repo

Setting up the GitHub token

The token needs minimal permissions. A fine-grained personal access token scoped
to the content repository with read-only Contents access is sufficient:

Go to GitHub → Settings → Personal access tokens → Fine-grained tokens
Create a new token scoped to the content repository only
Grant Contents → Read-only permission
Add the token as GH_PAT in the Netlify dashboard under Site configuration → Environment variables

The token never appears in the repository. It's injected at build time through
the environment variable.

The .gitignore entry

Since the content is cloned at build time, the directory is gitignored in the
main repository:

# blog content (cloned from private repo at build time)
collections/posts/

Local development

For local development, clone the content repository once into collections/posts/:

git clone git@github.com:sourcier/sourcier.uk-content.git collections/posts

Because the directory is gitignored, the main repository doesn't track it. You
work inside collections/posts/ as its own git repo: commit content changes
there and push to the content repository's remote. The main site repo never
sees those files.

Running pnpm dev picks up the content from disk exactly as before. Nothing
changes about the local workflow except that content commits go to a different
remote.

VS Code workspace setup

With two git repositories on disk, a VS Code multi-root workspace makes the
local setup feel intentional rather than awkward. The .code-workspace file at
the root of the site repository adds collections/posts as a second folder:

{
  "folders": [
    { "name": "sourcier.uk (site)", "path": "." },
    { "name": "sourcier.uk (content)", "path": "collections/posts" }
  ],
  "settings": {
    "terminal.integrated.cwd": "${workspaceFolder:sourcier.uk (site)}"
  }
}

Opening this file gives you both repositories in a single VS Code window. The
Source Control panel shows two separate entries, one for each repo, so staging,
committing, and pushing content changes is completely independent from site
changes. The file explorer shows both roots side by side.

The settings block is optional, but terminal.integrated.cwd is worth adding.
Without it, VS Code opens terminals relative to whichever file is currently
active, which means a terminal opened while editing a post drops you into
collections/posts/ instead of the project root where pnpm dev and other site
commands live.

Because collections/posts/ is gitignored by the site repo, VS Code won't
accidentally stage content files as part of a site commit. Each repository
manages its own history, and the workspace just surfaces both at once.

Triggering deploys from the content repository

Pushing to the content repository doesn't trigger a Netlify deploy: the main
site repository hasn't changed, so Netlify has nothing to react to.

The fix is a Netlify build hook: a URL you POST to kick off a build regardless
of code changes.

In the Netlify dashboard go to Site configuration → Build hooks and create a new hook. Copy the URL.
In the content repository, add that URL as a secret named NETLIFY_BUILD_HOOK under Settings → Secrets and variables → Actions.
Add a workflow to the content repository:

name: Deploy site

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Netlify build
        run: curl -X POST -d '{}' "${{ secrets.NETLIFY_BUILD_HOOK }}"

Now every push to main in the content repository fires a full Netlify build,
which clones the latest content and rebuilds the site.

What this gives you

Drafts stay private. Unpublished posts, half-written ideas, and cover images
for future content don't appear in the public repository's commit history.

The site code stays open. Layouts, components, serverless functions, and
configuration remain public and visible.

The build is identical. Astro's content collection loader doesn't know or
care where the files came from. They're at the expected path, and the schema
validates them the same way.

No infrastructure changes. No new services, no CMS, no API layer. It's
two git repositories and a one-line build command.

Gating the preview branch behind a passcode

The build hook workflow targets main, so the public site auto-deploys on
content changes. But the preview branch, the one that includes drafts, is
also a public URL. Anyone who finds or guesses preview--sourcieruk.netlify.app
can read unpublished posts.

The solution is a Netlify Edge Function that intercepts every request on the
preview deploy and serves a passcode form until the visitor authenticates.

import type { Config, Context } from "@netlify/edge-functions";

const COOKIE_NAME = "preview_auth";
const COOKIE_MAX_AGE = 60 * 60 * 24 * 7; // 7 days

async function computeToken(passcode: string): Promise<string> {
  const encoder = new TextEncoder();
  const key = await crypto.subtle.importKey(
    "raw",
    encoder.encode(passcode),
    { name: "HMAC", hash: "SHA-256" },
    false,
    ["sign"],
  );
  const signature = await crypto.subtle.sign(
    "HMAC",
    key,
    encoder.encode("preview_authenticated"),
  );
  return btoa(String.fromCharCode(...new Uint8Array(signature)));
}

export default async function previewAuth(request: Request, context: Context) {
  const passcode = Netlify.env.get("PREVIEW_PASSCODE");

  // No passcode configured — pass through (production unaffected)
  if (!passcode) return context.next();

  const url = new URL(request.url);
  const expectedToken = await computeToken(passcode);
  const cookies = parseCookies(request.headers.get("cookie") ?? "");

  if (cookies[COOKIE_NAME] === expectedToken) return context.next();

  if (request.method === "POST") {
    const body = await request.formData();
    const submitted = body.get("code")?.toString() ?? "";

    if (submitted === passcode) {
      const redirectTo = sanitizeRedirect(
        url.searchParams.get("redirect") ?? "/",
        url.origin,
      );
      const response = new Response(null, {
        status: 302,
        headers: { location: redirectTo },
      });
      response.headers.append(
        "set-cookie",
        `${COOKIE_NAME}=${expectedToken}; HttpOnly; Secure; SameSite=Strict; Max-Age=${COOKIE_MAX_AGE}; Path=/`,
      );
      return response;
    }

    return new Response(renderForm(url, true), { status: 401, ... });
  }

  return new Response(renderForm(url, false), { status: 401, ... });
}

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

A few things worth calling out:

The cookie stores an HMAC, not the passcode. The passcode is used as an
HMAC key to sign the string "preview_authenticated". The resulting signature
goes into the cookie. The raw passcode never leaves the server: if the cookie
is stolen it reveals nothing about the code, and it's valid only on this origin.

The cookie is HttpOnly, Secure, and SameSite=Strict. It can't be read
by JavaScript, only travels over HTTPS, and is never sent cross-site.

Production is unaffected by design. The function checks for a
PREVIEW_PASSCODE environment variable and no-ops immediately if it isn't set.
The variable is scoped to branch deploys only in the Netlify dashboard, so the
production site never even evaluates the auth logic.

Changing the passcode invalidates all sessions instantly. The HMAC changes
when the key changes, so existing cookies no longer match. No session store, no
token revocation list.

To wire it up:

In the Netlify dashboard: Site configuration → Environment variables → Add variable
- Key: PREVIEW_PASSCODE
- Value: a short memorable code, or generate one with openssl rand -base64 12
- Scope: Branch deploys only
Install @netlify/edge-functions as a devDependency, this gives TypeScript the types locally. Netlify's edge runtime provides the module automatically at deploy time, so it only needs to be present for type checking:

   pnpm add -D @netlify/edge-functions

Netlify auto-discovers edge functions in netlify/edge-functions/, no extra netlify.toml configuration is needed. The path is declared inside the function itself via export const config: Config = { path: "/*" }.

The full edge function (including the form renderer) is in the
site repository.

Purging content from the existing git history

Moving files to a private repository stops future content from appearing in the
public repo. But every post you committed before the split is still visible in
the history. Anyone can check out an older commit and read all your drafts.

The tool for this is git filter-repo.
It rewrites history by replaying every commit through a filter, in this case,
"keep everything except collections/posts/":

brew install git-filter-repo
git filter-repo --path collections/posts --invert-paths --force

--path identifies the directory to target. --invert-paths turns the filter
around: instead of keeping only that path, it removes it. --force is required
because the repo has a remote, and git-filter-repo refuses to run on repos with
remotes unless you explicitly confirm intent.

After the rewrite, git-filter-repo removes the origin remote as a safety
measure. Add it back and force push:

git remote add origin git@github.com:sourcier/sourcier.uk-content.git
git push --force origin main

If you have other branches (a preview branch, for example), recreate them
from the rewritten main and force push those too:

git branch -D preview
git checkout -b preview
git push --force origin preview
git checkout main

The force push replaces every ref on GitHub with the rewritten chain. The old
SHAs, and the content blobs they referenced, are no longer accessible via the
public repository.

One caveat: GitHub caches some data, such as pull request diffs and web UI
caches, that may retain stale content for a period after the force push. For a
personal repo with no open PRs this expires naturally, but you can contact
GitHub Support to request an immediate cache purge if needed.

What to watch for

README.md in the content repository. Every GitHub repository gets a
README.md at the root. When the content repository is cloned into
collections/posts/, that README.md lands in the loader's base directory.
Astro's glob loader picks it up and tries to validate it against the post
schema, which fails immediately because it has no title, no pubDate, none
of the required frontmatter fields.

The fix is a negation pattern in the glob loader:

loader: glob({ pattern: ["**/*.md", "!README.md"], base: "./collections/posts" }),

This excludes any file named README.md regardless of where the build runs
from. Without this, the build works fine locally (where the directory contains
only posts) but fails on Netlify every time.

Two repositories to manage. Content and code live in separate repos. When
a code change depends on a content change (a new frontmatter field, for
example), both repos need to be updated and the deploy needs both changes
present. In practice this hasn't been an issue: schema changes are infrequent
and easy to coordinate.

Token expiry. Fine-grained tokens have an expiration date. If the token
expires, builds fail silently with a clone authentication error. Set a calendar
reminder or use a long-lived token if your threat model allows it.

Branch alignment. The build command clones the main branch of the content
repository. If you work on a content branch, you'll need to adjust the clone
command or merge to main before deploying.

Working on something similar?

If you're building a content pipeline, managing private content alongside public
code, or setting up deploy automation, I'm available for consulting.
Get in touch via the contact page and tell me what you're working on.

Web analytics on a static Astro blog

Roger Rajaratnam — Fri, 04 Sep 2026 11:34:23 +0000

Original post: Web analytics on a static Astro blog

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

A blog without analytics is guesswork. You have no idea whether anyone is reading,
which posts land, or where people drop off. For a personal site that's fine for
a while, but eventually you want data.

The question for a statically-generated blog isn't whether to add analytics,
it's which ones, and how to avoid polluting your development logs with noise.

Picking a tool

There are several free options that work well with an Astro/Netlify stack:

Tool	Cost	Notes
PostHog	1M events/month free	Product analytics + web analytics; generous free tier
GoatCounter	Free for public sites	Lightweight, no cookies, no self-hosting needed
GA4	Fully free	Full-featured but requires a cookie consent banner
Cloudflare Web Analytics	Free	Zero JS, but requires your DNS on Cloudflare
Netlify Analytics	$9/month	Server-side, zero JS impact on the page
Umami	Free (self-hosted)	Privacy-first, but needs a server to run on

I went with PostHog for a few reasons:

The free tier covers 1 million events per month.
It tracks page views, but also gives you session recordings, funnels, and feature flags if you ever want them.
The EU cloud (eu.i.posthog.com) means data stays in Europe, which simplifies GDPR considerations.
The setup is a small script, no npm package, no build step changes.

The implementation

The analytics snippet lives in two places: a conditional <script> tag in
src/layouts/BaseLayout.astro, which wraps every page on the site, and a
small vendor bootstrap file in public/scripts/posthog-bootstrap.js.

Production-only loading

The most important constraint: the snippet should only load in production. In
local development, PostHog would record your own page views, skew the data, and
clutter the network panel with requests to an external service.

Astro exposes import.meta.env.PROD, a boolean that is true during a
production build and false during astro dev. Wrapping the script tag in a
conditional expression gates it cleanly:

{
  import.meta.env.PROD && (
    <script
      src="/scripts/posthog-bootstrap.js"
      data-posthog-key={import.meta.env.PUBLIC_POSTHOG_KEY}
      data-posthog-host={
        import.meta.env.PUBLIC_POSTHOG_HOST || "https://eu.i.posthog.com"
      }
      defer
    />
  )
}

In development the entire block evaluates to nothing, so no script tag is
emitted and no network requests are made.

Why an external file instead of `define:vars`

The first version of this wired PostHog's project key straight into an inline
script using Astro's define:vars directive, which injects server-side
variables into an inline <script> block at build time. That worked, but
PostHog's loader snippet is a wall of minified vendor JavaScript, and Prettier
reformats every .astro file on save. Having that vendor blob embedded
directly inside the component meant every save reflowed it along with the
rest of the file, turning a one-line stub into unreadable diffs and risking a
subtle edit to code nobody should be hand-editing.

Moving the snippet into its own .js file under public/ fixes the
build-time half of the problem: Astro serves anything in public/ as a
static asset without bundling or transforming it, so there's no chance of the
Astro compiler mangling the vendor code. It also confines Prettier's
formatting to a single vendor file that isn't meant to be hand-edited, rather
than fighting with the surrounding .astro template on every save. Since an
external script has no access to the Astro component's scope, configuration
has to travel through data-* attributes instead of define:vars, read back
out with document.currentScript.dataset:

const currentScript = document.currentScript;

if (
  currentScript instanceof HTMLScriptElement &&
  currentScript.dataset.posthogKey
) {
  const posthogKey = currentScript.dataset.posthogKey;
  const posthogHost =
    currentScript.dataset.posthogHost || "https://eu.i.posthog.com";

  /* eslint-disable */
  !function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+" (stub)"},o="capture identify alias people.set people.set_once set_config register register_once unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled onFeatureFlags getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures getActiveMatchingSurveys getSurveys onSessionId".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
  posthog.init(posthogKey, { api_host: posthogHost });
  /* eslint-enable */
}

The minified stub is PostHog's own array.js
loader, copied verbatim from their documentation. It bootstraps a minimal
stub synchronously, then loads the full library asynchronously from the
PostHog CDN. The eslint-disable comment matters too: the vendor code
doesn't follow this project's lint rules, and it shouldn't be rewritten to
satisfy them.

Variables prefixed with PUBLIC_ in Astro are safe to expose this way.
PostHog's project key is designed to be public: it appears in the page
source of every site using PostHog. The only real requirement is that it
never gets hardcoded in source control, which the environment variables
below take care of.

Environment variables

Two environment variables are required:

Variable	Value
`PUBLIC_POSTHOG_KEY`	Your PostHog project API key (`phc_...`)
`PUBLIC_POSTHOG_HOST`	`https://eu.i.posthog.com` (EU) or `https://us.i.posthog.com` (US)

Getting the key

Sign up at posthog.com, create a project, and copy the
API key from Project Settings → Project API Key. It starts with phc_.

Local development

Create a .env file in the project root (already in .gitignore via
Astro's default setup):

PUBLIC_POSTHOG_KEY=phc_your_key_here
PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com

Even with these set locally, the snippet won't fire. The import.meta.env.PROD
check takes care of that.

GitHub Actions

This site doesn't build on Netlify. CI builds the static site in GitHub
Actions, and Netlify just deploys the pre-built dist/ folder with
netlify deploy --no-build, so the environment variables that get baked into
the HTML have to live as GitHub Actions repository secrets
(Settings → Secrets and variables → Actions), not in the Netlify
dashboard. The build step in .github/workflows/ci.yml passes them through
explicitly:

- run: pnpm build
  env:
    SHOW_DRAFTS: "false"
    PUBLIC_STRIPE_PUBLISHABLE_KEY: ${{ secrets.PUBLIC_STRIPE_PUBLISHABLE_KEY }}
    PUBLIC_POSTHOG_KEY: ${{ secrets.PUBLIC_POSTHOG_KEY }}
    PUBLIC_POSTHOG_HOST: ${{ secrets.PUBLIC_POSTHOG_HOST }}

One thing this setup doesn't solve yet: the preview build
(SHOW_DRAFTS: "true", deployed to the passcode-protected preview alias)
uses the exact same PostHog secrets as the production build. Every preview
and branch deploy reports into the same PostHog project as production, so
draft traffic and my own review sessions on the preview alias mix in with
real visitor data. Splitting them would mean a second PostHog project and a
second pair of secrets scoped per build job, which isn't worth the overhead
yet for a personal blog.

What you get out of the box

Once deployed, PostHog automatically captures:

Page views: URL, referrer, and UTM parameters
Sessions: grouping page views by visitor session
Device and browser: OS, browser, screen resolution
Geography: country and city, derived from IP, not stored

The dashboard is ready to use from the first page view with no configuration
beyond the snippet.

A note on cookie consent

PostHog uses cookies and local storage by default to identify returning
visitors across sessions. Depending on your jurisdiction and audience, this
may require a cookie consent banner.

This site doesn't have one yet. posthog.init() runs with PostHog's
defaults, no persistence override, which sets a cookie on the first page
view. For a personal blog with a UK/EU audience, the strictest interpretation
of GDPR would require consent before setting analytics cookies, so this is a
compliance gap I'm accepting for now rather than one I've solved.

A pragmatic middle ground, if I revisit this, is configuring PostHog to use
persistence: 'memory' to avoid setting any cookies, at the cost of losing
cross-session identity:

posthog.init(posthogKey, {
  api_host: posthogHost,
  persistence: "memory",
});

Page views and event counts would still be accurate, I'd just lose the
ability to track individual user journeys across multiple sessions.

A custom 404 page

Roger Rajaratnam — Thu, 27 Aug 2026 15:23:09 +0000

Original post: A custom 404 page

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

A 404 page is easy to forget. You build the real pages, you wire up the routes, and the 404 sits at the bottom of the list — "I'll do that later." Later arrives when someone pastes a broken link, follows a dead URL from an old tweet, or misremembers your slug. What they see in that moment is not nothing: it is a page, it represents your site, and it should look like it belongs there.

In Astro, building one is trivial. The interesting part is the design.

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

Click the expand icon to view it fullscreen.

How Astro handles 404s

Create a file at src/pages/404.astro and Astro will render it as /404.html in the static build output. Netlify serves that file automatically for any path that doesn't match a real route. No configuration required — it works out of the box.

The page has access to everything a normal page does: layouts, components, styles, the full design system.

Skipping the standard layout

The first decision was whether to use the PageHero component that every other page uses. It gives you a kicker, a title, a subtitle, breadcrumbs, and optional cover image — which is fine for real content, but overkill for an error page. A 404 doesn't need breadcrumbs. It doesn't need a cover image. It needs to tell the user what happened and give them somewhere to go.

Dropping PageHero frees up the layout, but "somewhere to go" turned out to be more than one link. Rather than a single centred block, the page ended up as two sections: a hero panel that states the problem, and a grid of cards underneath that gives the visitor several concrete next steps.

The hero panel

The hero is a self-contained page-panel with a two-column grid on tablet and up: the outlined number on the left, the eyebrow, heading, copy, and buttons on the right. Below that breakpoint it stacks into a single column.

.not-found__panel {
  display: grid;
  gap: 1.5rem;
  align-items: center;
  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-primary) 4%, var(--surface-elevated)) 0%,
      var(--surface-elevated) 62%
    ),
    var(--surface-elevated);

  @media (min-width: 768px) {
    grid-template-columns: minmax(9rem, 0.6fr) minmax(0, 1.4fr);
    gap: 2rem;
  }
}

The gradients are subtle: a hint of the pink accent bleeding in from the left, a hint of the secondary green in the top-right corner, layered over the same --surface-elevated token every other panel on the site uses, so the page still looks like it belongs here rather than a one-off design experiment.

The number

The visual anchor is the "404" itself. The approach here is outlined text: transparent fill, a pink stroke, with a faint offset copy behind it to create a ghost effect.

.not-found__number {
  font-family: "Barlow Condensed", sans-serif;
  font-size: clamp(6rem, 18vw, 12rem);
  font-weight: 900;
  line-height: 0.9;
  letter-spacing: -0.03em;
  color: transparent;
  -webkit-text-stroke: 2px var(--accent-primary);
  position: relative;

  &::after {
    content: "404";
    position: absolute;
    inset: 0;
    color: rgba(var(--accent-primary-rgb), 0.07);
    -webkit-text-stroke: 0;
    transform: translate(6px, 6px);
    z-index: -1;
  }
}

-webkit-text-stroke has broad browser support and the effect is subtle enough that it degrades gracefully if it didn't. The ::after pseudo-element repeats the text, shifts it six pixels, and uses a very low-opacity solid fill — it looks like a shadow but reads as intentional.

clamp(6rem, 18vw, 12rem) handles the responsive sizing without a media query: small on mobile, fluid in the middle, capped once the panel's own column width takes over on wider screens.

The copy and the primary actions

Inside the right-hand column, there's a small eyebrow above the heading, a two-line explanation, and two calls to action styled with the site's existing Bulma button classes rather than anything bespoke:

<p class="not-found__eyebrow">Page not found</p>
<h1 class="not-found__heading">Nothing here.</h1>
<p class="not-found__sub">
  That URL may have moved, been deleted, or never existed. Start
  from the homepage, jump into the latest writing, or pick the guide
  that matches where you are now.
</p>
<div class="not-found__actions">
  <a href="/" class="button is-primary is-medium">Home</a>
  <a href="/blog" class="button is-light is-medium">Browse the blog</a>
</div>

"Nothing here." is short deliberately. "Page not found" is accurate but passive, so it moved to a small uppercase eyebrow instead, and the <h1> gets to be the blunt version. The is-primary button (solid pink) covers the obvious escape route; is-light gives a lower-commitment second option for someone who just wants to keep reading.

Try these instead: guides and core pages

Two buttons cover the obvious cases, but a 404 is also a reasonable place to hand someone a menu. Below the hero panel sits a second section, labelled "Try these instead", with a card grid mixing two sources:

The site's audienceGuides data — the same array that powers the guide landing pages — mapped straight into cards.
A short, hard-coded list of core pages: Blog, About, Contact.

{audienceGuides.map((guide) => (
  <article class="not-found-card not-found-card--guide">
    <p class="not-found-card__eyebrow">Guide</p>
    <h3 class="not-found-card__title">{guide.title}</h3>
    <p class="not-found-card__body">{guide.summary}</p>
    <a href={guide.href} class="not-found-card__cta">Open the guide</a>
  </article>
))}
{corePages.map((page) => (
  <article class="not-found-card">
    <p class="not-found-card__eyebrow">Page</p>
    <h3 class="not-found-card__title">{page.label}</h3>
    <p class="not-found-card__body">{page.description}</p>
    <a href={page.href} class="not-found-card__cta">Open {page.label}</a>
  </article>
))}

Reusing audienceGuides instead of duplicating the guide titles and blurbs means the 404 page can't drift out of sync with the guides landing page: if a guide is renamed or its summary is rewritten, this grid picks it up automatically. The two card types are visually distinguished by a thin top border: guide cards use --accent-secondary, core page cards use --accent-primary.

Accessibility notes

The number carries aria-hidden="true", since it's decoration and the <h1> already says what happened, so a screen reader doesn't need to announce "404" on top of "Nothing here." Both sections use aria-labelledby pointing at their own heading id (not-found-heading, not-found-paths-heading) rather than a generic aria-label, so the accessibility tree gets the same heading text a sighted reader sees, instead of a second, possibly diverging, piece of copy to maintain.

Full code listing

---
import BaseLayout from "../layouts/BaseLayout.astro";
import { audienceGuides } from "../data/audienceGuides";

const corePages = [
  {
    href: "/blog",
    label: "Blog",
    description: "\"Start with the latest writing and browse by topic.\","
  },
  {
    href: "/about",
    label: "About",
    description: "\"Find out who I help and the kind of work I do.\","
  },
  {
    href: "/contact",
    label: "Contact",
    description: "\"Get in touch about mentoring, consulting, or a question.\","
  },
];
---

<BaseLayout
  pageTitle="Page not found — Sourcier"
  description="The page you're looking for doesn't exist."
>
  <div class="not-found flow-section flow-section--loose">
    <div class="container is-max-desktop">
      <section class="not-found__hero" aria-labelledby="not-found-heading">
        <div class="page-panel not-found__panel">
          <div class="not-found__number" aria-hidden="true">404</div>
          <div class="not-found__copy">
            <p class="not-found__eyebrow">Page not found</p>
            <h1 class="not-found__heading" id="not-found-heading">
              Nothing here.
            </h1>
            <p class="not-found__sub">
              That URL may have moved, been deleted, or never existed. Start
              from the homepage, jump into the latest writing, or pick the guide
              that matches where you are now.
            </p>
            <div class="not-found__actions">
              <a href="/" class="button is-primary is-medium">Home</a>
              <a href="/blog" class="button is-light is-medium">
                Browse the blog
              </a>
            </div>
          </div>
        </div>
      </section>

      <section
        class="not-found__paths"
        aria-labelledby="not-found-paths-heading"
      >
        <p class="section-label">Try these instead</p>
        <h2 class="not-found__paths-heading" id="not-found-paths-heading">
          Start from a guide or a core page
        </h2>
        <div class="not-found__grid">
          {
            audienceGuides.map((guide) => (
              <article class="not-found-card not-found-card--guide">
                <p class="not-found-card__eyebrow">Guide</p>
                <h3 class="not-found-card__title">{guide.title}</h3>
                <p class="not-found-card__body">{guide.summary}</p>
                <a href={guide.href} class="not-found-card__cta">
                  Open the guide
                </a>
              </article>
            ))
          }
          {
            corePages.map((page) => (
              <article class="not-found-card">
                <p class="not-found-card__eyebrow">Page</p>
                <h3 class="not-found-card__title">{page.label}</h3>
                <p class="not-found-card__body">{page.description}</p>
                <a href={page.href} class="not-found-card__cta">
                  Open {page.label}
                </a>
              </article>
            ))
          }
        </div>
      </section>
    </div>
  </div>
</BaseLayout>

<style lang="scss">
  .not-found {
    padding: 0 1.5rem;
  }

  .not-found__panel {
    display: grid;
    gap: 1.5rem;
    align-items: center;
    margin-bottom: 3rem;
    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-primary) 4%, var(--surface-elevated)) 0%,
        var(--surface-elevated) 62%
      ),
      var(--surface-elevated);

    @media (min-width: 768px) {
      grid-template-columns: minmax(9rem, 0.6fr) minmax(0, 1.4fr);
      gap: 2rem;
    }
  }

  .not-found__number {
    font-family: "Barlow Condensed", sans-serif;
    font-size: clamp(6rem, 18vw, 12rem);
    font-weight: 900;
    line-height: 0.9;
    letter-spacing: -0.03em;
    color: transparent;
    -webkit-text-stroke: 2px var(--accent-primary);
    user-select: none;
    position: relative;

    &::after {
      content: "404";
      position: absolute;
      inset: 0;
      color: rgba(var(--accent-primary-rgb), 0.07);
      -webkit-text-stroke: 0;
      transform: translate(6px, 6px);
      z-index: -1;
    }
  }

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

  .not-found__heading {
    margin: 0;
    font-family: "Barlow Condensed", sans-serif;
    font-size: clamp(2rem, 5vw, 3.5rem);
    line-height: 0.95;
    text-transform: uppercase;
    color: var(--text-primary);
  }

  .not-found__sub {
    margin: 0.95rem 0 0;
    max-width: 58ch;
    line-height: 1.75;
    color: var(--text-muted);
  }

  .not-found__actions {
    display: flex;
    flex-wrap: wrap;
    gap: 0.75rem;
    margin-top: 1.4rem;
  }

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

  .not-found__grid {
    display: grid;
    gap: 1rem;

    @media (min-width: 768px) {
      grid-template-columns: repeat(3, minmax(0, 1fr));
    }
  }

  .not-found-card {
    display: flex;
    flex-direction: column;
    gap: 0.85rem;
    min-height: 100%;
    padding: 1.4rem;
    border: 1px solid var(--border-subtle);
    border-top: 3px solid var(--accent-primary);
    border-radius: var(--radius-panel);
    background:
      linear-gradient(
        160deg,
        color-mix(in srgb, var(--accent-primary) 4%, var(--surface-elevated)) 0%,
        var(--surface-elevated) 62%
      ),
      var(--surface-elevated);
    box-shadow: var(--shadow-panel);
    transition:
      transform 0.18s ease,
      box-shadow 0.18s ease,
      border-color 0.18s ease;

    &:hover {
      transform: translateY(-3px);
      box-shadow: var(--shadow-lift);
    }
  }

  .not-found-card--guide {
    border-top-color: var(--accent-secondary);
    background:
      radial-gradient(
        circle at top right,
        color-mix(in srgb, var(--accent-secondary) 12%, transparent) 0%,
        transparent 34%
      ),
      linear-gradient(
        160deg,
        color-mix(in srgb, var(--accent-primary) 3%, var(--surface-elevated)) 0%,
        var(--surface-elevated) 62%
      ),
      var(--surface-elevated);
  }

  .not-found-card__eyebrow {
    margin: 0;
    font-family: "Barlow Condensed", sans-serif;
    font-size: 0.78rem;
    font-weight: 700;
    letter-spacing: 0.1em;
    text-transform: uppercase;
    color: var(--text-muted);
  }

  .not-found-card--guide .not-found-card__eyebrow {
    color: var(--accent-secondary);
  }

  .not-found-card__title {
    margin: 0;
    font-family: "Barlow Condensed", sans-serif;
    font-size: 1.15rem;
    line-height: 1.05;
    text-transform: uppercase;
    color: var(--text-primary);
  }

  .not-found-card__body {
    margin: 0;
    line-height: 1.65;
    color: var(--text-muted);
  }

  .not-found-card__cta {
    margin-top: auto;
    display: inline-flex;
    align-items: center;
    padding-block: 0.75rem;
    font-family: "Barlow Condensed", sans-serif;
    font-size: 0.86rem;
    font-weight: 700;
    letter-spacing: 0.08em;
    text-transform: uppercase;
    color: var(--accent-primary);
    text-decoration: none;
  }

  .not-found-card--guide .not-found-card__cta {
    color: var(--accent-secondary);
  }
</style>

What Netlify does with it

Netlify serves 404.html for any unmatched route. No netlify.toml redirect rule needed, no custom headers — it just works. Deploy it and broken links get your page instead of the browser default.

Paginating a Blog in Astro

Roger Rajaratnam — Tue, 25 Aug 2026 12:09:49 +0000

Original post: Paginating a Blog in Astro

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

Most blog tutorials reach for paginate() — Astro's built-in helper — and call it done. It works, but the URLs it produces (/blog/2, /blog/3) aren't great for SEO. Search engines prefer a clear signal that these are pages of a list, not individual resources. /blog/page/2 communicates that explicitly.

This post walks through how I built pagination on this site: clean URLs, no client-side JavaScript, placeholder cards, and a reusable BlogGrid component.

The URL structure

The target structure:

/blog           → page 1 (canonical)
/blog/page/2    → page 2
/blog/page/3    → page 3

Page 1 lives at /blog with no page number — it's the canonical listing URL and the one that gets linked to from everywhere. Pages 2 and beyond use /blog/page/N to signal clearly that they are paginated continuations.

I deliberately avoided /blog/1 for page 1. A URL like /blog/1 implies there's a post with the ID 1, or that the canonical URL is somehow different from /blog. Neither is true.

Why not `paginate()`?

Astro's paginate() is great for getting started. You export getStaticPaths from a [...page].astro file, pass your content collection and a page size, and Astro generates all the pages. The catch is the URL pattern it produces:

/blog           → page 1
/blog/2         → page 2
/blog/3         → page 3

That flat structure is fine functionally, but /blog/page/2 is more semantically correct and is the pattern recommended by Google for paginated content. To get it with Astro you need to take back control of routing.

Two route files instead of one

Rather than fighting paginate(), I use two separate route files:

src/pages/blog/index.astro handles page 1. It's a static page — no getStaticPaths needed — that fetches all posts, slices the first page, and renders the grid.

src/pages/blog/page/[page].astro handles pages 2 and above. It uses getStaticPaths to generate one static page per remaining page number.

// src/pages/blog/page/[page].astro
export async function getStaticPaths() {
  const PAGE_SIZE = 9;
  const allPosts = (await getCollection("posts"))
    .filter(isPublished)
    .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());
  const totalPages = Math.ceil(allPosts.length / PAGE_SIZE);
  return Array.from({ length: totalPages - 1 }, (_, i) => ({
    params: { page: String(i + 2) },
  }));
}

The length: totalPages - 1 is key — page 1 is handled by index.astro, so this file only generates pages 2 through N. Attempting to generate page 1 here would create a conflicting route at /blog/page/1.

isPublished is the same helper from the scheduled publishing post — it filters out drafts and future-dated posts outside of dev mode, so archive pages never leak unpublished content.

Notice that getStaticPaths only returns params, not props. The actual page data — the slice of posts, currentPage, prevUrl, nextUrl — is recomputed in the component script below, using Astro.params.page:

const PAGE_SIZE = 9;
const currentPage = Number(Astro.params.page);

const allPosts = (await getCollection("posts"))
  .filter(isPublished)
  .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());

const totalPages = Math.ceil(allPosts.length / PAGE_SIZE);
const posts = allPosts.slice(
  (currentPage - 1) * PAGE_SIZE,
  currentPage * PAGE_SIZE,
);
const prevUrl = currentPage === 2 ? "/blog" : `/blog/page/${currentPage - 1}`;
const nextUrl =
  currentPage < totalPages ? `/blog/page/${currentPage + 1}` : null;

That means the same fetch-sort-slice logic is duplicated three times across index.astro, getStaticPaths, and the component script in [page].astro. It's a small DRY violation, but getStaticPaths runs in an isolated build-time context before the rest of the file executes, so there's no way to share the computed allPosts array between it and the component body without a separate module-level helper. For three call sites doing one cheap array operation, the duplication was the simpler trade-off.

A shared BlogGrid component

Both route files render the same grid. Rather than duplicating the markup, I extracted it into src/components/BlogGrid.astro, which accepts these props:

interface Props {
  posts: CollectionEntry<"posts">[];
  currentPage: number;
  totalPages: number;
  prevUrl: string | null;
  nextUrl: string | null;
  paginationBase?: string;
  sectionLabel?: string;
  sectionTitle?: string;
  sectionDescription?: string;
}

It renders the post grid, placeholder cards, and pagination controls. Both index.astro and [page].astro import it and pass their data through, along with a section label and heading so the same component reads correctly whether it's showing "Recent articles" on page 1 or "Posts on page 2" further into the archive. paginationBase is what lets the tag system reuse this exact component for paginated tag pages — it swaps /blog/page/N for /tags/<tag>/N without any other change.

Placeholder cards for a half-full grid

While the post count is low, a 9-post grid with only 4 real posts on the last page would look half-empty. Placeholder cards fill the remaining slots instead of leaving obvious gaps.

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

Click the expand icon to view it fullscreen.

The grid is responsive — two columns on tablet, three on desktop — so a placeholder count that's correct for one breakpoint can be wrong for the other. BlogGrid.astro computes both independently, then works out how many placeholders are needed at both breakpoints, only one, or neither:

const showGhostCards = currentPage === totalPages;
const TABLET_COLS = 2;
const DESKTOP_COLS = 3;
const tabletGhostCount = showGhostCards
  ? (TABLET_COLS - (posts.length % TABLET_COLS)) % TABLET_COLS
  : 0;
const desktopGhostCount = showGhostCards
  ? (DESKTOP_COLS - (posts.length % DESKTOP_COLS)) % DESKTOP_COLS
  : 0;
const sharedGhostCount = Math.min(tabletGhostCount, desktopGhostCount);
const tabletOnlyGhostCount = tabletGhostCount - sharedGhostCount;
const desktopOnlyGhostCount = desktopGhostCount - sharedGhostCount;

Only the last page ever gets placeholders — every other page is a full row at both breakpoints. The three resulting counts each render into a differently-classed cell (--tablet-up, --tablet-only, --desktop-only) so CSS media queries can show or hide the right ones without any JavaScript recalculating the layout on resize.

I deliberately kept BlogCardPlaceholder.astro static rather than reaching for an animated loading skeleton. These cards aren't hiding content that's still loading — the grid is fully rendered at build time, there's nothing to wait for. A shimmering skeleton would be actively misleading here, so the placeholder is just a dashed-border card with a quiet "More posts coming soon" label:

<div class="card card__blog card__blog--placeholder" aria-hidden="true">
  <div class="card__blog--placeholder-inner">
    <span class="card__blog--placeholder-label">More posts coming soon</span>
  </div>
</div>

aria-hidden="true" and pointer-events: none keep it invisible to screen readers and non-interactive, since there's nothing behind it to click or announce.

Pagination controls

The navigation sits below the grid and only renders when there's more than one page. Previous and next links use the prevUrl/nextUrl props passed in from the route files. Page number buttons are generated from totalPages, routed through a small pageUrl() helper so the same markup works for both /blog/page/N and a tag page's paginationBase:

function pageUrl(n: number) {
  if (paginationBase) {
    return n === 1 ? paginationBase : `${paginationBase}/${n}`;
  }
  return n === 1 ? "/blog" : `/blog/page/${n}`;
}

{Array.from({ length: totalPages }).map((_, i) => {
  const n = i + 1;
  return (
    <a href={pageUrl(n)} aria-current={n === currentPage ? "page" : undefined}>
      {n}
    </a>
  );
})}

The n === 1 branch ensures the first page button always links to /blog (or the tag's base URL), never /blog/page/1.

Disabled states on Previous/Next use aria-disabled and pointer-events: none rather than swapping <a> for <span>, which keeps the DOM structure consistent across all pages.

What this produces

At build time, Astro generates:

dist/blog/index.html        ← page 1
dist/blog/page/2/index.html ← page 2 (when posts > 9)
dist/blog/page/3/index.html ← page 3 (when posts > 18)

Everything is static HTML. No client-side JavaScript, no API calls, no hydration — the pagination just works as links between pre-rendered pages.

As more posts are published, the grid fills naturally. Once 10 posts exist, page 2 appears automatically at the next build.

Full code listing

---
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 BlogGrid from "../../../components/BlogGrid.astro";
import BlogTagCloud from "../../../components/BlogTagCloud.astro";

export async function getStaticPaths() {
  const PAGE_SIZE = 9;
  const allPosts = (await getCollection("posts"))
    .filter(isPublished)
    .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());
  const totalPages = Math.ceil(allPosts.length / PAGE_SIZE);
  return Array.from({ length: totalPages - 1 }, (_, i) => ({
    params: { page: String(i + 2) },
  }));
}

const PAGE_SIZE = 9;
const currentPage = Number(Astro.params.page);

const allPosts = (await getCollection("posts"))
  .filter(isPublished)
  .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());

const totalPages = Math.ceil(allPosts.length / PAGE_SIZE);
const posts = allPosts.slice(
  (currentPage - 1) * PAGE_SIZE,
  currentPage * PAGE_SIZE,
);
const prevUrl = currentPage === 2 ? "/blog" : `/blog/page/${currentPage - 1}`;
const nextUrl =
  currentPage < totalPages ? `/blog/page/${currentPage + 1}` : null;
---

<BaseLayout pageTitle={`Blog — Page ${currentPage} — Sourcier`}>
  <PageHero kicker="Writing" title="Blog" subtitle="..." />

  <BlogGrid
    posts={posts}
    currentPage={currentPage}
    totalPages={totalPages}
    prevUrl={prevUrl}
    nextUrl={nextUrl}
    sectionLabel="Archive"
    sectionTitle={`Posts on page ${currentPage}`}
    sectionDescription={`Page ${currentPage} of ${totalPages} from the blog archive.`}
  />

  <BlogTagCloud />
  <MailingListCTA />
</BaseLayout>

---
import type { CollectionEntry } from "astro:content";
import BlogPost from "./BlogPost.astro";
import BlogCardPlaceholder from "./BlogCardPlaceholder.astro";
import readingTime from "reading-time";

interface Props {
  posts: CollectionEntry<"posts">[];
  currentPage: number;
  totalPages: number;
  prevUrl: string | null;
  nextUrl: string | null;
  paginationBase?: string;
  sectionLabel?: string;
  sectionTitle?: string;
  sectionDescription?: string;
}

const { posts, currentPage, totalPages, prevUrl, nextUrl, paginationBase } =
  Astro.props;

const showGhostCards = currentPage === totalPages;
const TABLET_COLS = 2;
const DESKTOP_COLS = 3;
const tabletGhostCount = showGhostCards
  ? (TABLET_COLS - (posts.length % TABLET_COLS)) % TABLET_COLS
  : 0;
const desktopGhostCount = showGhostCards
  ? (DESKTOP_COLS - (posts.length % DESKTOP_COLS)) % DESKTOP_COLS
  : 0;
const sharedGhostCount = Math.min(tabletGhostCount, desktopGhostCount);
const tabletOnlyGhostCount = tabletGhostCount - sharedGhostCount;
const desktopOnlyGhostCount = desktopGhostCount - sharedGhostCount;

function pageUrl(n: number) {
  if (paginationBase) {
    return n === 1 ? paginationBase : `${paginationBase}/${n}`;
  }
  return n === 1 ? "/blog" : `/blog/page/${n}`;
}
---

<section class="section blog-grid-section flow-section">
  <div class="container is-max-desktop">
    {posts.map((post) => (
      <div class="blog-grid__cell">
        <BlogPost
          title={post.data.title}
          url={`/blog/${post.id}`}
          cover={post.data.cover}
          pubDate={post.data.pubDate}
          draft={post.data.draft}
          readingTime={readingTime(post.body ?? "").text}
        />
      </div>
    ))}
    {Array.from({ length: sharedGhostCount }).map(() => (
      <div class="blog-grid__cell blog-grid__ghost-cell blog-grid__ghost-cell--tablet-up">
        <BlogCardPlaceholder />
      </div>
    ))}
    {Array.from({ length: tabletOnlyGhostCount }).map(() => (
      <div class="blog-grid__cell blog-grid__ghost-cell blog-grid__ghost-cell--tablet-only">
        <BlogCardPlaceholder />
      </div>
    ))}
    {Array.from({ length: desktopOnlyGhostCount }).map(() => (
      <div class="blog-grid__cell blog-grid__ghost-cell blog-grid__ghost-cell--desktop-only">
        <BlogCardPlaceholder />
      </div>
    ))}

    {totalPages > 1 && (
      <nav class="pagination-nav" aria-label="Blog pagination">
        <a
          href={prevUrl}
          aria-disabled={!prevUrl}
          tabindex={!prevUrl ? -1 : 0}
        >
          &larr; Previous
        </a>
        <div class="pagination-nav__pages" role="list">
          {Array.from({ length: totalPages }).map((_, i) => {
            const n = i + 1;
            return (
              <a
                href={pageUrl(n)}
                role="listitem"
                aria-current={n === currentPage ? "page" : undefined}
              >
                {n}
              </a>
            );
          })}
        </div>
        <a href={nextUrl} aria-disabled={!nextUrl} tabindex={!nextUrl ? -1 : 0}>
          Next &rarr;
        </a>
      </nav>
    )}
  </div>
</section>

Improving code blocks in Astro

Roger Rajaratnam — Tue, 09 Jun 2026 10:00:10 +0000

Original post: Improving code blocks in Astro

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

Astro ships with built-in syntax highlighting through Shiki, and for the most part it
does the job. But out of the box you get highlighted code and not much else: no copy
button, no language badge, no way to mark specific lines or highlight a changed word,
no framing to distinguish a terminal command from a config file. For a blog that is
primarily about code, those gaps show up constantly. I wanted blocks that added
context at a glance without requiring custom CSS for every new feature.

Expressive Code is an Astro integration that replaces
the default code fence renderer with polished, accessible components — syntax
highlighting, dual themes, a copy button, language labels, editor and terminal frames,
and line/text markers, all driven by code fence attributes. No custom CSS or
JavaScript required.

The alternative is building it yourself: a custom rehype plugin to transform code
nodes, hand-rolled CSS for every theme variant, client-side JavaScript for the copy
button, and your own logic for diff markers and line highlighting. I looked at that
route and decided the maintenance surface was not worth it. Expressive Code solves the
whole problem in a single integration, the feature set is well ahead of anything I
would build in a reasonable time, and the API maps cleanly to what you already write
in a code fence.

Setup

Install the integration and the optional line numbers plugin:

pnpm add astro-expressive-code @expressive-code/plugin-line-numbers

This site uses a manual data-theme toggle rather than prefers-color-scheme, so
useDarkModeMediaQuery is disabled and themeCssSelector maps theme variants to
that attribute:

import { defineConfig } from 'astro/config';
import expressiveCode from 'astro-expressive-code';
import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers';

export default defineConfig({
  integrations: [
    expressiveCode({
      themes: ['one-light', 'one-dark-pro'],
      plugins: [pluginLineNumbers()],
      defaultProps: {
        showLineNumbers: true,
        wrap: true,
        overridesByLang: {
          'bash,sh,zsh': { preserveIndent: false },
        },
      },
      styleOverrides: {
        codePaddingInline: '1.5rem',
      },
      useDarkModeMediaQuery: false,
      themeCssSelector: (theme) =>
        theme.type === 'dark'
          ? '[data-theme="dark"]'
          : ':root:not([data-theme="dark"])',
    }),
  ],
  markdown: {
    syntaxHighlight: false,
  },
});

syntaxHighlight: false hands all code fence processing over to Expressive Code.

Themes

themes takes an array of Shiki theme names — first is the light variant, second is
dark. Expressive Code emits scoped CSS variables for both and activates each via the
selector returned by themeCssSelector. Any pair from
the Shiki catalogue works.

Frames

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

Every code block is wrapped in a frame. The frame type — editor or terminal —
is detected automatically from the language identifier, but can be overridden.

Editor frames

There are two ways to set the tab title — a title attribute on the fence, or a
file name comment in the first four lines of the code:

js title="src/utils/format.js"
export function formatDate(date) {
return new Intl.DateTimeFormat('en-GB').format(date);
}

js
// src/utils/format.js
export function formatDate(date) {
return new Intl.DateTimeFormat('en-GB').format(date);
}

title attribute — the tab label is set directly:

export function formatDate(date) {
  return new Intl.DateTimeFormat('en-GB').format(date);
}

File name comment — extracted as the tab title and removed from the rendered output:

// src/utils/format.js
export function formatDate(date) {
  return new Intl.DateTimeFormat('en-GB').format(date);
}

Terminal frames

Shell languages (bash, sh, zsh, ps1, etc.) are automatically rendered as
terminal frames. A title is optional:

pnpm build

echo "No title — still a terminal frame"

Overriding frame type

Force a specific type with the frame attribute. Useful when a shell script should
look like an editor tab, or when you want to strip all chrome from a block:

ps frame="code" title="PowerShell Profile.ps1"
function Watch-Tail { Get-Content -Tail 20 -Wait $args }
New-Alias tail Watch-Tail

function Watch-Tail { Get-Content -Tail 20 -Wait $args }
New-Alias tail Watch-Tail

sh frame="none"
echo "No frame at all"

echo "No frame at all"

Line numbers

Enabled globally via defaultProps: { showLineNumbers: true }. Both props can be
overridden per block — turn them off entirely, or start the counter at an arbitrary
number when showing a file excerpt:

js showLineNumbers=false
export function formatDate(date) {
return new Intl.DateTimeFormat('en-GB').format(date);
}

js startLineNumber=42
export function formatDate(date) {
return new Intl.DateTimeFormat('en-GB').format(date);
}

showLineNumbers=false — line numbers hidden:

export function formatDate(date) {
  return new Intl.DateTimeFormat('en-GB').format(date);
}

startLineNumber=42 — counter starts at 42, useful for excerpts:

export function formatDate(date) {
  return new Intl.DateTimeFormat('en-GB').format(date);
}

Word wrap

wrap: true enables soft wrapping globally. Long lines fold visually to the next
line rather than causing a horizontal scrollbar. preserveIndent (default: true)
keeps wrapped lines aligned with their original indentation — useful for code.
Setting it to false makes wrapped lines start at column 1, which suits terminal
output, so the config uses overridesByLang to apply that for bash,sh,zsh.

Both can be overridden per block:

js wrap=true
const result = await fetch('https://api.example.com/v1/users?filter=active&sort=createdAt&order=desc&limit=100&page=2');

js wrap=false
const result = await fetch('https://api.example.com/v1/users?filter=active&sort=createdAt&order=desc&limit=100&page=2');

wrap=true — long line folds to the next line:

const result = await fetch('https://api.example.com/v1/users?filter=active&sort=createdAt&order=desc&limit=100&page=2');

wrap=false — long line causes a horizontal scrollbar:

const result = await fetch('https://api.example.com/v1/users?filter=active&sort=createdAt&order=desc&limit=100&page=2');

Line markers

Draw attention to specific lines or ranges using mark, ins, and del:

mark={N} — neutral highlight
ins={N} — green "added" highlight with a + indicator
del={N} — red "removed" highlight with a - indicator

js mark={1} ins={3-5} del={7}
import { defineConfig } from 'astro/config';

import expressiveCode from 'astro-expressive-code';
import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers';
import emoji from 'remark-emoji';

import { oldPlugin } from './old-plugin';

import { defineConfig } from 'astro/config';

import expressiveCode from 'astro-expressive-code';
import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers';
import emoji from 'remark-emoji';

import { oldPlugin } from './old-plugin';

Combine multiple ranges in one attribute: ins={1-2, 5, 8-10}.

Labels can be added to any marked range — wrap the value in {"label:": range}
and a coloured badge appears at the start of the highlighted block. The label
string must end with a colon:

js ins={"1":3-5} del={"2":7}
import { defineConfig } from 'astro/config';

import expressiveCode from 'astro-expressive-code';
import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers';
import emoji from 'remark-emoji';

import { oldPlugin } from './old-plugin';

import { defineConfig } from 'astro/config';

import expressiveCode from 'astro-expressive-code';
import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers';
import emoji from 'remark-emoji';

import { oldPlugin } from './old-plugin';

Using diff syntax

Set the language to diff and prefix lines with + or -. Add lang="..." to
keep syntax highlighting for the actual language:

diff lang="js"
export default defineConfig({
integrations: [

shikiConfig({ themes: { light: 'one-light', dark: 'one-dark-pro' } }),
expressiveCode({ themes: ['one-light', 'one-dark-pro'] }), ], });

  export default defineConfig({
    integrations: [
-     shikiConfig({ themes: { light: 'one-light', dark: 'one-dark-pro' } }),
+     expressiveCode({ themes: ['one-light', 'one-dark-pro'] }),
    ],
  });

Text markers

Mark arbitrary text within lines using the same mark, ins, or del attributes
with a quoted string value:

js ins="expressiveCode" del="shikiConfig" mark="themes"
import expressiveCode from 'astro-expressive-code';

export default defineConfig({
integrations: [expressiveCode({ themes: ['one-light', 'one-dark-pro'] })],
markdown: { shikiConfig: { themes: { light: 'one-light' } } },
});

import expressiveCode from 'astro-expressive-code';

export default defineConfig({
  integrations: [expressiveCode({ themes: ['one-light', 'one-dark-pro'] })],
  markdown: { shikiConfig: { themes: { light: 'one-light' } } },
});

Use a /regex/ for pattern-based matching, or repeat the attribute for multiple
values: ins="foo" ins="bar". Capture groups narrow the match to a sub-expression:
/import (expressiveCode)/ marks only the identifier, not the whole import statement.

The full picture

With astro-expressive-code in place, a single config block handles syntax
highlighting, dual themes, line numbers, word wrap, copy buttons, and language labels.
Editor and terminal frames add context without extra markup. Line and text markers let
you direct the reader's attention precisely — all driven by code fence attributes that
read naturally in the source.

If you are setting this up on your own Astro site, or have a different approach to
code block styling, I'd like to hear about it. The rest of the series
covers the table of contents, pagination, search, and more — sign up to the mailing.
list below to get each post the morning it drops.

Running Local AI Models on macOS

Roger Rajaratnam — Thu, 04 Jun 2026 10:34:15 +0000

Original post: Running Local AI Models on macOS

I use GitHub Copilot at work and Claude for personal projects. Both switched to usage-based billing this month, dropping the flat subscription model. For anyone using these tools heavily across multiple projects, that shift makes the monthly cost unpredictable. Running models locally removes that variable entirely: no usage bills, no rate limits, and everything stays on your machine.

The quality gap has closed enough that local models are a realistic daily driver now, not just an experiment.

This guide covers the first-time setup on a Mac with Apple Silicon. I run this on an M1 MacBook Pro with 16 GB of unified memory. The default settings are tuned for that hardware, but each relevant section also covers what to change if you have more RAM.

How it fits together

Diagram fallback for Dev.to. View the canonical article for the full version: https://sourcier.uk/blog/local-ai-ollama-setup

Prerequisites

macOS with Apple Silicon (M series)
Homebrew installed
A few GB of free disk space per model (most 7–8B models need 4–5 GB each)
VS Code, for the integration sections at the end; a GitHub Copilot subscription is needed to use cloud models, but the local Ollama integration works without one

Install Ollama

Ollama is the runtime that downloads, manages, and serves local models. Install it via Homebrew:

brew install --cask ollama

Alternatively, download the installer directly from ollama.com. Once launched, Ollama places an icon in the menu bar and starts the API server at http://localhost:11434. Confirm it is running:

curl http://localhost:11434

The response should be Ollama is running.

Memory and performance settings

Running a language model is fundamentally a memory operation, not a compute one. A model's weights are the billions of numerical parameters that encode its behaviour, and they must be loaded entirely into RAM before a single token can be generated. A 7B model in Q4_K_M quantisation takes around 4–5 GB; an 8B model is similar. If those weights do not fit and the system starts paging to disk, inference slows to a near halt regardless of how fast your CPU is.

On Apple Silicon this matters more than on a typical machine: the CPU, Metal GPU, and every running application share a single pool of unified memory. VS Code, a dev server, a browser, and Ollama are all drawing from the same 16 GB.

Ollama's defaults are generous with memory, which compounds these pressures. Without tuning, the runtime may load multiple models simultaneously, allocate a context window far larger than needed, and leave your other tools fighting for RAM.

Add these variables to ~/.zshrc or ~/.zprofile:

# Limit concurrency — one model at a time on 16 GB
export OLLAMA_MAX_LOADED_MODELS=1
export OLLAMA_NUM_PARALLEL=1

# Keep the model warm between requests — avoids cold-start latency in VS Code
export OLLAMA_KEEP_ALIVE=30m

# Default context window
export OLLAMA_CONTEXT_LENGTH=4096

# Apple Silicon optimisations — the highest-impact pair for 16 GB
export OLLAMA_FLASH_ATTENTION=1
export OLLAMA_KV_CACHE_TYPE=q8_0

Then apply them without restarting your shell:

source ~/.zshrc

Setting	Why
`OLLAMA_MAX_LOADED_MODELS=1`	Prevents multiple models competing for the same 16 GB
`OLLAMA_NUM_PARALLEL=1`	Explicit default; prevents accidental concurrent loads
`OLLAMA_FLASH_ATTENTION=1`	Reduces peak activation memory on M1 Metal
`OLLAMA_KV_CACHE_TYPE=q8_0`	Halves KV cache RAM compared to the default `f16`
`OLLAMA_KEEP_ALIVE=30m`	Model stays loaded between requests, no cold-start delay

OLLAMA_FLASH_ATTENTION and OLLAMA_KV_CACHE_TYPE=q8_0 together free around 1–2 GB of effective headroom. That is enough to run 8B parameter models comfortably on 16 GB when they would otherwise be marginal.

Adjusting for more RAM

The settings above are conservative, tuned for 16 GB. On machines with more unified memory you can relax the concurrency limits and drop the KV cache compression:

Setting	16 GB (M1/M2)	32 GB (M2 Pro/M3 Pro)	64 GB+ (M3 Max/Ultra)
`OLLAMA_MAX_LOADED_MODELS`	`1`	`2`	`3` or more
`OLLAMA_NUM_PARALLEL`	`1`	`2`	`4`
`OLLAMA_KV_CACHE_TYPE`	`q8_0`	`q8_0` or omit	Omit: use default `f16`

OLLAMA_FLASH_ATTENTION=1 is still worth keeping on any Apple Silicon machine: it reduces peak activation memory regardless of total RAM.

Staying fully local

Ollama does not send your prompts anywhere by default. If you are working with sensitive data and want a hard guarantee, add this flag too:

# Optional — disables remote inference and web search entirely
export OLLAMA_NO_CLOUD=1

Choosing a model

Every model has a name and a size tag. The number in the tag reflects how many billion parameters it contains, which determines both output quality and how much RAM it needs to load. Use the table below to pick the right fit for your hardware and use case.

Model reference

Model	Size	Vision	Best for
`gemma3:4b`	~2.5 GB	Yes	Fast chat, vision, light tasks
`qwen3:8b`	~4.5 GB	No	Best all-rounder, strong reasoning
`qwen2.5vl:7b`	~4.5 GB	Yes	Vision and text
`qwen2.5vl:3b`	~2 GB	Yes	Lightweight vision
`qwen2.5-coder:7b`	~4.3 GB	No	Code generation
`mistral-nemo`	~7 GB	No	Long documents, 32K context
`gemma3:12b`	~8 GB	Yes	Higher quality, viable with flash attention
`nomic-embed-text`	~0.3 GB	No	Embeddings and RAG pipelines

On 16 GB, avoid 13B models and larger. They will page to swap and feel sluggish under any real workload. On 32 GB you can run 13B and 14B models comfortably, and gemma3:12b and qwen3:14b become reliable daily drivers. On 64 GB or more, 27B and 32B models are viable. Check ollama.com/library for the full catalogue.

Prefer Q4_K_M quantised variants when available. They offer the best speed-to-quality tradeoff regardless of hardware tier.

When you want to attach an image to a conversation, switch to a vision model like qwen2.5vl:7b or gemma3:4b. Text-only models reject image input.

Pulling and running a model

Use ollama pull to download a model and ollama run to test it interactively:

ollama pull qwen3:8b
ollama run qwen3:8b

The first pull downloads several gigabytes, so run this on a decent connection. After that, the model lives on disk at ~/.ollama/models/ and launches instantly.

A good starting set for most daily-use scenarios:

ollama pull qwen3:8b           # daily driver — best all-rounder
ollama pull qwen2.5-coder:7b   # coding tasks
ollama pull qwen2.5vl:7b       # vision and text
ollama pull gemma3:4b          # lightweight vision alternative
ollama pull nomic-embed-text   # embeddings and RAG

VS Code Copilot integration

VS Code Copilot can use a local Ollama server as a model provider. The setup is straightforward, but there is one catch: Copilot reads each model's maximum reported context size and may allocate the full window upfront.

Model	Reported max context	KV cache cost at max
`qwen3:8b`	41K tokens	~4 GB
`qwen2.5vl:7b`	128K tokens	~16 GB
`qwen2.5-coder:7b`	33K tokens	~3 GB

OLLAMA_CONTEXT_LENGTH=4096 sets a global default, but Copilot does not always respect it in API requests. The reliable fix is a Modelfile: a small config file that bakes a capped context window into a named model variant.

Create capped model variants

A Modelfile is a plain text file that tells Ollama how to build a named variant from an existing base. The two fields that matter here are FROM (the base model to derive from) and PARAMETER num_ctx (the context window to enforce):

FROM qwen3:8b
PARAMETER num_ctx 4096
PARAMETER temperature 0.7

temperature controls how much variation the model introduces when generating a response. 0.7 is a reasonable general-purpose default: creative enough to avoid repetitive output, focused enough to stay on topic. The coder variant uses 0.2 because code generation benefits from deterministic output. There is usually one right answer, not several equally valid variations.

Running ollama create <name> -f <Modelfile> registers that file as a new named model. No additional data is downloaded: Ollama references the base model already on disk with the specified parameters baked in.

The following creates all four variants in one pass:

mkdir -p ~/ollama-models

printf 'FROM qwen3:8b\nPARAMETER num_ctx 4096\nPARAMETER temperature 0.7\n' \
  > ~/ollama-models/Modelfile.qwen3-fast

printf 'FROM qwen2.5-coder:7b\nPARAMETER num_ctx 4096\nPARAMETER temperature 0.2\n' \
  > ~/ollama-models/Modelfile.coder-fast

printf 'FROM qwen2.5vl:7b\nPARAMETER num_ctx 4096\n' \
  > ~/ollama-models/Modelfile.vision-fast

printf 'FROM gemma3:4b\nPARAMETER num_ctx 4096\n' \
  > ~/ollama-models/Modelfile.gemma-fast

ollama create qwen3-fast  -f ~/ollama-models/Modelfile.qwen3-fast
ollama create coder-fast  -f ~/ollama-models/Modelfile.coder-fast
ollama create vision-fast -f ~/ollama-models/Modelfile.vision-fast
ollama create gemma-fast  -f ~/ollama-models/Modelfile.gemma-fast

Connect to Ollama and select a model

To wire VS Code Copilot to a local Ollama server, add this to your VS Code settings.json:

"github.copilot.chat.ollama.endpoint": "http://localhost:11434"

You can also do this through the UI: open Copilot Chat (Cmd+Shift+I on macOS), click the model picker dropdown at the top of the chat panel, and choose "Manage Models". VS Code discovers all models running on localhost:11434 automatically once Ollama is running.

Once connected, the capped variants appear in the picker alongside any cloud models. Switch to qwen3-fast, coder-fast, vision-fast, or gemma-fast depending on the task. After starting a conversation, confirm the model loaded:

ollama ps

Copilot CLI

GitHub Copilot has a standalone CLI for the terminal. Install it via Homebrew:

brew install copilot-cli

Once installed, run copilot from any project directory. On first launch it asks you to trust the folder and log in to GitHub. You type prompts directly in the terminal and Copilot can read, modify, and run files in the current directory. It supports plan mode (Shift+Tab to toggle), custom agents, and MCP servers.

You can point it at Ollama to use local models rather than GitHub's cloud. The quickest way is:

ollama launch copilot

This opens a model selector populated from Ollama's library. To specify a model directly:

ollama launch copilot --model qwen3:8b

For manual wiring, set the Ollama endpoint via environment variables before running copilot:

export COPILOT_PROVIDER_BASE_URL=http://localhost:11434/v1
export COPILOT_PROVIDER_API_KEY=
export COPILOT_PROVIDER_WIRE_API=responses
export COPILOT_MODEL=qwen3:8b

One caveat: Copilot CLI works best with a generous context window. The Ollama docs recommend at least 64K tokens, so the 4K capped variants created above are too small for it. Use the base models directly and raise OLLAMA_CONTEXT_LENGTH to 32768 or higher when running Copilot CLI sessions.

Wrapping up

This covers the full stack: Ollama installed and tuned, a model set selected for different use cases, VS Code Copilot wired to local variants, and the standalone Copilot CLI pointed at Ollama. On 16 GB the memory settings and capped context variants make local inference genuinely practical for everyday coding and chat work, not just a curiosity.

For tasks that fit in a 4K context window a local model handles them without touching any external service. For longer context, heavier reasoning, or the times a cloud model simply performs better, the paid providers are still there. The difference is that reaching for them is now a deliberate choice rather than the default.

Keeping up with new model releases is a single ollama pull command. Ollama fetches only changed layers, so updates stay fast even at multi-GB model sizes.

I'm also working on a dedicated machine for local AI inference: custom hardware that removes the unified memory constraint entirely. I'll write that up once it's running. If you're building something similar or have a setup you're happy with, drop a comment below or subscribe via the form at the end of this page to catch that post when it lands.

GitHub Copilot for Engineers: Getting Better Results

Roger Rajaratnam — Tue, 02 Jun 2026 09:50:19 +0000

Original post: GitHub Copilot for Engineers: Getting Better Results

GitHub Copilot moved to usage-based billing in June 2026, dropping the flat subscription model that made monthly costs predictable. For teams using it heavily across multiple projects, that shift puts a premium on being deliberate: reaching for the right model, keeping prompts focused, and building a configuration that produces good results without a lot of back-and-forth iteration.

Many of us install the extension, start with the defaults, and only tune settings later. The defaults are a reasonable starting point, but they are not a full configuration. A small investment in setup changes how much you get out of every request on an ordinary working day, and that matters more now that each request has a cost attached.

This guide covers the full path: getting the tooling in place, choosing models with cost in mind, layering global and project-level rules, and building out instructions, agents, and skills that make Copilot predictable across different kinds of work.

Architecture overview

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

Before you start

Subscription and VS Code extension

You need an active GitHub Copilot subscription. Plans are available at individual, business, and enterprise tiers at github.com/features/copilot. Once active, all tools use your GitHub account credentials.

The GitHub Copilot extension for VS Code is the primary day-to-day interface. Install it from the Extensions panel or via the CLI:

code --install-extension GitHub.copilot

The extension provides inline completions as you type, Copilot Chat in the sidebar, inline chat on any selection via Cmd+I / Ctrl+I, agent mode for multi-step tasks, and multi-file edits with a single review step.

Defaults keep improving, so avoid cargo-culting old setting lists. Focus on non-default tweaks that improve signal quality and control usage:

Setting	Value	Effect
`github.copilot.nextEditSuggestions.enabled`	`true`	Surfaces likely next edits proactively during implementation
`github.copilot.chat.codesearch.enabled`	`true`	Improves answers on larger repos by pulling semantic code context

Copilot CLI

The GitHub Copilot CLI is a standalone AI agent for the terminal.

Install via Homebrew:

brew install copilot-cli

Or via pnpm, if you prefer Node.js tooling:

pnpm add -g @github/copilot

On first launch, authenticate with your GitHub account by following the /login prompt. The CLI has two modes: an interactive session where you have a back-and-forth conversation while Copilot reads and modifies files in the current directory, and a programmatic mode where you pass a single prompt with -p and the CLI executes and exits.

# Start an interactive session
copilot

# One-shot task with explicit tool approval
copilot -p "Show me this week's commits and summarise them" --allow-tool='shell(git)'

# Open a PR with the changes
copilot -p "Refactor the auth module to use async/await and open a PR"

awesome-copilot

github.com/github/awesome-copilot is the official community-curated repository of Copilot instructions, agents, skills, and prompts. Before writing any configuration from scratch, check here first. It is far faster to adapt a battle-tested instruction file than to start from a blank page. The catalogue covers common engineering workflows: security review, frontend, documentation, and more.

Choose models by task

Model choice should match task shape. GitHub Copilot subscriptions give you access to a range of models. Here is how to map them to real work:

Task	Recommended model	Why
Quick edits and inline completions	GPT-5.4	Strong quality at lower effort per prompt, reducing rework
General feature work and refactoring	GPT-5.4 or Claude Sonnet 4.5	Strong reasoning with a good speed and cost balance
Complex architecture and deep analysis	Claude Sonnet 4.5	Extended reasoning and long context without premium pricing
Security review	Claude Sonnet 4.5	Strong policy alignment and risk detection
Documentation and standards	GPT-5.4 or Claude Sonnet 4.5	Consistent structure, clear prose
Agent and multi-step repo operations	Claude Sonnet 4.5 or GPT-5.4	Reliable tool-calling across many steps

A practical pattern:

Start with your default model.
If the output is shallow, switch to a stronger reasoning model.
If the output is too slow for a simple task, switch back to a faster model.
Keep one model per agent role for consistency: engineering, security, UX, docs.

Agents (covered below) let you pin a model in their frontmatter, so the same task always runs with the same capability profile.

Layer global and project settings

The most reliable setup is layered: global defaults for how you work everywhere, project-level rules for what is unique to a specific repo.

Global settings

Global Copilot configuration lives under your home directory:

Path	Purpose
`~/.copilot/instructions/`	Always-on rules applied across all repos
`~/.copilot/agents/`	Reusable agent definitions
`~/.copilot/skills/`	Reusable skill playbooks
`~/.copilot/mcp-config.json`	Global MCP server connections

Managing these in a dotfiles repo and syncing them to $HOME on each machine gives you a consistent baseline without reconfiguring per project. Good candidates for global rules include workflow behaviour and tool preferences, secure coding defaults, code-commenting standards, and framework-specific instructions for React, TypeScript, and similar.

If you want a concrete reference, this is my setup: github.com/sourcier/dotfiles.

Project-level settings

For project-specific behaviour, add a .github/copilot-instructions.md to the repo root, or place .instructions.md files in .github/instructions/. VS Code picks these up automatically when you open the project.

Use project-level rules for naming conventions unique to this repo, folder architecture and module boundaries, test and QA requirements, and build and deployment constraints. Use global rules for communication style, security baseline, preferred CLIs, package manager choices, and repeatable personal workflow.

Instructions, agents, and skills

These three tools serve different purposes. Treating them as interchangeable leads to a setup that is noisy and hard to maintain.

Instructions: always-on policy

Instructions are Markdown files with YAML frontmatter that Copilot reads automatically whenever the applyTo glob matches the file you are working in. Use them for stable guardrails and standards that should apply silently in the background.

Two patterns work well: broad instructions with applyTo: '*' for universal rules, and targeted instructions with file-type globs for framework-specific rules.

Minimal template:

---
applyTo: '**/*.ts'
description: 'TypeScript service-layer standards'
---

# Service Standards
- Use strict typing
- Return typed errors
- Validate external input at boundaries

Agents: task-specific operators

Agents are .agent.md files that define a reusable persona with a pinned model, a tool budget, and a system prompt. Use them when the same class of work needs consistent behaviour every time.

An agent definition includes:

name: shown in the VS Code agent picker
description: used for routing; Copilot reads this to decide which agent fits a request
model: pinned model for this workflow
tools: explicit list of tools the agent is allowed to use

Good starting agents: a Software Engineer for general implementation and refactoring, a Security Reviewer for OWASP-focused code review, an Expert Frontend Engineer for React and TypeScript work, and a Tech Writer for documentation and READMEs.

Create a new agent when a task requires a distinct review lens, needs a stable model and tool profile, or when you want consistent output style for that workflow.

Skills: reusable playbooks

Skills are SKILL.md files that contain detailed step-by-step procedures for a specific domain. The agent reads the skill file at invocation time rather than keeping it in context permanently, which means skills can be as long and detailed as needed without bloating every conversation.

Good candidates: a premium frontend UI craftsmanship checklist, a workflow for creating AGENTS.md files for a new repo, or a Playwright website exploration procedure.

The rule of thumb:

Instructions = default behaviour
Agents = who does the work
Skills = how specialised work gets executed

MCP servers

MCP (Model Context Protocol) extends Copilot with external capabilities: browsers, issue trackers, cloud providers, databases, and more. Servers are configured in ~/.copilot/mcp-config.json for global access, or .vscode/mcp.json for project scope.

Three common patterns:

Local command server: runs a pre-installed binary on your machine (preferred)
Remote HTTP server: connects to an external service over HTTPS
npx/uvx on-demand: package runner launches the server each time; avoid for servers you use regularly as the cold boot adds latency on every invocation

Installing common servers

Playwright MCP: browser automation and visual QA:

brew install playwright-mcp
# or via pnpm
pnpm add -g @playwright/mcp

Azure MCP Server: Azure resource inspection and management:

brew tap azure/azure-cli
brew install azmcp
# Authenticate before first use
az login

Example config

{
  "mcpServers": {
    "playwright": {
      "command": "playwright-mcp",
      "args": ["--headless"]
    },
    "atlassian/atlassian-mcp-server": {
      "type": "http",
      "url": "https://mcp.atlassian.com/v1/mcp/"
    },
    "Azure MCP Server": {
      "command": "azmcp",
      "args": ["server", "start"]
    }
  }
}

Prefer a globally installed binary via Homebrew or pnpm for any server you use regularly. Reserve npx for one-off evaluation of a new server before committing to a permanent install.

When to reach for MCP

Follow this order:

Native CLI first: git, gh, pnpm, docker, cloud CLIs.
Use MCP when no good CLI path exists or when MCP adds capability the CLI cannot.
Keep the MCP list minimal and intentional.

Security checklist

Before adding any MCP server:

Never hardcode tokens in config files. Use environment variables or a secret store.
Prefer least-privilege credentials.
Use trusted hosts only for remote HTTP servers.
Disable or remove servers you are not actively using.

Rolling it out

Individual setup

Install the VS Code extension and Copilot CLI.
Create ~/.copilot/instructions/ and add one global instruction file. Workflow preferences and a security baseline are the highest-value starting points.
Browse awesome-copilot and copy two or three instruction files relevant to your stack.
Add a .github/copilot-instructions.md to your primary repo with project-specific conventions.
Try agent mode for a non-trivial task to get a feel for how it behaves.

Team rollout

Define a shared baseline in a dotfiles or inner-source repo covering instructions, agents, skills, and MCP config.
Add two to four high-value project instructions per repo.
Create three core agents: engineering, security, and documentation review.
Add skills only for repeated, specialised workflows.
Review output quality every two weeks and refine rules and prompts based on what you observe.

Keeping it improving

Results degrade when instructions conflict, when prompts are vague, or when agents are used for everything regardless of fit. A simple quality loop prevents that drift:

Be explicit in prompts: goal, constraints, relevant files, and done criteria.
Keep instructions concise and non-conflicting.
Scope rules with applyTo so they trigger only where needed.
Use specialised agents for repeated high-value workflows.
Validate with tests and lint, and feed failures back into instructions.

Quick audit checklist

When the setup is in place, use this to evaluate it quickly:

Model selection is intentional by task type.
Global rules exist for workflow and security.
Project rules exist for repo-specific conventions.
Agent catalogue maps to real team workflows.
Skills exist only for deep, repeated procedures.
MCP servers are minimal, secure, and actively used.
Prompts include explicit success criteria.

Wrap up

The model table in this guide covers the cloud providers available through a Copilot subscription. If you want to cut cloud costs further or keep sensitive work entirely on your machine, running models locally is worth exploring. My next post covers exactly that: installing and tuning Ollama on Apple Silicon, choosing models by use case, and wiring local inference into VS Code Copilot and the CLI. It goes live June 4.

If this guide helped, use it as a practical checklist this week: pick one primary model, tighten your instruction layers, and remove one source of prompt churn from your workflow. Then share what changed for you in the comments, or subscribe via the form at the end of this page to get the local AI follow-up as soon as it publishes.

Adding comments to a static Astro blog with Netlify Forms

Roger Rajaratnam — Wed, 27 May 2026 11:48:06 +0000

Original post: Adding comments to a static Astro blog with Netlify Forms

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

Comments on a static site are one of those problems that sounds simple until you
actually sit down to solve it. You've got a few options.

You can reach for a third-party widget: Disqus, Commento, or Giscus. They all work,
and Giscus in particular is clever if your readers are likely to have GitHub
accounts. But they all introduce an external dependency you don't control, and
most of them inject JavaScript you didn't write.

You can build a full backend: a database, an API, authentication for moderation.
That's a lot of infrastructure for what is, on a personal blog, a fairly low-volume
use case.

Or you can use what you already have. If you're hosting on Netlify, you've already
got Netlify Forms and serverless
Functions available. The approach I settled on uses both, inspired by
Phil Hawksworth's jamstack-comments-engine.

The approach

The system runs in four steps:

A visitor submits the comment form. Netlify intercepts the POST and stores it in its Forms queue. No backend code needed.
A webhook triggers comment-handler, which sends an email with HMAC-signed approve and delete links.
Clicking Approve calls approve-comment, which re-posts the comment data to a second form (approved-comments) and removes it from the queue.
get-comments reads only from approved-comments, so only reviewed content ever reaches readers.

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

There's no database to provision, no moderation dashboard to watch, and no
third-party script on the page. Comments don't go live until I explicitly approve
them from my inbox.

The form

Netlify detects forms at build time by scanning the static HTML for data-netlify="true".
Because this is an Astro site, the form is a server-rendered .astro component, which
means it appears in the built HTML and Netlify registers it automatically on first deploy.

<form
  name="blog-comments"
  method="POST"
  data-netlify="true"
  netlify-honeypot="bot-field"
>
  <input type="hidden" name="form-name" value="blog-comments" />
  <input type="hidden" name="postSlug" value={postId} />
  <!-- honeypot -->
  <input name="bot-field" style="display:none" tabindex="-1" />
  <!-- fields: name, email (optional), comment -->
</form>

A few things worth noting here:

The form-name hidden field is required when submitting via fetch rather than a native form POST. Netlify uses it to route the payload to the right form bucket.
postSlug stores the post identifier. When reading comments back, this is what ties each submission to its post.
The netlify-honeypot="bot-field" attribute tells Netlify to silently drop any submission that fills in the bot-field input. Real users don't see it; bots typically fill every field.

The form submits via fetch with Content-Type: application/x-www-form-urlencoded
to the current page URL; Netlify intercepts those requests before they hit the origin.

The functions

There are three Netlify Functions in total.

get-comments

netlify/functions/get-comments.js takes a ?slug= query param and fetches
submissions from the approved-comments form via the Netlify API, filtered by slug.

Email addresses are hashed server-side before the response leaves the function; the
raw address is never sent to the browser:

import crypto from "node:crypto";

function gravatarHash(email) {
  return crypto.createHash("md5").update(email.trim().toLowerCase()).digest("hex");
}

const comments = submissions
  .filter((s) => s.data?.postSlug === slug)
  .map((s) => ({
    name: s.data.name,
    comment: s.data.comment,
    // Use the original submission date, not the approval date
    date: s.data.originalDate || s.created_at,
    emailHash: s.data.email ? gravatarHash(s.data.email) : null,
  }))
  .sort((a, b) => new Date(a.date) - new Date(b.date));

MD5 is the hash format Gravatar's API requires; hashing also means the raw email
address never leaves the server.

Using originalDate rather than created_at matters here: created_at on an
approved submission reflects the moment it was approved, not when the visitor
wrote it. The approval function stamps the original queue date into originalDate
when it copies the submission across.

The access token lives in an environment variable; it never touches the browser.
The function returns an empty array if the variables aren't set, so the site
degrades gracefully in local dev.

comment-handler

netlify/functions/comment-handler.js is triggered by a Netlify outgoing webhook
whenever a new submission hits the blog-comments queue. It sends an HTML email
via Resend (the same delivery layer used for new post notifications) containing the comment text and two
HMAC-SHA256-signed action links:

import crypto from "node:crypto";

function hmac(submissionId, action, secret) {
  return crypto
    .createHmac("sha256", secret)
    .update(`${submissionId}:${action}`)
    .digest("hex");
}

const approveToken = hmac(id, "approve", secret);
const deleteToken  = hmac(id, "delete",  secret);

const approveUrl =
  `${siteUrl}/.netlify/functions/approve-comment` +
  `?action=approve&id=${id}&token=${approveToken}`;

Each token encodes both the submission ID and the intended action, so an approve
token can't be replayed as a delete, and tokens for one submission don't work on
another.

approve-comment

netlify/functions/approve-comment.js handles the link clicks. It:

Verifies the HMAC token with crypto.timingSafeEqual to prevent timing attacks
For approve: fetches the submission from the Netlify API, re-posts it to approved-comments with an originalDate field, then deletes the pending entry
For delete: deletes the pending submission directly
Returns a minimal HTML confirmation page either way

function verifyToken(submissionId, action, token, secret) {
  const expected = hmac(submissionId, action, secret);
  if (token.length !== expected.length) return false;
  return crypto.timingSafeEqual(
    Buffer.from(token, "hex"),
    Buffer.from(expected, "hex")
  );
}

The approve step posts to the site's own URL; Netlify's edge intercepts it and
stores it in the approved-comments bucket, exactly as it does for visitor
submissions. No direct Netlify API write is needed.

Rendering comments

Client-side JavaScript calls /.netlify/functions/get-comments?slug={postId} on page
load and renders whatever comes back.

One discipline worth keeping here: never use innerHTML with raw user data. Because
the comment cards are built as an HTML template string, innerHTML is unavoidable for
inserting the full card structure, but all user-supplied values are passed through
escapeHtml before they touch the template:

function escapeHtml(str) {
  return String(str)
    .replace(/&/g, "&amp;")
    .replace(/</g, "&lt;")
    .replace(/>/g, "&gt;")
    .replace(/"/g, "&quot;")
    .replace(/'/g, "&#39;");
}

No raw user content ever reaches the HTML parser.

Gravatar avatars

Each commenter gets an avatar. If they provided an email address, the emailHash from
the function is used to fetch their Gravatar. If they didn't, or if no Gravatar is
registered, a pink circle with their initial is shown instead.

The d=404 parameter tells Gravatar to return a 404 rather than a default image.
onerror hides the <img> and the initial shows through. onload hides the initial
when a real Gravatar loads successfully:

const avatarInner = c.emailHash
  ? `<img src="https://www.gravatar.com/avatar/${c.emailHash}?s=72&d=404"
         onload="this.nextElementSibling.style.display='none'"
         onerror="this.style.display='none'" />
     <span class="comment__avatar-initial">${initial}</span>`
  : `<span class="comment__avatar-initial">${initial}</span>`;

The <span> is always in the DOM behind the image, so the fallback requires no extra
logic.

Styling dynamically injected content in Astro

This tripped me up. Astro's scoped CSS works by adding a unique attribute
(e.g. data-astro-cid-xxx) to every element it renders, and then qualifying all the
CSS selectors with that attribute. That means the styles only match elements that were
rendered at build time.

Comment cards are injected via innerHTML at runtime; they never get the scoping
attribute. The fix is to wrap those selectors in :global():

/* scoped — applies to server-rendered elements */
.comments__heading { ... }

/* global — applies to runtime-injected elements */
:global(.comment) { ... }
:global(.comment__avatar) { ... }

Everything that's server-rendered stays scoped. Only the comment card classes need to
escape scoping.

Registering the approved-comments form

Netlify discovers forms by scanning built HTML at deploy time. The blog-comments
form lives in the Comments.astro component, so it's found automatically. The
approved-comments form is never rendered on a page; it only receives programmatic
POSTs from approve-comment. Without an explicit registration it would never be
created in the Netlify dashboard.

The fix is a hidden placeholder form in Comments.astro, alongside the visible
blog-comments form that visitors submit:

<form name="approved-comments" data-netlify="true" hidden aria-hidden="true">
  <input type="hidden" name="postSlug" />
  <input type="hidden" name="name" />
  <input type="hidden" name="email" />
  <input type="hidden" name="comment" />
  <input type="hidden" name="originalDate" />
</form>

Netlify only needs to find a form in one built page to register it. Since
Comments.astro is rendered on every blog post, the form is present in every post
page's HTML and will be picked up on the first deploy. The hidden attribute keeps
it invisible; aria-hidden="true" removes it from the accessibility tree.

Setting it up on Netlify

After the first deploy:

Get a personal access token: Netlify → User settings → Applications → Personal access tokens
Set up a Resend account and verify a sender domain (their free tier covers 3,000 emails per month, more than enough). If you already followed the mailing list post, your Resend account and sender domain are already configured.
Add these environment variables in Netlify → Site configuration → Environment variables:
- NETLIFY_PAT: personal access token from step 1. Avoid the name NETLIFY_ACCESS_TOKEN; Netlify auto-overwrites it at runtime with a limited machine token
- APPROVAL_SECRET: a random secret for HMAC signing (openssl rand -hex 32 works well)
- SITE_URL: the public URL, e.g. https://sourcier.uk
- RESEND_API_KEY: Resend API key
- NOTIFY_FROM_EMAIL: verified Resend sender address
- NOTIFY_EMAIL: where to receive approval emails
Add a webhook: Netlify → Forms → blog-comments → Form notifications → Add notification → Outgoing webhook → URL: https://your-site/.netlify/functions/comment-handler
Submit a test comment to create the first approved-comments entry, then copy its Form ID from the Netlify Forms dashboard URL
Add the final variable:
- APPROVED_COMMENTS_FORM_ID: form ID from step 5
Trigger a redeploy

After that, every new comment fires a notification email. Approve or delete it
by clicking the link. No dashboard visit required.

Refreshing the list after submission

After a successful POST, loadComments() is called a second time so the list
reflects whatever the server currently holds. Because Netlify Forms requires manual
approval before submissions appear via the API, the newly posted comment won't show
up immediately, but any comments approved in the meantime will, and the list stays
in sync rather than going stale.

To make the refresh feel intentional rather than jarring, renderComments accepts
an animate flag. When set, the list container fades out, swaps its HTML, then
fades back in:

function renderComments(comments, animate = false) {
  const html = buildCommentsHtml(comments);
  if (!animate) {
    listEl.innerHTML = html;
    return;
  }
  listEl.classList.add("is-fading");
  listEl.addEventListener("animationend", () => {
    listEl.innerHTML = html;
    listEl.classList.remove("is-fading");
    listEl.classList.add("is-entering");
    listEl.addEventListener(
      "animationend",
      () => listEl.classList.remove("is-entering"),
      { once: true },
    );
  }, { once: true });
}

The initial page-load call passes no flag, so the first render is instant with no
flash. The post-submission refresh passes animate = true.

The two CSS keyframes are defined in the component's scoped styles:

@keyframes comments-fade-out {
  from { opacity: 1; transform: translateY(0); }
  to   { opacity: 0; transform: translateY(-6px); }
}

@keyframes comments-fade-in {
  from { opacity: 0; transform: translateY(8px); }
  to   { opacity: 1; transform: translateY(0); }
}

:global(#comments-list.is-fading)  { animation: comments-fade-out 0.2s ease forwards; }
:global(#comments-list.is-entering) { animation: comments-fade-in  0.25s ease forwards; }

The selectors need :global() for the same reason comment card styles do; the list
element is in the server-rendered HTML but the classes are toggled at runtime by
JavaScript, so Astro's scoped-CSS attribute won't be present on the selector when the
animation fires.

What I'd do differently

The main remaining limitation is that comments don't appear immediately after
submission; the visitor sees a "submitted for review" message and has to come
back later to see it live. The list refreshes after submission, but an unapproved
comment can't show up in that refresh.

The cleanest fix would be to optimistically insert the pending comment into the
DOM immediately, marked visually as "awaiting approval", and then confirm or
remove it on the next real fetch. That adds state management I haven't needed
yet; volume is low enough that the current UX is fine for now.

Wrap-up

The full implementation spans four files: Comments.astro and the three serverless
functions. Netlify Forms handles the queue and webhook delivery, Resend sends the
notification email, and the HMAC signing keeps approve and delete actions
tamper-proof. Nothing goes live until I've clicked a link from my inbox, with no
database to provision and no third-party script on the page.

The Comments.astro component and all three functions are in the
sourcier.uk repository if you want to
use them as a starting point.

Adding a mailing list to a static Astro blog with Resend

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

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

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

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

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

What we're building

A MailingListCTA Astro component that:

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

The Netlify Function:

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

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

Setting up Resend Segments

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

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

The Netlify Function

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

A few things worth noting:

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

Welcome email

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

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

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

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

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

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

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

Creating the template with a script

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

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

The script:

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

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

The Astro component

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

Click the expand icon to view it fullscreen.

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

Honeypot field

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

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

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

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

Shared form utility

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

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

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

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

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

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

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

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

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

      const data = await res.json();

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

A few things worth noting:

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

Environment variables

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

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

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

Adding the component to pages

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

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

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

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

Sidebar variant

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

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

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

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

Dark mode theming

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

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

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

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

What Resend handles for you

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

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

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

Wrap-up

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

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

Scheduled publishing in Astro on Netlify

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

Original post: Scheduled publishing in Astro on Netlify

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

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

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

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

The problem with `draft: false` alone

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Two functions in drafts.ts are worth keeping straight:

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

Setting `pubDate` values

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

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

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

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

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

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

The scheduled Netlify function

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

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

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

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

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

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

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

netlify.toml configuration

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

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

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

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

Dashboard setup

One step in the Netlify dashboard is required:

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

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

Verifying the setup

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

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

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

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

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

How it fits together

A post ready to publish looks like this:

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

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

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

Where `draft` still fits in

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

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

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

The practical workflow:

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

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

What this doesn't do

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

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

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

Wrapping up

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

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

Working on something similar?

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

Sending new post notifications with Resend

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

Original post: Sending new post notifications with Resend

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

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

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

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

Why a script rather than a build hook

There are a few reasons.

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

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

Dependencies

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

Reading frontmatter without a build

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

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

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

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

  return result;
}

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

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

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

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

Environment variables

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

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

Required variables:

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

Optional variables:

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

The email content

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

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

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

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

Confirmation before sending

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

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

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

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

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

The two-step API call

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

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

The second dispatches it to the segment:

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

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

Running the script

node scripts/notify-new-post.js

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

Total runtime is a few seconds.

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

The full script is in the
sourcier.uk repository.

Deploying an Astro blog to Netlify

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

Original post: Deploying an Astro blog to Netlify

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

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

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

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

netlify.toml

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

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

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

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

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

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

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

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

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

Cache headers

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

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

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

The functions directory

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

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

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

Edge functions

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

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

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

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

Environment variables

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

Build-time variables

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

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

Runtime variables

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

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

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

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

openssl rand -hex 32

Deploy previews and draft posts

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

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

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

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

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

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

One-time Netlify dashboard setup for comments

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

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

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

Wrapping up

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

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

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

DEV Community: Roger Rajaratnam

Moving blog content to a private repository

The constraint

Why not a git submodule

The build-time clone approach

Setting up the GitHub token

The .gitignore entry

Local development

VS Code workspace setup

Triggering deploys from the content repository

What this gives you

Gating the preview branch behind a passcode

Purging content from the existing git history

What to watch for

Working on something similar?

Web analytics on a static Astro blog

Picking a tool

The implementation

Production-only loading

Why an external file instead of define:vars

Environment variables

Getting the key

Local development

GitHub Actions

What you get out of the box

A note on cookie consent

A custom 404 page

How Astro handles 404s

Skipping the standard layout

The hero panel

The number

The copy and the primary actions

Try these instead: guides and core pages

Accessibility notes

Full code listing

What Netlify does with it

Paginating a Blog in Astro

The URL structure

Why not paginate()?

Two route files instead of one

A shared BlogGrid component

Placeholder cards for a half-full grid

Pagination controls

What this produces

Full code listing

Improving code blocks in Astro

Setup

Themes

Frames

Editor frames

Terminal frames

Overriding frame type

Line numbers

Word wrap

Line markers

Using diff syntax

Text markers

The full picture

Running Local AI Models on macOS

How it fits together

Prerequisites

Install Ollama

Memory and performance settings

Adjusting for more RAM

Staying fully local

Choosing a model

Model reference

Pulling and running a model

VS Code Copilot integration

Create capped model variants

Connect to Ollama and select a model

Copilot CLI

Wrapping up

GitHub Copilot for Engineers: Getting Better Results

Architecture overview

Before you start

Subscription and VS Code extension

Copilot CLI

awesome-copilot

Choose models by task

Why an external file instead of `define:vars`

Why not `paginate()`?

The problem with `draft: false` alone

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

Setting `pubDate` values

Where `draft` still fits in