DEV Community: Roger Rajaratnam

Building a dark/light theme toggle in Astro

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

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

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

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

The colour system

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

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

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

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

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

The toggle component

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

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

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

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

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

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

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

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

The script

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

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

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

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

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

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

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

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

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

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

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

A few things worth noting:

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

Preventing the flash of wrong theme

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

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

The priority order is:

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

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

Expressive Code alignment

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

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

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

Typed content collections in Astro

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

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

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

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

How the collection is defined

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

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

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

export const collections = { posts };

A few things worth noting:

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

Where the posts live

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

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

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

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

Querying the collection

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

import { getCollection } from "astro:content";

const allPosts = await getCollection("posts");

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

The draft flag and scheduled publishing

The draft field alone isn't the full picture. The blog uses a small utility
in src/utils/drafts.ts that combines draft status, publish date, and an
environment variable:

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

export function isPublished(post: { data: { draft: boolean; pubDate: Date } }): boolean {
  if (showDrafts) return true;
  if (post.data.draft) return false;
  return post.data.pubDate <= new Date();
}

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

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

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

This gives three distinct states:

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

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

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

Optional fields and TypeScript

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

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

What this gives you

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

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

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

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

Working on something similar?

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

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

Keeping your zsh config out of Copilot's terminals

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

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

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

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

The naive fix and why it breaks things

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

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

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

Why PATH isn't a reliable signal

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

The fix: a custom env var

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

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

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

Then in .zshrc, update the guard:

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

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

Why this works

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

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

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

That's it

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

Choosing the tech stack

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

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

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

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

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

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

Tech

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

TypeScript

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

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

Astro

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

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

Content collections

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

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

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

Zero JS by default

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

The build pipeline

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

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

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

Remark Emoji

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

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

The plugin takes two options worth knowing about:

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

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

Netlify

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

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

Resend

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

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

The integration is a few lines in a Netlify function:

import { Resend } from "resend";

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

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

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

Design

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

Bulma CSS

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

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

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

Font Awesome

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

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

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

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

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

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

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

Unsplash

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

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

Testing

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

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

AI

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

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

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

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

When this stack falls short

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

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

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

Need help choosing your stack?

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

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

How this blog was built

Roger Rajaratnam — Mon, 13 Apr 2026 18:52:01 +0000

When I launched this blog last week I wrote a post called
I Should Start a Blog — the short version of why I'd stopped putting it off.
Part of what I mentioned there was that building the site itself had been an
enjoyable project: a proper excuse to use Astro in
earnest, deploy serverless functions on Netlify, wire up email delivery through Resend.

What I didn't write about was how any of that actually works.

Diagram fallback for Dev.to. View the canonical article for the full version: https://sourcier.uk/blog/how-this-blog-was-built

The series

I've decided to fix that. Starting today, I'm publishing a series of posts that
document how this blog was built — the technical decisions, the design choices,
the problems that needed solving and how I solved them.

It is, admittedly, a slightly self-referential thing to write a blog about the
blog. But I think there's genuine value in it. These are patterns and decisions
that come up on almost any content-driven site. The answers I landed on aren't
unique to this project — they're worth writing up properly.

The series covers:

Choosing the tech stack — Live — the full stack decision: Astro for static output and content collections, Bulma for a no-runtime CSS foundation, Netlify for hosting and serverless functions, Font Awesome, Resend, and the other tools that hold it together.
Typed content collections — Live — Zod schemas, build-time validation, the draft flag pattern, and what typed frontmatter actually buys you.
Dark/light theme toggle — Live — CSS custom properties, localStorage persistence, and why not getting this right causes the flash of wrong theme.
Blog card and post hero design — 16 April — typography hierarchy, cover image pipeline, the draft overlay.
A tag system with weighted clouds — 21 April — slug normalisation, the three-tier cloud, a concentric ring layout, paginated tag pages.
OpenGraph and SEO metadata — 23 April — OG tags, Twitter Cards, canonical URLs, article metadata — all centralised in one place.
RSS in Astro — 28 April — the @astrojs/rss package, draft filtering, autodiscovery.
Breadcrumb navigation with Schema.org markup — 30 April — auto-generated crumbs, BreadcrumbList structured data, accessible aria-current.
A share widget with the Clipboard API — 5 May — LinkedIn, email, copy-link with in-place feedback.
Page history and credits — 7 May — transparent revision logs and why attribution is a first-class concern.
Deploying to Netlify — 12 May — netlify.toml, functions, environment variables, deploy previews.
Post notification emails with Resend — 14 May — a Node.js script that reads frontmatter, builds an HTML email, and sends a broadcast to subscribers.
Scheduled publishing — 19 May — a isPublished() helper that gates on both draft status and pubDate, a Netlify scheduled function, and a daily build hook so future-dated posts go live automatically.
Adding a mailing list — 21 May — Resend's Segments API, a serverless subscribe function, honeypot spam protection.
Comments on a static site — 26 May — Netlify Forms as a queue, HMAC-signed approve/delete links, three serverless functions, no database.
Mermaid diagrams — 28 May — bypassing Expressive Code, client-side rendering, theme-aware SVGs, a fullscreen lightbox.
Better code blocks — 2 June — syntax highlighting with Expressive Code, dual themes, line numbers, frames, and markers.
Sticky table of contents — 4 June — build-time heading extraction, IntersectionObserver active state.
Pagination — 9 June — clean URLs, skeleton placeholder cards, no client-side JavaScript.
A custom 404 page — 11 June — outlined text, a ghost effect, and why a dead end is worth designing properly.
Web analytics on a static Astro blog — 16 June — picking PostHog from the free options, loading the snippet only in production, and wiring up credentials with Netlify environment variables.
Moving blog content to a private repository — 18 June — splitting Markdown content into a private GitHub repo, a build-time clone with a fine-grained token, and a GitHub Actions workflow to trigger deploys on content changes.
Adding search — 19 June — Pagefind for static site search, a command-palette header modal with keyboard navigation, and the non-obvious problems with meta elements, asset hashing, and scoped styles.
Emoji reactions with Netlify Blobs — 23 June — serverless key-value storage, a Netlify Function API, and an optimistic UI with pop animations and localStorage deduplication.
Automating Dev.to cross-posting — 26 June — a Node.js script that reads your frontmatter, normalises tags, makes image URLs absolute, sets the canonical URL, and publishes in one command.

That's twenty-five posts rolling out through to late June. Some are short — a single technique worth documenting cleanly. Others go deeper. All of them are grounded in code that actually runs on this site right now. Subscribe below and you'll get each one the morning it drops — no noise, just the article.

Why write this at all

Two reasons.

The first is that documenting things properly forces me to understand them better. When I built the comment system I had a rough sense of how the HMAC signing worked. Writing it up properly — in a way that another engineer could follow — required me to be precise about the details. Every single post in this series has taught me something about my own implementation.

The second is that I genuinely couldn't find a comprehensive write-up for most of these patterns when I was building them. There are fragments — a hint in the Astro docs, a Stack Overflow answer that's half-right, a GitHub issue with a workaround. Writing them up in one place, with enough context to be useful, seems worth doing.

Working on something similar?

If you're building a content site, a developer blog, or anything along these lines and would rather not figure it all out from scratch — I'm available for consulting. I can help with architecture decisions, implementation, or a straightforward code review.

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

I Should Start a Blog

Roger Rajaratnam — Mon, 13 Apr 2026 18:51:07 +0000

I've said "I should start a blog" more times than I'd like to admit.

For years it existed as a vague intention — something I'd get around to once I had more time, once I had the perfect thing to write about, once I'd figured out exactly what my "niche" was. The usual excuses. The usual friction.

The thing is, I've been doing this job for over twenty years. I've worked across fintech, media, non-profits, and everything in between. I've mentored engineers, taught at bootcamps, led teams through big architectural decisions and painful rewrites. Somewhere along the way I accumulated a lot of opinions, patterns, and hard-won lessons — and almost none of it has been written down anywhere anyone else can read it.

That bothers me now more than it used to.

What changed

Teaching did it, honestly.

Running bootcamp sessions for The Jump Digital School forced me to take things I'd internalised and make them legible. When you have to explain why something works, not just that it works, you understand it differently. You catch the gaps in your own thinking. You realise how much of what you "know" is actually just vibes and pattern recognition that you've never had to articulate out loud.

Those sessions reminded me that I like explaining things. I like finding the clean way through a confusing concept. I find it genuinely satisfying when something clicks for someone.

A blog is that, scaled up slightly.

The other thing that pushed me over the line is AI. Not because I think it makes writing less relevant — quite the opposite. The more capable these tools become at generating code, the more important it becomes to understand what good code actually looks like, and why. AI amplifies whatever understanding you bring to it. An engineer who can't evaluate the output is just a faster way to ship the wrong thing. The knowledge worth preserving isn't the mechanical kind. It's the judgement. And that has to come from somewhere.

What I want this to be

Not a content calendar. Not a personal brand exercise. Not SEO-optimised articles with H2s engineered for search intent.

I want this to read like how I actually talk to other engineers — direct, with opinions, willing to say "this is complicated" rather than flattening nuance into a listicle. More like a long conversation than a documentation page.

The topics will mostly come from wherever my head is at. Engineering. Architecture. Technical leadership. The weird in-between space of being someone who codes and also has to communicate about code to people who don't. Occasionally something completely unrelated if it feels worth writing.

I won't pretend I'll post on a schedule. That's historically not how I work. But I will actually post, which is already an improvement on the previous arrangement.

How this will be different

A lot of engineering blogs stop at the code. Here's the snippet, here's the library, copy and paste. There's nothing wrong with that — but it doesn't explain the thinking that led there.

I'm more interested in the decisions. The trade-offs. Why this tool over that one, and what you give up either way. What the design is actually trying to communicate, not just how to implement it. When the clean abstraction is worth the added indirection, and when it's just complicating something simple.

That's because writing clean code is only part of what it means to be a good engineer. The rest is judgement — knowing what to build, how to structure it, when to push back, and how to bring other people along with you. That part rarely gets written down. It tends to stay locked in the heads of people who've been around long enough to have made the same mistakes a few times.

So that's what I'm aiming for here. Less "here's how to do the thing" and more "here's why this is the thing to do, and here's what it cost us to find that out."

The site itself

I built this with Astro — partly because it's genuinely excellent for content-focused sites, and partly because I wanted an excuse to use it properly. It's fast, it renders mostly static HTML, and the content layer is exactly as flexible as I needed it to be. No regrets there.

It's also pleasingly simple to maintain. The posts live as Markdown files in a collections/ folder. There's no CMS, no database, no admin panel. Just files, which is how I like it.

Anyway. Hello. I'm Roger. I've been in software for a long time and I've finally decided to write some of it down.

Let's see how this goes.