DEV Community: Roger Rajaratnam

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.

Page history and credits on a static blog

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

Original post: Page history and credits on a static blog

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

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

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

Architecture overview

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

UI mockup

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

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

Page history

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

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

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

The Zod schema definition:

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

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

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

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

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

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

Credits

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

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

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

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

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

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

Why both belong in the schema

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

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

Building a share widget with the Clipboard API

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

Original post: Building a share widget with the Clipboard API

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

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

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

The component props

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

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

LinkedIn share URL

LinkedIn's share endpoint accepts a url parameter:

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

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

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

Reddit share URL

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

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

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

Email share URL

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

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

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

Copy link with the Clipboard API

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

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

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

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

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

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

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

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

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

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

Placement in the post layout

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

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

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

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

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

Putting it together

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

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

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

Breadcrumb navigation with Schema.org markup

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

Original post: Breadcrumb navigation with Schema.org markup

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

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

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

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

The component interface

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

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

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

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

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

Auto-generation from URL path

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

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

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

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

Schema.org BreadcrumbList

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

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

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

Accessibility

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

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

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

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

Full code listing

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Adding an RSS feed to an Astro blog

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

Original post: Adding an RSS feed to an Astro blog

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

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

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

Installing the package

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

pnpm add @astrojs/rss

The feed endpoint

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

A few parts of this are easy to get wrong.

Draft filtering

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

This blog distinguishes three publication states:

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

The isPubliclyPublished utility returns true only for the published state:

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

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

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

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

Sorting

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

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

Post links

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

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

Absolute URLs

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

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

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

atom:link self-reference

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

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

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

Validating the feed

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

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

pnpm build && open dist/rss.xml

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

Adding the feed autodiscovery link

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

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

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

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

Full code listing

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

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

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

DEV Community: Roger Rajaratnam

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

Layer global and project settings

Global settings

Project-level settings

Instructions, agents, and skills

Instructions: always-on policy

Agents: task-specific operators

Skills: reusable playbooks

MCP servers

Installing common servers

Example config

When to reach for MCP

Security checklist

Rolling it out

Individual setup

Team rollout

Keeping it improving

Quick audit checklist

Further reading

Wrap up

Adding comments to a static Astro blog with Netlify Forms

The approach

The form

The functions

get-comments

comment-handler

approve-comment

Rendering comments

Gravatar avatars

Styling dynamically injected content in Astro

Registering the approved-comments form

Setting it up on Netlify

Refreshing the list after submission

What I'd do differently

Wrap-up

Adding a mailing list to a static Astro blog with Resend

What we're building

Setting up Resend Segments

The Netlify Function

Welcome email

Creating the template with a script

The Astro component

Honeypot field

Shared form utility

Environment variables

The problem with `draft: false` alone

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

Setting `pubDate` values

Where `draft` still fits in