Building and deploying a blog website

A blog is read far more often than it changes. So every page here is built once, ahead of time, and sent as a finished HTML file.

The tools

Each tool does one job, and most of them only run during the build.

How it works

1. WriteAn HTML post
2. BuildPages and bundles
3. DeployFiles go to Vercel
4. ReadThe CDN serves them

Adding a post

A post is one HTML file. The top block is metadata, and the rest is the article.

---
title: Hello world
date: 2026-11-02
---
<p>The article starts here.</p>

The file name becomes the URL, so this one lives at /posts/hello/. The build then does the rest:

What is SVG?

A PNG stores pixels and blurs when enlarged. An SVG stores drawing instructions, so it stays sharp at any size.

<svg viewBox="0 0 32 32">
  <rect x="2" y="2" width="28" height="28" rx="8"
        fill="#070b14" stroke="#f2b544" stroke-width="2"/>
  <text x="16" y="22" fill="#f2b544" font-size="17"
        text-anchor="middle">R</text>
</svg>

The viewBox sets a 32 by 32 grid, and each shape sits on that grid. An SVG can be written by hand, exported from a tool like Figma, or taken from an icon set.

Dark and light mode

The switch changes one attribute on the page, and CSS does the rest.

1. Colours are variablesEach one is defined twice, and everything else uses the name.
   tokens.css

   :root { --bg: #070b14; }
   :root[data-theme="light"] { --bg: #faf7f0; }
   body { background: var(--bg); }

2. The button flips the themeIt changes the attribute and saves the choice.
   theme.ts

   const next = root.dataset.theme === "light" ? "dark" : "light";
   root.dataset.theme = next;
   localStorage.setItem("theme", next);

3. No flash on loadA tiny script in the <head> runs before anything is drawn.
   head

   const saved = localStorage.getItem("theme");
   if (saved) document.documentElement.dataset.theme = saved;

Keeping secrets out

A token pushed to GitHub has to be treated as leaked, so gitleaks scans for them first. It looks for known formats, like ghp_, and for values that look random.

1. CommitThe hook starts
2. ScanStaged changes are read
3. BlockA secret stops the commit
4. PushCI scans it all again

pre-commit:
  commands:
    gitleaks:
      run: gitleaks git --pre-commit --staged --redact --no-banner

Hosting on Vercel

Vercel only needs to know how to build the site and where the finished files go.

Connecting the domain

Think of DNS as a phone book. Cloudflare holds the book, Vercel hosts the site, and one entry joins them.

1. In Vercel, add the domainOpen Settings, then Domains, and add blog.example.com. Vercel shows a value. Copy it.
2. In Cloudflare, add the recordOpen DNS, then Records, and add this:
   TypeCNAME

   Nameblog

   TargetThe copied value

   ProxyDNS only
3. Back in Vercel, wait for the tickVercel checks the record and adds HTTPS by itself.