DEV Community: Roger Rajaratnam

Adding reading times to an Astro blog

Roger Rajaratnam — Thu, 24 Sep 2026 17:09:08 +0000

Original post: Adding reading times to an Astro blog

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

Reading times set expectations before someone commits to an article. A "2 min
read" label on a blog card tells you it's a quick technique post. "14 min read"
tells you to save it for later. Both are useful signals — and they're trivial
to add once you know which package to reach for.

This post covers adding reading times to both blog listing cards and individual
post pages in Astro, using the reading-time npm package from the
official Astro recipe.

The package

Astro's documentation recommends the reading-time
package. It accepts a string of text, counts the words, and returns a result
object including a .text property formatted as "5 min read".

pnpm add reading-time

Usage is a single function call:

import readingTime from 'reading-time';

const result = readingTime(post.body ?? '');
// result.text → "5 min read"
// result.minutes → 4.7
// result.words → 940

The .text property is what gets displayed — it rounds to the nearest minute
and appends "min read".

Where reading times appear

This blog shows reading time in two places:

Blog cards — after the publication date, separated by a middle dot: 14 Apr 2026 · 5 min read
Post page hero — in the meta bar between the date and the tag pills

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

Blog cards

The computation happens in the listing components — BlogGrid.astro for paginated
blog pages and index.astro for the homepage recent-posts grid. Both import
the package and pass the result down to BlogPost.astro:

---
import readingTime from 'reading-time';
---

{posts.map((post) => (
  <BlogPost
    title={post.data.title}
    description={post.data.description}
    url={`/blog/${post.id}`}
    cover={post.data.cover}
    pubDate={post.data.pubDate}
    readingTime={readingTime(post.body ?? '').text}
  />
))}

BlogPost.astro receives readingTime as an optional prop and appends it to
the existing date string:

---
const { description, title, subTitle, url, cover, pubDate, draft, readingTime } =
  Astro.props;
---

{formattedDate && (
  <p class="card-meta">
    {formattedDate}{readingTime && ` · ${readingTime}`}
  </p>
)}

Making readingTime optional means the card degrades gracefully in any context
where it isn't passed — no template changes needed elsewhere.

Post pages

For individual post pages, the computation lives in blog/[id].astro alongside
the existing render() call:

---
import readingTime from 'reading-time';

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

<MarkdownPostLayout
  frontmatter={post.data}
  postId={post.id}
  headings={headings}
  readingTime={postReadingTime}
>
  <Content />
</MarkdownPostLayout>

MarkdownPostLayout.astro destructures the new prop and passes it straight
through to PageHero:

const { frontmatter, postId, headings = [], readingTime } = Astro.props;

// ...

<PageHero
  title={frontmatter.title}
  date={formattedDate ?? undefined}
  readingTime={readingTime}
  tags={frontmatter.tags}
  {/* ... */}
/>

In PageHero.astro, the reading time sits between the date and the tags divider.
The condition that guards the meta bar is extended to include readingTime, and
the divider condition is updated to account for either date or reading time being
present:

{(author || date || readingTime || (tags && tags.length > 0)) && (
  <div class="page-hero__meta">
    {author && <span class="page-hero__author">By {author}</span>}
    {date && <span class="page-hero__date">{date}</span>}
    {readingTime && (
      <span class="page-hero__reading-time">{readingTime}</span>
    )}
    {(date || readingTime) && tags && tags.length > 0 && (
      <span class="page-hero__divider" aria-hidden="true" />
    )}
    {/* tags... */}
  </div>
)}

With that in place, every post page shows its reading time in the hero meta
bar next to the date, and the divider between the meta bar and the tags
appears whenever either one is present, so tags never end up floating with
no separator when a post has no author or date set.

The reading-time package does the hard part: counting words and formatting
the label. The rest of the work was just making sure that one value flowed
cleanly from post.body, through the listing pages and the post-page render,
down to the two places a reader actually sees it: the card and the hero.

Automating Dev.to cross-posting from an Astro blog

Roger Rajaratnam — Tue, 22 Sep 2026 09:45:21 +0000

Original post: Automating Dev.to cross-posting from an Astro blog

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

Dev.to has a large audience that won't find your personal blog through search.
Cross-posting gets your content in front of them, but only if you set up the
canonical URL correctly. Skip that step and you risk training search engines to
prefer the Dev.to copy over your own site.

This post walks through the cross-posting script this blog uses: a single Node.js
file that reads frontmatter from your markdown posts, converts a few
blog-specific features into Dev.to-friendly markdown, builds an article payload,
shows a preview, and asks for confirmation before publishing or updating.

How cross-posting and canonical URLs work

When you publish the same content to two URLs, search engines need a signal for
which one to treat as authoritative. The canonical URL (<link rel="canonical">)
provides that signal.

Dev.to supports a canonical_url field on its API. When set, Dev.to renders it
as the canonical link in the page <head>, pointing back to your blog. Search
engines follow that signal and credit your domain for the content, not Dev.to.

Never cross-post without setting canonical_url. Without it, Dev.to's version
may outrank your own.

Architecture

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

Setting up

Get an API key from dev.to/settings/extensions
under DEV Community API Keys. Add it, along with your site's public URL, to
.env:

DEVTO_API_KEY=your_key_here
SITE_URL=https://sourcier.uk

The script reads .env automatically if it exists, using Node 20.12's built-in
process.loadEnvFile.

Running it

pnpm crosspost:devto

The script lists published, non-future posts sorted newest-first and prompts you
to pick one from a dropdown built with @inquirer/prompts:

? Select a post to cross-post: (Use arrow keys)
❯ reactions-netlify-blobs-astro
  dark-light-theme-toggle
  comments-system
  ...

─────────────────────────────────────────
  Title        : Adding emoji reactions to your Astro blog with Netlify Blobs
  Canonical URL: https://sourcier.uk/blog/reactions-netlify-blobs-astro
  Tags         : astro, netlify, engineering, frontend
  Description  : How to add emoji reactions…
  Mermaid      : 1 converted (image mode)
  Code fences  : 3 normalised
  Series notes : 0 normalised
  SVG images   : 2 converted to links
  Original link: prepended
  Body length  : 4821 chars
─────────────────────────────────────────

Checking for existing Dev.to article by canonical URL…
No existing article found, will create a new one.

Cross-post to Dev.to? [y/N]

If a matching article already exists (found by canonical_url), the script
offers a choice instead: update the existing article, create a new one, or
cancel. Pass --update to force update mode, or --update <article-id> to
target a specific article without the canonical URL lookup.

How frontmatter is parsed

The script reads collections/posts/<slug>/index.md directly, no Astro build
needed. Frontmatter is parsed with a lightweight regex approach rather than a
full YAML library, which keeps the script dependency-free.

Tags are normalised for Dev.to's format: lowercase, alphanumeric only, maximum 4.
The # prefix Dev.to adds to tags in its UI is handled by the API automatically.

function normaliseTags(tags = []) {
  return tags
    .map((t) => t.toLowerCase().replace(/[^a-z0-9]/g, ""))
    .filter(Boolean)
    .slice(0, 4);
}

Hyphenated tags like web-performance become webperformance. That's a Dev.to
constraint: their tag system doesn't support hyphens.

Making image URLs absolute

Markdown posts reference images with paths like /post-images/slug/image.webp
or ./image.webp. Dev.to renders these relative to dev.to, not your domain,
so they'd break.

The script converts both patterns to absolute URLs before sending to the API:

function makeImagesAbsolute(markdown, slug) {
  return markdown
    .replace(/\(\/post-images\//g, `(${siteBase}/post-images/`)
    .replace(
      /\(\.\/([^)]+\.(png|jpg|jpeg|gif|webp|svg))\)/g,
      `(${siteBase}/post-images/${slug}/$1)`
    );
}

Converting mermaid diagrams to images

Dev.to doesn't run the client-side mermaid library this blog uses, so a raw
`mermaid fence would just render as an unstyled code block. The script
renders the diagram as an image instead, using the free
mermaid.ink rendering service: the diagram source is
base64url-encoded into an image URL, with a note linking back to the canonical
article for the interactive version.

`javascript
function mermaidFallback(markdown, canonicalUrl) {
const diagram = markdown.trim();
const encoded = toBase64Url(diagram);
const imageUrl = https://mermaid.ink/img/${encoded};

return [
![Mermaid diagram](${imageUrl}),
"",
> Diagram fallback for Dev.to. View the canonical article for the full version: ${canonicalUrl},
].join("\n");
}
`

Set DEVTO_MERMAID_MODE=code in .env to fall back to the raw code fence
instead, if you'd rather readers copy the diagram source.

Converting SVG wireframes to PNG

SVG images (used for wireframes and mockups on this blog) aren't reliably
supported by Dev.to's renderer. The script swaps the .svg extension for .png
in the image URL, pointing at the PNG fallback that post-images:copy already
generates for every SVG, and adds a note linking back to the original:

`javascript
function svgFallback(alt, svgUrl, canonicalUrl) {
const pngUrl = swapSvgExtension(svgUrl);

return [
![${escapeMarkdownLinkText(alt)}](${pngUrl}),
"",
> Diagram fallback for Dev.to. View the canonical article for the original SVG: ${canonicalUrl},
].join("\n");
}
`

Normalising series callouts and adding the original-post link

This blog marks series posts with a <div class="series-callout"> element,
which Dev.to would strip as unknown HTML. The script converts it into a plain
markdown blockquote, and prepends every article body with a link back to the
canonical post, since not everyone reads the canonical URL in the article
footer:

`javascript function buildOriginalPostLine(title, canonicalUrl) { return `> Original post: [${escapeMarkdownLinkText(title)}](${canonicalUrl})`; } `

Updating an already cross-posted article

Re-running pnpm crosspost:devto and selecting a post that's already on Dev.to
triggers a lookup by canonical_url against your Dev.to articles. If found, you
can update it in place rather than accidentally creating a duplicate:

`javascript async function findExistingArticleByCanonical(canonicalUrl) { const target = normaliseUrl(canonicalUrl); // paginate through /api/articles/me/all and match on canonical_url } `

This means editing a published post on your blog and re-running the script is
enough to keep the Dev.to copy in sync, no need to track article IDs manually.

What to check after publishing

Even with these conversions, Dev.to doesn't render everything your blog does:

Code block titles: title="filename.ts" attributes in fenced code blocks don't render on Dev.to. The code itself is fine.
Expressive code features like line highlighting or diff markers may not survive the normal Dev.to markdown renderer.
Fullscreen image expand buttons are added by this blog's layout at runtime, so they won't appear on Dev.to. That's expected: readers can still click through to the canonical article.

After publishing, open the article on Dev.to and do a quick visual check,
especially for any mermaid diagrams or SVG wireframes.

Full code listing

`js

!/usr/bin/env node

// Cross-posts a blog post to Dev.to with a canonical URL pointing back to sourcier.uk.
// Prepends an original-post link and converts unsupported SVG embeds into PNG fallbacks.
// Reads post content from collections/posts//index.md.
//
// Usage:
// node scripts/crosspost-devto.js
// node scripts/crosspost-devto.js --update
// node scripts/crosspost-devto.js --update
//
// Required environment variables (set in .env or shell):
// DEVTO_API_KEY - API key from https://dev.to/settings/extensions -> DEV Community API Keys
// SITE_URL - public URL of the site, e.g. https://sourcier.uk

import { select, confirm } from "@inquirer/prompts";
import { readFileSync, readdirSync, existsSync } from "fs";
import { join, resolve } from "path";

const root = resolve(new URL(".", import.meta.url).pathname, "..");

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

const apiKey = process.env.DEVTO_API_KEY;
const siteBase = (process.env.SITE_URL ?? "https://sourcier.uk").replace(
/\/$/,
"",
);
const mermaidMode = (process.env.DEVTO_MERMAID_MODE ?? "image").toLowerCase();

function parseCliArgs(argv) {
let explicitArticleId = null;
let updateOnly = false;

for (let i = 0; i < argv.length; i += 1) {
const arg = argv[i];

if (arg === "--help" || arg === "-h") {
  console.log("Usage:");
  console.log("  node scripts/crosspost-devto.js");
  console.log("  node scripts/crosspost-devto.js --update");
  console.log(
    "  node scripts/crosspost-devto.js --update <devto-article-id>",
  );
  process.exit(0);
}

if (arg === "--update") {
  updateOnly = true;
  const maybeId = argv[i + 1];
  if (maybeId && !maybeId.startsWith("--")) {
    explicitArticleId = Number(maybeId);
    i += 1;
  }
  continue;
}

console.error(`Error: Unknown argument '${arg}'.`);
console.error("Use --help to see supported options.");
process.exit(1);

}

return { explicitArticleId, updateOnly };
}

const { explicitArticleId, updateOnly } = parseCliArgs(process.argv.slice(2));

if (!apiKey) {
console.error("Error: DEVTO_API_KEY environment variable is required.");
console.error("Get one at: https://dev.to/settings/extensions");
process.exit(1);
}

if (explicitArticleId !== null && !Number.isInteger(explicitArticleId)) {
console.error("Error: --update must be a valid integer.");
process.exit(1);
}

// -- Frontmatter parser --------------------------------------------------------

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();
}

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(" ");
}

// Parse tags array: tags: ["tag1", "tag2"]
const tagsMatch = yaml.match(/^tags:\s*[(.+?)]/m);
if (tagsMatch) {
result.tags = tagsMatch[1]
.split(",")
.map((t) => t.trim().replace(/^["']|["']$/g, ""));
}

return result;
}

function stripFrontmatter(content) {
return content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, "").trim();
}

// Dev.to tags: lowercase alphanumeric only, max 4
function normaliseTags(tags = []) {
return tags
.map((t) => t.toLowerCase().replace(/[^a-z0-9]/g, ""))
.filter(Boolean)
.slice(0, 4);
}

function escapeMarkdownLinkText(value) {
return String(value ?? "")
.replace(/\/g, "\\")
.replace(/[/g, "\[")
.replace(/]/g, "\]");
}

function makeUrlAbsolute(url) {
if (!url) return url;
if (/^https?:\/\//i.test(url)) return url;
if (url.startsWith("/")) return ${siteBase}${url};
return url;
}

function buildOriginalPostLine(title, canonicalUrl) {
return > Original post: [${escapeMarkdownLinkText(title)}](${canonicalUrl});
}

function swapSvgExtension(url) {
return url.replace(/.svg(?=(?:\?[^)]*)?$)/i, ".png");
}

// Replace relative /post-images/ paths and ./image references with absolute URLs
function makeImagesAbsolute(markdown, slug) {
return markdown
.replace(/(\/post-images\//g, (${siteBase}/post-images/)
.replace(
/(.\/([^)]+.(png|jpg|jpeg|gif|webp|svg)))/g,
(${siteBase}/post-images/${slug}/$1),
);
}

function stripHtmlTags(str) {
let result = str;
let prev;
do {
prev = result;
result = result.replace(/<[^>]*>?/g, "");
} while (result !== prev);
return result;
}

function normaliseSeriesCallout(line) {
const match = line.match(
/^

([^<]+)<\/span>([\s\S]*?)<\/span><\/div>$/,
);

if (!match) return null;

const label = match[1].trim();
const text = stripHtmlTags(
match[2].replace(
/([\s\S]*?)<\/a>/g,
(_, href, linkText) =>
[${escapeMarkdownLinkText(stripHtmlTags(linkText))}](${makeUrlAbsolute(href)}),
),
)
.replace(/\s+/g, " ")
.trim();

return > ${label}: ${text};
}

function toBase64Url(value) {
return Buffer.from(value, "utf8")
.toString("base64")
.replace(/+/g, "-")
.replace(/\//g, "_")
.replace(/=+$/g, "");
}

function normaliseFenceLanguage(info) {
const token = info.trim().split(/\s+/)[0] ?? "";
return /^[a-z0-9#+.-]+$/i.test(token) ? token.toLowerCase() : "";
}

function mermaidFallback(markdown, canonicalUrl) {
const diagram = markdown.trim();
if (!diagram) return "";

if (mermaidMode === "code") {
return [
> Mermaid diagram is available in the canonical article: ${canonicalUrl},
"",
"mermaid", diagram, "",
].join("\n");
}

const encoded = toBase64Url(diagram);
const imageUrl = https://mermaid.ink/img/${encoded};

return [
![Mermaid diagram](${imageUrl}),
"",
> Diagram fallback for Dev.to. View the canonical article for the full version: ${canonicalUrl},
].join("\n");
}

function svgFallback(alt, svgUrl, canonicalUrl) {
const pngUrl = swapSvgExtension(svgUrl);

return [
![${escapeMarkdownLinkText(alt)}](${pngUrl}),
"",
> Diagram fallback for Dev.to. View the canonical article for the original SVG: ${canonicalUrl},
].join("\n");
}

function normaliseSvgImage(line, canonicalUrl) {
const match = line.match(/^![([^]])](([^)\s]+.svg(?:\?[^)])?))$/i);
if (!match) return null;

const alt = match[1].trim() || "Diagram";
const url = match[2];

return svgFallback(alt, url, canonicalUrl);
}

function normaliseMarkdownForDevto(markdown, canonicalUrl, title) {
const lines = markdown.split(/\r?\n/);
const output = [];
const stats = {
mermaidBlocks: 0,
codeFencesNormalised: 0,
seriesCalloutsNormalised: 0,
svgImagesConverted: 0,
};

let inFence = false;
let fenceMarker = "";
let fenceInfo = "";
let fenceLines = [];

for (const line of lines) {
if (!inFence) {
const open = line.match(/^(`{3,})(.*)$/);
if (!open) {
const seriesCallout = normaliseSeriesCallout(line);
if (seriesCallout) {
stats.seriesCalloutsNormalised += 1;
output.push(seriesCallout);
continue;
}

    const svgImage = normaliseSvgImage(line, canonicalUrl);
    if (svgImage) {
      stats.svgImagesConverted += 1;
      output.push(svgImage);
      continue;
    }

    output.push(line);
    continue;
  }

  inFence = true;
  fenceMarker = open[1];
  fenceInfo = open[2] ?? "";
  fenceLines = [];
  continue;
}

const trimmed = line.trim();
const isFenceClose =
  trimmed.startsWith(fenceMarker) &&
  /^`+$/.test(trimmed) &&
  trimmed.length >= fenceMarker.length;

if (!isFenceClose) {
  fenceLines.push(line);
  continue;
}

const rawCode = fenceLines.join("\n");
const language = normaliseFenceLanguage(fenceInfo);

if (language === "mermaid") {
  stats.mermaidBlocks += 1;
  output.push(mermaidFallback(rawCode, canonicalUrl));
} else {
  if (fenceInfo.trim()) stats.codeFencesNormalised += 1;
  output.push(language ? `\`\`\`${language}` : "

      output.push(rawCode);
      output.push("```

");
    }

    inFence = false;
    fenceMarker = "";
    fenceInfo = "";
    fenceLines = [];
  }

  if (inFence) {
    output.push(`${fenceMarker}${fenceInfo}`);
    output.push(...fenceLines);
  }

  return {
    markdown: `${buildOriginalPostLine(title, canonicalUrl)}\n\n${output.join("\n").trimStart()}`,
    stats,
  };
}

function loadPost(slug) {
  const filePath = join(root, "collections", "posts", slug, "index.md");
  let raw;
  try {
    raw = readFileSync(filePath, "utf8");
  } catch {
    throw new Error(`Post not found: collections/posts/${slug}/index.md`);
  }
  const fm = parseFrontmatter(raw);
  if (!fm.title) throw new Error(`No title found in frontmatter for: ${slug}`);

  const title = fm.title.replace(/^["']|["']$/g, "");
  const canonicalUrl = `${siteBase}/blog/${slug}`;
  const markdownBody = makeImagesAbsolute(stripFrontmatter(raw), slug);
  const normalised = normaliseMarkdownForDevto(
    markdownBody,
    canonicalUrl,
    title,
  );

  return {
    title,
    description: fm.description || "",
    tags: normaliseTags(fm.tags),
    draft: fm.draft === "true",
    pubDate: fm.pubDate ? new Date(fm.pubDate) : null,
    body: normalised.markdown,
    canonicalUrl,
    transformStats: normalised.stats,
  };
}

function listPostIds() {
  const postsDir = join(root, "collections", "posts");
  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);
        return {
          id: d.name,
          pubDate: fm.pubDate ? new Date(fm.pubDate) : new Date(0),
          isDraft: fm.draft === "true",
          isFuture: fm.pubDate ? new Date(fm.pubDate) > new Date() : false,
        };
      } catch {
        return null;
      }
    })
    .filter((p) => p && !p.isDraft && !p.isFuture)
    .sort((a, b) => b.pubDate - a.pubDate)
    .map((p) => p.id);
}

function normaliseUrl(value) {
  return String(value || "").replace(/\/$/, "");
}

function buildArticlePayload(post) {
  return {
    article: {
      title: post.title,
      body_markdown: post.body,
      published: true,
      canonical_url: post.canonicalUrl,
      description: post.description,
      tags: post.tags,
    },
  };
}

async function findExistingArticleByCanonical(canonicalUrl) {
  const target = normaliseUrl(canonicalUrl);
  let page = 1;
  const perPage = 100;

  while (true) {
    const res = await fetch(
      `https://dev.to/api/articles/me/all?page=${page}&per_page=${perPage}`,
      {
        headers: {
          "api-key": apiKey,
        },
      },
    );

    const data = await res.json();

    if (!res.ok) {
      throw new Error(
        `Unable to list Dev.to articles (${res.status}): ${JSON.stringify(data)}`,
      );
    }

    if (!Array.isArray(data) || data.length === 0) return null;

    const existing = data.find((article) => {
      const canonical = normaliseUrl(article.canonical_url);
      return canonical && canonical === target;
    });

    if (existing) return existing;
    if (data.length < perPage) return null;

    page += 1;
  }
}

// -- Select post ----------------------------------------------------------------

const postIds = listPostIds();
if (postIds.length === 0) {
  console.log("\nNo published posts found.");
  process.exit(0);
}

const slug = await select({
  message: "Select a post to cross-post:",
  choices: postIds.map((id) => ({ value: id })),
}).catch(() => process.exit(0));

let post;
try {
  post = loadPost(slug);
} catch (err) {
  console.error(`Error: ${err.message}`);
  process.exit(1);
}

// -- Preview ---------------------------------------------------------------------

console.log("\n─────────────────────────────────────────");
console.log(`  Title        : ${post.title}`);
console.log(`  Canonical URL: ${post.canonicalUrl}`);
console.log(`  Tags         : ${post.tags.join(", ") || "(none)"}`);
console.log(
  `  Description  : ${post.description.slice(0, 80)}${post.description.length > 80 ? "…" : ""}`,
);
console.log(
  `  Mermaid      : ${post.transformStats.mermaidBlocks} converted (${mermaidMode} mode)`,
);
console.log(
  `  Code fences  : ${post.transformStats.codeFencesNormalised} normalised`,
);
console.log(
  `  Series notes : ${post.transformStats.seriesCalloutsNormalised} normalised`,
);
console.log(
  `  SVG images   : ${post.transformStats.svgImagesConverted} converted to links`,
);
console.log("  Original link: prepended");
console.log(`  Body length  : ${post.body.length} chars`);
console.log("─────────────────────────────────────────\n");

// -- Detect existing Dev.to article -----------------------------------------

let existingArticle = null;

if (explicitArticleId !== null) {
  existingArticle = { id: explicitArticleId };
  console.log(
    `--update ${explicitArticleId} provided - forcing update mode.\n`,
  );
} else {
  console.log("Checking for existing Dev.to article by canonical URL…");
  try {
    existingArticle = await findExistingArticleByCanonical(post.canonicalUrl);
  } catch (err) {
    console.error(`Error: ${err.message}`);
    process.exit(1);
  }
  if (existingArticle) {
    console.log(
      `Found existing article: https://dev.to/articles/${existingArticle.id}\n`,
    );
  } else {
    console.log("No existing article found - will create a new one.\n");
  }
}

const isUpdate = Boolean(existingArticle?.id);

if (updateOnly && !isUpdate) {
  console.error(
    "Error: --update was set, but no existing Dev.to article was found for this canonical URL.",
  );
  console.error("Re-run without --update to create a new article instead.");
  process.exit(1);
}

// -- Confirm action ------------------------------------------------------------

let proceed;

if (explicitArticleId !== null || updateOnly) {
  const ok = await confirm({
    message: `Update Dev.to article ${existingArticle.id}?`,
    default: false,
  }).catch(() => process.exit(0));
  if (!ok) {
    console.log("Aborted.");
    process.exit(0);
  }
  proceed = "update";
} else if (isUpdate) {
  proceed = await select({
    message: `An existing article was found. What would you like to do?`,
    choices: [
      { name: "Update the existing article", value: "update" },
      { name: "Create a new article", value: "create" },
      { name: "Cancel", value: "cancel" },
    ],
  }).catch(() => process.exit(0));
} else {
  const ok = await confirm({
    message: "Cross-post to Dev.to?",
    default: false,
  }).catch(() => process.exit(0));
  proceed = ok ? "create" : "cancel";
}

if (proceed === "cancel") {
  console.log("Aborted.");
  process.exit(0);
}

const doUpdate = proceed === "update";

// -- CREATE or UPDATE via Dev.to API --------------------------------------------

const endpoint = doUpdate
  ? `https://dev.to/api/articles/${existingArticle.id}`
  : "https://dev.to/api/articles";
const method = doUpdate ? "PUT" : "POST";

console.log(`\n${doUpdate ? "Updating" : "Posting"} on Dev.to…`);

const res = await fetch(endpoint, {
  method,
  headers: {
    "Content-Type": "application/json",
    "api-key": apiKey,
  },
  body: JSON.stringify(buildArticlePayload(post)),
});

const data = await res.json();

if (!res.ok) {
  console.error(
    `\nDev.to API error (${res.status}):`,
    JSON.stringify(data, null, 2),
  );
  process.exit(1);
}

console.log(`\n✓ ${doUpdate ? "Updated" : "Published"}! View at: ${data.url}`);
console.log("  Dev.to article ID:", data.id);
console.log(
  "\nNote: Mermaid and expressive code fences were normalised for Dev.to compatibility.",
);
console.log(
  "Review the Dev.to article to confirm formatting. Original-post link and canonical URL are set correctly.",
);

Adding emoji reactions to your Astro blog with Netlify Blobs

Roger Rajaratnam — Thu, 17 Sep 2026 16:09:14 +0000

Original post: Adding emoji reactions to your Astro blog with Netlify Blobs

Comments ask a lot of a reader. Reactions ask almost nothing, a single click
and a second of intent. That asymmetry is what makes them worth adding: most
readers who found your post useful will never write a comment, but many of them
will click a heart or a lightbulb if you make it easy enough.

This post covers the full implementation on this blog: a Netlify Blobs store
for persistence, a serverless function for the API, and an Astro component that
handles optimistic updates, localStorage deduplication, and a pop animation that
makes the whole thing feel alive.

Architecture overview

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

The client side is purely progressive: if the function call fails, the optimistic
increment still shows. On the next page load, fetchCounts corrects it.

Setting up Netlify Blobs

Netlify Blobs is a managed key-value store included on all Netlify plans, no
database to provision, no connection strings to manage. When deployed, it works
with zero configuration. For local development, the explicit fallback is
NETLIFY_SITE_ID plus either NETLIFY_AUTH_TOKEN or NETLIFY_PAT
in .env:

NETLIFY_PAT=           # personal access token — use NETLIFY_PAT, not NETLIFY_ACCESS_TOKEN
                       # (Netlify auto-injects NETLIFY_ACCESS_TOKEN at runtime with a limited
                       # site-scoped machine token, which overwrites any value you set)
NETLIFY_SITE_ID=       # visible in Site configuration → General → Site ID
# Optional: NETLIFY_AUTH_TOKEN=  # use this only if you want a separate Blobs token

Install the package:

pnpm add @netlify/blobs

The serverless function

The function lives at netlify/functions/reactions.ts and handles GET (fetch
counts), POST (record a reaction), and OPTIONS (CORS preflight):

import type { HandlerEvent } from "@netlify/functions";
import { connectLambda, getStore } from "@netlify/blobs";

const REACTIONS = ["heart", "fire", "bulb", "clap"] as const;
// Matches slugs like "deploying-astro-netlify" — prevents path traversal
const SLUG_RE = /^[a-z0-9-]+$/;

const CORS = {
  "Access-Control-Allow-Origin":
    process.env.SITE_URL?.replace(/\/$/, "") ?? "*",
  "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
  "Access-Control-Allow-Headers": "Content-Type",
};

function getReactionsStore(event: HandlerEvent & { blobs?: string }) {
  if (event.blobs && event.headers?.["x-nf-site-id"]) {
    connectLambda(event as any);
    return getStore("reactions");
  }

  const siteID = process.env.NETLIFY_SITE_ID;
  const token = process.env.NETLIFY_AUTH_TOKEN ?? process.env.NETLIFY_PAT;

  if (siteID && token) {
    return getStore("reactions", { siteID, token });
  }

  return getStore("reactions");
}

export const handler = async (event: HandlerEvent & { blobs?: string }) => {
  if (event.httpMethod === "OPTIONS") {
    return { statusCode: 204, headers: CORS, body: "" };
  }

  const postId = event.queryStringParameters?.post ?? "";
  if (!postId || !SLUG_RE.test(postId)) {
    return {
      statusCode: 400,
      headers: CORS,
      body: JSON.stringify({ error: "Invalid post ID" }),
    };
  }

  const store = getReactionsStore(event);

  if (event.httpMethod === "GET") {
    const data = (await store.get(postId, { type: "json" })) ?? {};
    return {
      statusCode: 200,
      headers: { ...CORS, "Content-Type": "application/json" },
      body: JSON.stringify(data),
    };
  }

  if (event.httpMethod === "POST") {
    let body: { reaction?: unknown };
    try {
      body = JSON.parse(event.body ?? "{}");
    } catch {
      return {
        statusCode: 400,
        headers: CORS,
        body: JSON.stringify({ error: "Invalid JSON" }),
      };
    }

    const reaction = body.reaction;
    if (!REACTIONS.includes(reaction as (typeof REACTIONS)[number])) {
      return {
        statusCode: 400,
        headers: CORS,
        body: JSON.stringify({ error: "Invalid reaction" }),
      };
    }

    const data: Record<string, number> =
      (await store.get(postId, { type: "json" })) ?? {};
    data[reaction as string] = (data[reaction as string] ?? 0) + 1;
    await store.set(postId, JSON.stringify(data));

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

  return { statusCode: 405, headers: CORS, body: "Method not allowed" };
};

A few things worth noting:

The SLUG_RE regex is the security boundary: it ensures postId can only be an alphanumeric slug, preventing any path traversal or injection into the store key.
The CORS headers and the OPTIONS branch exist because the reactions widget can be embedded and fetched from more than one origin during local development. SITE_URL narrows the allowed origin in production.
In Netlify's Lambda compatibility mode, connectLambda(event) has to run before getStore. Without it, the Blobs client has no runtime context and throws the missing siteID, token error.
The explicit NETLIFY_SITE_ID plus token fallback keeps the function usable in local scripts and any path where Netlify hasn't injected that context.
The POST handler wraps JSON.parse in a try/catch so a malformed request body returns a clean 400 instead of an unhandled exception.
store.get returns null if the key doesn't exist, so ?? {} handles the cold-start case cleanly.
The function returns the full updated counts on POST so the client can sync without a second GET, one round trip per reaction.

The Astro component

The component has three responsibilities: load counts on mount, post reactions on
click, and preserve which reactions the current user has already given.

Preventing duplicate votes

There's no authentication on this blog, so duplicate prevention is localStorage-based.
Each post gets a key of reactions:<slug> holding a JSON array of reaction keys
the user has already clicked. On mount, this set is read back and used to restore
the active button state.

This means:

Clearing localStorage clears the deduplication state, by design.
It doesn't prevent someone from opening a private window. That's an acceptable tradeoff for a zero-auth reaction system.
It does prevent the common case: a page refresh or return visit triggering accidental double-counting.

Optimistic updates

When a button is clicked, the count increments immediately in the UI before the
API call returns. This makes the interaction feel instant. Once the API responds,
the displayed counts are replaced with the server truth, which will be identical
in the normal case and correct in the rare case of a race condition.

async function postReaction(btn: HTMLButtonElement) {
  const reaction = btn.dataset.reaction!;
  if (reacted.has(reaction)) return; // already voted

  reacted.add(reaction);
  saveReacted(); // persist to localStorage immediately

  // Optimistic increment — no waiting for the network
  const countEl = btn.querySelector<HTMLElement>(".reactions__count")!;
  const current = parseInt(countEl.textContent ?? "0", 10) || 0;
  countEl.textContent = String(current + 1);

  const res = await fetch(`/.netlify/functions/reactions?post=${postId}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ reaction }),
  });
  if (res.ok) {
    const data = await res.json();
    // Sync all buttons with server truth
    root.querySelectorAll<HTMLButtonElement>(".reactions__btn").forEach((b) => {
      updateButton(b, data[b.dataset.reaction!] ?? 0);
    });
  }
}

The pop animation

A small @keyframes animation triggers on click for tactile feedback:

@keyframes btn-pop {
  0%   { transform: scale(1); }
  40%  { transform: scale(1.22); }
  70%  { transform: scale(0.94); }
  100% { transform: scale(1); }
}

The class is added, a reflow is forced with void btn.offsetWidth, then the class
is re-added, this restarts the animation even if the same button is clicked twice
quickly. prefers-reduced-motion is respected by removing the transition on the
emoji element.

Placement: hero and page menu, not a standalone block

The Reactions component takes variant and compact props so the same
markup and script can adapt to two very different contexts without duplicating
logic:

Post hero. <Reactions postId={postId} variant="hero" compact /> sits in the engagement row directly under the title, next to the share button. The hero variant visually hides the heading and shrinks the buttons into a row of compact pills, so reacting is the first thing a reader can do, before they've committed to reading the whole article.
Page menu. <Reactions postId={postId} compact /> sits inside the floating page menu panel, alongside the table of contents, share, and support sections. This keeps reacting reachable from anywhere while scrolling, without competing for space with the article body.

Both placements pass compact, which switches the buttons to a horizontal
pill layout and hides the text label, leaving only the emoji and count. The
hero variant additionally visually hides the heading for screen-reader-only
context, since the surrounding UI already makes the purpose clear.

This spreads the interaction across two low-friction entry points instead of
funnelling it through a single comments-adjacent widget.

What the counts look like when empty

On first load before any reactions, counts display — rather than 0. This is a
deliberate choice: 0 signals "nobody found this useful", which is discouraging
for a new post. A dash is neutral and avoids that framing.

Local development

With connectLambda(event) in place, netlify dev injects the Blobs context
for Lambda compatibility functions and runs the store in local sandbox mode.
If that context isn't available, the NETLIFY_SITE_ID plus token fallback still
lets the function connect manually.

That keeps normal local development isolated from production while still making
the function portable outside Netlify's request pipeline.

Full code listing

// Stores and retrieves emoji reaction counts for blog posts using Netlify Blobs.
//
// GET  /.netlify/functions/reactions?post=<slug>  → { heart: N, fire: N, bulb: N, clap: N }
// POST /.netlify/functions/reactions?post=<slug>  body: { reaction: "heart" }  → updated counts
//
// Local dev: requires NETLIFY_SITE_ID plus either NETLIFY_AUTH_TOKEN or
// NETLIFY_PAT in .env
// Production: works automatically with no extra config

import type { HandlerEvent } from "@netlify/functions";
import { connectLambda, getStore } from "@netlify/blobs";

const REACTIONS = ["heart", "fire", "bulb", "clap"] as const;
// Matches slugs like "deploying-astro-netlify" — prevents path traversal
const SLUG_RE = /^[a-z0-9-]+$/;

const CORS = {
  "Access-Control-Allow-Origin":
    process.env.SITE_URL?.replace(/\/$/, "") ?? "*",
  "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
  "Access-Control-Allow-Headers": "Content-Type",
};

function getReactionsStore(event: HandlerEvent & { blobs?: string }) {
  if (event.blobs && event.headers?.["x-nf-site-id"]) {
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    connectLambda(event as any);
    return getStore("reactions");
  }

  const siteID = process.env.NETLIFY_SITE_ID;
  const token = process.env.NETLIFY_AUTH_TOKEN ?? process.env.NETLIFY_PAT;

  if (siteID && token) {
    return getStore("reactions", { siteID, token });
  }

  return getStore("reactions");
}

export const handler = async (event: HandlerEvent & { blobs?: string }) => {
  if (event.httpMethod === "OPTIONS") {
    return { statusCode: 204, headers: CORS, body: "" };
  }

  const postId = event.queryStringParameters?.post ?? "";
  if (!postId || !SLUG_RE.test(postId)) {
    return {
      statusCode: 400,
      headers: CORS,
      body: JSON.stringify({ error: "Invalid post ID" }),
    };
  }

  const store = getReactionsStore(event);

  if (event.httpMethod === "GET") {
    const data = (await store.get(postId, { type: "json" })) ?? {};
    return {
      statusCode: 200,
      headers: { ...CORS, "Content-Type": "application/json" },
      body: JSON.stringify(data),
    };
  }

  if (event.httpMethod === "POST") {
    let body: { reaction?: unknown };
    try {
      body = JSON.parse(event.body ?? "{}");
    } catch {
      return {
        statusCode: 400,
        headers: CORS,
        body: JSON.stringify({ error: "Invalid JSON" }),
      };
    }

    const reaction = body.reaction;
    if (!REACTIONS.includes(reaction as (typeof REACTIONS)[number])) {
      return {
        statusCode: 400,
        headers: CORS,
        body: JSON.stringify({ error: "Invalid reaction" }),
      };
    }

    const data: Record<string, number> =
      (await store.get(postId, { type: "json" })) ?? {};
    data[reaction as string] = (data[reaction as string] ?? 0) + 1;
    await store.set(postId, JSON.stringify(data));

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

  return { statusCode: 405, headers: CORS, body: "Method not allowed" };
};

---
interface Props {
  postId: string;
  variant?: "default" | "hero";
  compact?: boolean;
}
const { postId, variant = "default", compact = false } = Astro.props;
const heading =
  variant === "hero" ? "Was this useful?" : "Did you find this useful?";

const reactions = [
  { key: "heart", emoji: "❤️", label: "Love it" },
  { key: "fire", emoji: "🔥", label: "On fire" },
  { key: "bulb", emoji: "💡", label: "Insightful" },
  { key: "clap", emoji: "👏", label: "Helpful" },
] satisfies { key: string; emoji: string; label: string }[];
---

<div
  class:list={[
    "reactions",
    {
      "reactions--hero": variant === "hero",
      "reactions--compact": compact,
    },
  ]}
  data-post-id={postId}
  aria-label="Post reactions"
>
  <p class="reactions__heading">{heading}</p>
  <div class="reactions__buttons" role="group" aria-label="React to this post">
    {
      reactions.map((r) => (
        <button
          class="reactions__btn"
          data-reaction={r.key}
          aria-label={r.label}
          aria-pressed="false"
          type="button"
        >
          <span class="reactions__emoji" aria-hidden="true">
            {r.emoji}
          </span>
          <span class="reactions__count" aria-live="polite">
            —
          </span>
          <span class="reactions__label">{r.label}</span>
        </button>
      ))
    }
  </div>
</div>

<script>
  document.querySelectorAll<HTMLElement>(".reactions").forEach((root) => {
    if (root.dataset.bound === "true") return;
    root.dataset.bound = "true";

    const postId = root.dataset.postId;
    if (!postId) return;
    const storageKey = `reactions:${postId}`;

    function loadReacted(): string[] {
      try {
        const stored = JSON.parse(localStorage.getItem(storageKey) ?? "[]");
        return Array.isArray(stored)
          ? stored.filter((value): value is string => typeof value === "string")
          : [];
      } catch {
        return [];
      }
    }

    const reacted = new Set<string>(loadReacted());

    function saveReacted() {
      localStorage.setItem(storageKey, JSON.stringify([...reacted]));
    }

    function updateButton(btn: HTMLButtonElement, count: number) {
      const reaction = btn.dataset.reaction;
      if (!reaction) return;
      const countEl = btn.querySelector<HTMLElement>(".reactions__count")!;
      countEl.textContent = count > 0 ? String(count) : "—";
      const hasReacted = reacted.has(reaction);
      btn.classList.toggle("reactions__btn--active", hasReacted);
      btn.setAttribute("aria-pressed", hasReacted ? "true" : "false");
    }

    // Load current counts from the API
    async function fetchCounts() {
      try {
        const res = await fetch(`/.netlify/functions/reactions?post=${postId}`);
        if (!res.ok) return;
        const data: Record<string, number> = await res.json();
        root
          .querySelectorAll<HTMLButtonElement>(".reactions__btn")
          .forEach((btn) => {
            updateButton(btn, data[btn.dataset.reaction!] ?? 0);
          });
      } catch {}
    }

    // Post a reaction
    async function postReaction(btn: HTMLButtonElement) {
      const reaction = btn.dataset.reaction!;
      if (reacted.has(reaction)) return;

      reacted.add(reaction);
      saveReacted();
      btn.classList.add("reactions__btn--active");
      btn.setAttribute("aria-pressed", "true");
      btn.classList.remove("reactions__btn--pop");
      void btn.offsetWidth; // force reflow to restart animation
      btn.classList.add("reactions__btn--pop");

      // Optimistic increment
      const countEl = btn.querySelector<HTMLElement>(".reactions__count")!;
      const current = parseInt(countEl.textContent ?? "0", 10) || 0;
      countEl.textContent = String(current + 1);

      try {
        const res = await fetch(
          `/.netlify/functions/reactions?post=${postId}`,
          {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ reaction }),
          },
        );
        if (res.ok) {
          const data: Record<string, number> = await res.json();
          // Sync with server truth
          root
            .querySelectorAll<HTMLButtonElement>(".reactions__btn")
            .forEach((b) => {
              updateButton(b, data[b.dataset.reaction!] ?? 0);
            });
        }
      } catch {}
    }

    fetchCounts();

    root
      .querySelectorAll<HTMLButtonElement>(".reactions__btn")
      .forEach((btn) => {
        btn.addEventListener("click", () => postReaction(btn));
      });
  });
</script>

<style lang="scss">
  @keyframes btn-pop {
    0% {
      transform: scale(1);
    }
    40% {
      transform: scale(1.22);
    }
    70% {
      transform: scale(0.94);
    }
    100% {
      transform: scale(1);
    }
  }

  .reactions {
    margin-bottom: 2.5rem;
  }

  .reactions--hero {
    margin: 0;
  }

  .reactions--compact {
    margin: 0;
  }

  .reactions__heading {
    font-family: "Barlow Condensed", sans-serif;
    font-size: 1.25rem;
    font-weight: 800;
    text-transform: uppercase;
    letter-spacing: 0.04em;
    color: var(--text-primary);
    margin: 0 0 1.25rem;
  }

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

  .reactions__btn {
    display: flex;
    flex-direction: column;
    align-items: center;
    gap: 0.25rem;
    min-width: 5rem;
    padding: 1rem 1.25rem;
    border: 2px solid var(--border-subtle);
    border-radius: var(--radius-compact);
    background: transparent;
    cursor: pointer;
    transition:
      border-color 0.15s ease,
      background-color 0.15s ease,
      transform 0.15s ease;

    @media (max-width: 639px) {
      min-width: 4.25rem;
      padding: 0.875rem 1rem;
    }

    &:hover {
      border-color: var(--accent-primary);
      background-color: rgba(var(--accent-primary-rgb), 0.04);
      transform: translateY(-2px);

      .reactions__emoji {
        transform: scale(1.15);
      }
    }

    &--active {
      border-color: var(--accent-primary);
      background-color: rgba(var(--accent-primary-rgb), 0.08);

      .reactions__count {
        color: var(--accent-primary);
      }
      .reactions__label {
        color: var(--accent-primary);
      }
    }

    &--pop {
      animation: btn-pop 0.35s cubic-bezier(0.36, 0.07, 0.19, 0.97) both;
    }
  }

  .reactions__emoji {
    font-size: 1.75rem;
    line-height: 1;
    transition: transform 0.15s ease;

    @media (prefers-reduced-motion: reduce) {
      transition: none;
    }
  }

  .reactions__count {
    font-family: "Barlow Condensed", sans-serif;
    font-size: 1.25rem;
    font-weight: 800;
    line-height: 1;
    color: var(--text-primary);
    transition: color 0.15s ease;
  }

  .reactions__label {
    font-family: "Barlow Condensed", sans-serif;
    font-size: 0.7rem;
    font-weight: 700;
    text-transform: uppercase;
    letter-spacing: 0.08em;
    color: var(--text-muted);
    transition: color 0.15s ease;
  }

  .reactions--compact .reactions__heading {
    position: absolute;
    width: 1px;
    height: 1px;
    padding: 0;
    margin: -1px;
    overflow: hidden;
    clip: rect(0, 0, 0, 0);
    white-space: nowrap;
    border: 0;
  }

  .reactions--compact .reactions__buttons {
    gap: 0.45rem;
    justify-content: flex-end;
  }

  .reactions--compact .reactions__btn {
    flex-direction: row;
    justify-content: center;
    min-width: auto;
    gap: 0.35rem;
    padding: 0.5rem 0.65rem;
    border-width: 1px;
    border-radius: var(--radius-pill);
    border-color: color-mix(
      in srgb,
      rgba(var(--overlay-rgb), 0.16) 35%,
      var(--border-subtle)
    );
    background: color-mix(
      in srgb,
      var(--surface-elevated) 76%,
      rgba(var(--overlay-rgb), 0.08)
    );
    backdrop-filter: blur(8px);
  }

  .reactions--compact .reactions__emoji {
    font-size: 1rem;
  }

  .reactions--compact .reactions__count {
    min-width: 1ch;
    font-size: 0.95rem;
  }

  .reactions--compact .reactions__label {
    display: none;
  }

  @media (max-width: 1023px) {
    .reactions--compact.reactions--hero .reactions__heading {
      position: static;
      width: auto;
      height: auto;
      padding: 0;
      margin: 0 0 0.75rem;
      overflow: visible;
      clip: auto;
      white-space: normal;
      border: 0;
      font-size: 0.76rem;
      letter-spacing: 0.1em;
      color: color-mix(in srgb, var(--text-primary) 72%, transparent);
    }

    .reactions--compact.reactions--hero .reactions__buttons {
      justify-content: flex-start;
      gap: 0.5rem;
    }
  }

  .reactions--hero .reactions__heading {
    margin-bottom: 0.75rem;
    font-size: 0.76rem;
    letter-spacing: 0.1em;
    color: color-mix(in srgb, var(--text-primary) 72%, transparent);
  }

  .reactions--hero .reactions__buttons {
    gap: 0.5rem;
  }

  .reactions--hero .reactions__btn {
    flex-direction: row;
    justify-content: center;
    min-width: auto;
    gap: 0.45rem;
    padding: 0.55rem 0.8rem;
    border-width: 1px;
    border-radius: var(--radius-pill);
    border-color: color-mix(
      in srgb,
      rgba(var(--overlay-rgb), 0.16) 35%,
      var(--border-subtle)
    );
    background: color-mix(
      in srgb,
      var(--surface-elevated) 76%,
      rgba(var(--overlay-rgb), 0.08)
    );
    backdrop-filter: blur(8px);
  }

  .reactions--hero .reactions__emoji {
    font-size: 1.1rem;
  }

  .reactions--hero .reactions__count {
    min-width: 1ch;
    font-size: 1rem;
  }

  .reactions--hero .reactions__label {
    display: none;
  }

  @media (max-width: 639px) {
    .reactions--hero .reactions__btn {
      padding: 0.55rem 0.75rem;
    }
  }
</style>

Adding search to a static Astro blog

Roger Rajaratnam — Tue, 15 Sep 2026 16:56:53 +0000

Original post: Adding search to a static Astro blog

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

Static sites have an obvious gap: there is no server to run a query against. Everything lives in pre-built HTML files on a CDN. The conventional workarounds are to ship users off to Google with a site: filter, drop in Algolia, or accept that search just isn't a feature.

None of those felt right. Sending users to Google is a dead end. Algolia has a free tier, but it's an external dependency that needs a sync pipeline and will eventually bill you. And a developer blog without search is awkward the moment you have more than a handful of posts.

Pagefind is the answer for static sites. It crawls the built HTML, generates a WASM-based index at build time, and serves everything as static files alongside your site. No server, no external service, no runtime dependency. The index ships with the site.

Architecture overview

The full setup spans build time, the content repo, and the browser. Here's where the pieces connect:

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

The modal UI

The search trigger is a single icon button in the navbar. Clicking it opens a full-viewport overlay with an input and a scrollable results list:

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

The highlighted row shows keyboard focus. Escape or clicking the backdrop closes it. ↑ / ↓ move focus through results. Enter navigates. Click the expand icon on the wireframe to view it fullscreen.

How Pagefind works

After astro build produces the dist/ directory, you run Pagefind against it:

npx pagefind --site dist

Pagefind walks the HTML, extracts text from elements marked with data-pagefind-body, and writes a set of compressed index files into dist/pagefind/. Those files are served as static assets. The search itself runs entirely in the browser via a small WASM module that Pagefind provides.

Install it as a dev dependency:

pnpm add -D pagefind

Then append the Pagefind step to the Netlify build command in netlify.toml:

[build]
  command = "... && astro build && npx pagefind --site dist"

Indexing locally for dev

Pagefind runs post-build and writes its index to dist/pagefind/. The Astro dev server doesn't serve from dist/, so the index isn't available during pnpm dev. The solution is a local script that builds the site, runs Pagefind, and copies the result to public/pagefind/, which the dev server does serve:

"search:index": "pnpm assets:sync && SHOW_DRAFTS=true astro build && pagefind --site dist && rm -rf public/pagefind && cp -r dist/pagefind public/pagefind"

The rm -rf before the copy is intentional. Without it, running the script twice causes cp -r to nest dist/pagefind inside an existing public/pagefind, leaving stale index fragments alongside fresh ones. The old fragments don't get replaced: they persist and corrupt results.

Both public/pagefind/ and public/search-thumbnails/ (more on those later) are gitignored, they're generated artifacts, not source files.

Marking content for indexing

By default, Pagefind indexes everything in the <body>. You can tell it to be more selective with data-pagefind-body:

<article class="post" data-pagefind-body>
  <!-- Only this element and its descendants are indexed -->
</article>

Once any element on the site has data-pagefind-body, Pagefind ignores every page that doesn't have it. This is the right default for a blog: you only want post content indexed, not the navigation, footer, and sidebar that appear on every page.

This goes on MarkdownPostLayout.astro, which wraps every post.

A modal, not a search page

The obvious implementation is a /search page with a text input that queries Pagefind. It works, but the UX feels dated: you leave your current context, navigate to a new page, and wait for a result.

The better pattern is a command-palette style modal that opens inline wherever you are. Type a query, see results immediately, navigate with arrow keys, press Enter to go. It feels modern and fast, and it doesn't interrupt the reading flow.

The header gets a magnifying glass button:

<button class="social-icon" aria-label="Open search" data-search-open>
  <!-- Font Awesome icon -->
</button>

Clicking it opens a modal overlay with an input and a results list. Keyboard handling covers the full expected surface: Escape closes, ArrowUp/ArrowDown move through results, Enter follows the active result.

Pagefind's JS API

Pagefind ships a default UI component, but it has strong opinions about styling and it generates its own DOM. Using the JS API directly gives full control:

const pagefind = await import('/pagefind/pagefind.js');
await pagefind.init();

const results = await pagefind.search(query);
const data = await Promise.all(results.results.slice(0, 6).map(r => r.data()));

Each result's data() call returns the page's URL, an excerpt with matched terms highlighted, and whatever was stored in data-pagefind-meta attributes.

The import('/pagefind/pagefind.js') must be a runtime dynamic import. Vite processes static imports at build time, and pagefind.js doesn't exist until after the build runs. The script in Header.astro uses is:inline so Astro doesn't process it through Vite:

<script is:inline>
  // Dynamic import runs in the browser at runtime, not at build time
  const pagefind = await import('/pagefind/pagefind.js');
</script>

Pagefind is only initialised once. The first search triggers the init, and subsequent queries reuse the already-loaded instance.

Metadata: title and cover image

Pagefind reads data-pagefind-meta attributes to store custom fields alongside each result. The initial attempt used a single attribute on the <article> element:

<article data-pagefind-body data-pagefind-meta="title:Choosing the tech stack,image:/_astro/cover.webp">

This produces results where the title field contains "Choosing the tech stack,image:/_astro/cover.webp". The entire string after title: is treated as the title value, including the comma and everything after it.

The correct approach is a separate element per field:

<span data-pagefind-meta="title" class="visually-hidden">Choosing the tech stack</span>
<img data-pagefind-meta="image[src]" src="/search-thumbnails/choosing-the-tech-stack/choosing-the-tech-stack-thumbnail.webp"
     class="visually-hidden" alt="" aria-hidden="true" />

The image[src] syntax tells Pagefind to read the value from the src attribute rather than the text content of the element.

Why visually-hidden and not display:none

The first instinct is to hide these elements with display: none. It seems clean: they're purely for Pagefind's benefit, not for the user.

Pagefind's crawler skips elements with display: none. The meta is never read, and the fields come back undefined in results.

The .visually-hidden pattern keeps the element in the layout engine: it's positioned, sized, and rendered, but visually invisible and excluded from the accessibility tree:

.visually-hidden {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

Pagefind's crawler reads it. Screen readers ignore it via aria-hidden="true". Users don't see it.

The thumbnail problem

Cover images on this blog go through Astro's image optimisation pipeline, which hashes filenames at build time: cover.webp becomes cover.D7kJPmN_Z3QwX.webp. That hashed path is what Pagefind indexes.

In development, the Astro dev server generates images on demand and serves them at the original relative path, so the hashed path from the build doesn't exist. Pagefind reads the right path from the built HTML, stores it in the index, and it works in production, but the images 404 in dev.

The fix: pre-generate thumbnails as stable, predictably-named files that are served from the same path in both dev and production.

Generating thumbnails with ImageMagick

Each post directory in the content repo gets a <slug>-thumbnail.webp, a 96×96 center-cropped version of the cover image, generated once using ImageMagick:

magick cover.jpg -resize 96x96^ -gravity Center -extent 96x96 choosing-the-tech-stack-thumbnail.webp

The 96x96^ flag resizes to fill the target dimensions (scaling up the smaller dimension), and -gravity Center -extent 96x96 crops to the exact size, keeping the centre of the image.

These thumbnails live alongside the article: colocated in the content repo, committed once, never regenerated unless the cover changes.

Copying thumbnails before build and dev

The thumbnails live in collections/posts/<slug>/<slug>-thumbnail.webp. Astro serves from public/ (in dev) and dist/ (after build), not from collections/. The thumbnails:copy package command mirrors them to public/search-thumbnails/<slug>/<slug>-thumbnail.webp:

"thumbnails:copy": "node scripts/sync-public-assets.mjs thumbnails"

Both pnpm dev and pnpm search:index run pnpm thumbnails:copy first, and pnpm search:index also runs pnpm post-images:copy, so generated assets are always in place before the server starts or the search index is built. The Netlify build command also includes the asset sync step.

The layout then constructs the stable URL directly, no Astro getImage() involved:

const thumbSrc = frontmatter.cover?.thumbnail
  ? `/search-thumbnails/${postId}/${postId}-thumbnail.webp`
  : null;

/search-thumbnails/choosing-the-tech-stack/choosing-the-tech-stack-thumbnail.webp is the same URL in dev and production. The image is always there. No hashing, no broken thumbnails.

Styles must go in global.scss

Astro's scoped <style> blocks add a hash to every class name at build time, something like .search-panel[data-astro-cid-abc123]. Elements injected into the DOM at runtime via innerHTML don't have that hash attribute, so the scoped styles don't apply to them.

Everything that styles the search modal and results lives in global.scss, not in a scoped <style> block in Header.astro.

Design decisions

No search page

A dedicated /search route is the obvious implementation, but it has a friction cost: you leave your current context, wait for a page load, and then navigate back. The modal pattern keeps you where you are. Open, type, go: three steps, no navigation until you've found what you want.

The command-palette pattern is familiar from editors like VS Code's ⌘K and Spotlight. Users already know how it works.

The JS API over the default UI

Pagefind ships a ready-made UI component. It renders its own DOM, injects its own styles, and supports themes. For a blog that already has a design system and a specific interaction pattern in mind, the default UI introduces more constraints than it removes.

The JS API takes three lines to get search results and returns plain data: URL, excerpt, custom meta. The result DOM is written by the same code that writes the rest of the site. No style conflicts, no theme mismatch, no overriding someone else's HTML structure.

Dynamic import, not a static import

You can't statically import pagefind.js because the file doesn't exist at build time. Pagefind generates it after astro build runs. A static import would fail at the Vite bundling step. The runtime dynamic import await import('/pagefind/pagefind.js') sidesteps Vite entirely and loads only when the user first opens the search modal.

The is:inline attribute on the script tag is what keeps Astro from handing it to Vite.

Loading skeleton before results arrive

Pagefind's WASM module takes a moment to load on first use. A blank results area during that gap looks broken. Three skeleton rows, placeholder blocks with a shimmer animation, fill the space immediately, giving the user feedback that something is happening. The skeletons are replaced by real results as soon as the search resolves.

Predictable thumbnail paths

Astro's image optimisation pipeline hashes filenames: cover.webp becomes cover.D7kJPmN.webp. That hash changes every time the image is reprocessed. Pagefind stores whatever URL it finds at index time, which means indexed paths would become stale whenever the build produces a new hash.

Pre-generating thumbnails with a stable, slug-based filename (choosing-the-tech-stack-thumbnail.webp) breaks that dependency. The URL Pagefind indexes is the same URL that will exist in the next build and every build after that.

`visually-hidden`, not `display: none`

This is documented in detail in the metadata section above, but the principle is worth making explicit: anything you hide from the DOM with display: none is also hidden from Pagefind's crawler. .visually-hidden is the only pattern that satisfies all three constraints simultaneously: visually absent, accessible-tree absent, and crawler-visible.

Adding a new post

When you write a new post with a cover image, generate the thumbnail once:

magick path/to/cover.jpg -resize 96x96^ -gravity Center -extent 96x96 collections/posts/your-post-slug/your-post-slug-thumbnail.webp

Then add thumbnail: './your-post-slug-thumbnail.webp' as a child of cover: in the post frontmatter. The copy script and index rebuild will pick it up automatically.

Working on something similar?

If you're building a content site or developer blog and would rather not unpick these problems yourself, I'm available for consulting. Get in touch via the contact page.

Moving blog content to a private repository

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

Original post: Moving blog content to a private repository

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

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

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

The constraint

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

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

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

Why not a git submodule

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

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

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

The build-time clone approach

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

The entire change is in netlify.toml:

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

Three commands chained together:

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

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

Setting up the GitHub token

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

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

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

The .gitignore entry

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

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

Local development

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

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

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

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

VS Code workspace setup

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

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

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

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

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

Triggering deploys from the content repository

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

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

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

name: Deploy site

on:
  push:
    branches: [main]

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

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

What this gives you

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

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

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

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

Gating the preview branch behind a passcode

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

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

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

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

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

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

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

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

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

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

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

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

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

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

A few things worth calling out:

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

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

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

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

To wire it up:

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

   pnpm add -D @netlify/edge-functions

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

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

Purging content from the existing git history

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

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

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

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

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

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

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

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

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

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

What to watch for

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

The fix is a negation pattern in the glob loader:

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

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

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

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

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

Working on something similar?

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

Web analytics on a static Astro blog

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

Original post: Web analytics on a static Astro blog

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

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

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

Picking a tool

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

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

I went with PostHog for a few reasons:

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

The implementation

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

Production-only loading

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

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

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

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

Why an external file instead of `define:vars`

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

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

const currentScript = document.currentScript;

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

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

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

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

Environment variables

Two environment variables are required:

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

Getting the key

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

Local development

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

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

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

GitHub Actions

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

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

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

What you get out of the box

Once deployed, PostHog automatically captures:

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

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

A note on cookie consent

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

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

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

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

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

A custom 404 page

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

Original post: A custom 404 page

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

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

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

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

Click the expand icon to view it fullscreen.

How Astro handles 404s

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

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

Skipping the standard layout

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

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

The hero panel

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

.not-found__panel {
  display: grid;
  gap: 1.5rem;
  align-items: center;
  background:
    radial-gradient(
      circle at top right,
      color-mix(in srgb, var(--accent-secondary) 14%, transparent) 0%,
      transparent 34%
    ),
    linear-gradient(
      150deg,
      color-mix(in srgb, var(--accent-primary) 4%, var(--surface-elevated)) 0%,
      var(--surface-elevated) 62%
    ),
    var(--surface-elevated);

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

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

The number

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

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

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

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

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

The copy and the primary actions

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

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

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

Try these instead: guides and core pages

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

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

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

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

Accessibility notes

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

Full code listing

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

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

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

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

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

  .not-found__panel {
    display: grid;
    gap: 1.5rem;
    align-items: center;
    margin-bottom: 3rem;
    background:
      radial-gradient(
        circle at top right,
        color-mix(in srgb, var(--accent-secondary) 14%, transparent) 0%,
        transparent 34%
      ),
      linear-gradient(
        150deg,
        color-mix(in srgb, var(--accent-primary) 4%, var(--surface-elevated)) 0%,
        var(--surface-elevated) 62%
      ),
      var(--surface-elevated);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

What Netlify does with it

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

Paginating a Blog in Astro

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

Original post: Paginating a Blog in Astro

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

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

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

The URL structure

The target structure:

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

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

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

Why not `paginate()`?

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

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

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

Two route files instead of one

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

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

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

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

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

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

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

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

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

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

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

A shared BlogGrid component

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

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

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

Placeholder cards for a half-full grid

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

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

Click the expand icon to view it fullscreen.

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

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

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

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

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

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

Pagination controls

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

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

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

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

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

What this produces

At build time, Astro generates:

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

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

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

Full code listing

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Improving code blocks in Astro

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

Original post: Improving code blocks in Astro

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

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

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

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

Setup

Install the integration and the optional line numbers plugin:

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

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

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

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

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

Themes

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

Frames

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

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

Editor frames

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

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

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

title attribute — the tab label is set directly:

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

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

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

Terminal frames

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

pnpm build

echo "No title — still a terminal frame"

Overriding frame type

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

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

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

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

echo "No frame at all"

Line numbers

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

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

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

showLineNumbers=false — line numbers hidden:

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

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

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

Word wrap

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

Both can be overridden per block:

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

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

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

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

wrap=false — long line causes a horizontal scrollbar:

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

Line markers

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

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

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

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

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

import { defineConfig } from 'astro/config';

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

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

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

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

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

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

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

import { defineConfig } from 'astro/config';

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

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

Using diff syntax

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

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

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

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

Text markers

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

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

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

import expressiveCode from 'astro-expressive-code';

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

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

The full picture

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

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

Running Local AI Models on macOS

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

Original post: Running Local AI Models on macOS

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

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

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

How it fits together

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

Prerequisites

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

Install Ollama

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

brew install --cask ollama

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

curl http://localhost:11434

The response should be Ollama is running.

Memory and performance settings

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

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

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

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

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

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

# Default context window
export OLLAMA_CONTEXT_LENGTH=4096

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

Then apply them without restarting your shell:

source ~/.zshrc

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

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

Adjusting for more RAM

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

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

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

Staying fully local

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

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

Choosing a model

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

Model reference

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

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

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

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

Pulling and running a model

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

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

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

A good starting set for most daily-use scenarios:

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

VS Code Copilot integration

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

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

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

Create capped model variants

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

FROM qwen3:8b
PARAMETER num_ctx 4096
PARAMETER temperature 0.7

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

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

The following creates all four variants in one pass:

mkdir -p ~/ollama-models

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

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

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

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

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

Connect to Ollama and select a model

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

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

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

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

ollama ps

Copilot CLI

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

brew install copilot-cli

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

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

ollama launch copilot

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

ollama launch copilot --model qwen3:8b

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

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

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

Wrapping up

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

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

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

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

GitHub Copilot for Engineers: Getting Better Results

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

Original post: GitHub Copilot for Engineers: Getting Better Results

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

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

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

Architecture overview

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

Before you start

Subscription and VS Code extension

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

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

code --install-extension GitHub.copilot

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

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

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

Copilot CLI

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

Install via Homebrew:

brew install copilot-cli

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

pnpm add -g @github/copilot

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

# Start an interactive session
copilot

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

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

awesome-copilot

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

Choose models by task

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

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

A practical pattern:

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

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

Layer global and project settings

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

Global settings

Global Copilot configuration lives under your home directory:

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

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

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

Project-level settings

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

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

Instructions, agents, and skills

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

Instructions: always-on policy

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

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

Minimal template:

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

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

Agents: task-specific operators

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

An agent definition includes:

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

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

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

Skills: reusable playbooks

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

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

The rule of thumb:

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

MCP servers

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

Three common patterns:

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

Installing common servers

Playwright MCP: browser automation and visual QA:

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

Azure MCP Server: Azure resource inspection and management:

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

Example config

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

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

When to reach for MCP

Follow this order:

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

Security checklist

Before adding any MCP server:

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

Rolling it out

Individual setup

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

Team rollout

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

Keeping it improving

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

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

Quick audit checklist

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

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

Wrap up

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

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

Adding comments to a static Astro blog with Netlify Forms

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

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

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

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

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

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

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

The approach

The system runs in four steps:

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

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

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

The form

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

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

A few things worth noting here:

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

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

The functions

There are three Netlify Functions in total.

get-comments

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

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

import crypto from "node:crypto";

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

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

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

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

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

comment-handler

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

import crypto from "node:crypto";

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

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

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

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

approve-comment

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

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

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

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

Rendering comments

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

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

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

No raw user content ever reaches the HTML parser.

Gravatar avatars

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

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

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

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

Styling dynamically injected content in Astro

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

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

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

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

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

Registering the approved-comments form

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

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

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

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

Setting it up on Netlify

After the first deploy:

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

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

Refreshing the list after submission

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

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

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

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

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

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

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

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

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

What I'd do differently

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

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

Wrap-up

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

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

DEV Community: Roger Rajaratnam

Adding reading times to an Astro blog

The package

Where reading times appear

Blog cards

Post pages

Automating Dev.to cross-posting from an Astro blog

How cross-posting and canonical URLs work

Architecture

Setting up

Running it

How frontmatter is parsed

Making image URLs absolute

Converting mermaid diagrams to images

Converting SVG wireframes to PNG

Normalising series callouts and adding the original-post link

Updating an already cross-posted article

What to check after publishing

Full code listing

!/usr/bin/env node

Adding emoji reactions to your Astro blog with Netlify Blobs

Architecture overview

Setting up Netlify Blobs

The serverless function

The Astro component

Preventing duplicate votes

Optimistic updates

The pop animation

Placement: hero and page menu, not a standalone block

What the counts look like when empty

Local development

Full code listing

Adding search to a static Astro blog

Architecture overview

The modal UI

How Pagefind works

Indexing locally for dev

Marking content for indexing

A modal, not a search page

Pagefind's JS API

Metadata: title and cover image

Why visually-hidden and not display:none

The thumbnail problem

Generating thumbnails with ImageMagick

Copying thumbnails before build and dev

Styles must go in global.scss

Design decisions

No search page

The JS API over the default UI

Dynamic import, not a static import

Loading skeleton before results arrive

Predictable thumbnail paths

visually-hidden, not display: none

Adding a new post

Working on something similar?

Moving blog content to a private repository

The constraint

Why not a git submodule

The build-time clone approach

Setting up the GitHub token

The .gitignore entry

Local development

VS Code workspace setup

Triggering deploys from the content repository

What this gives you

Gating the preview branch behind a passcode

Purging content from the existing git history

What to watch for

Working on something similar?

Web analytics on a static Astro blog

Picking a tool

The implementation

Production-only loading

Why an external file instead of define:vars

Environment variables

Getting the key

Local development

GitHub Actions

What you get out of the box

A note on cookie consent

`visually-hidden`, not `display: none`

Why an external file instead of `define:vars`

Why not `paginate()`?