The Goal

I play a lot of ASCII and text-based games, and one of my favorite details in Caves of Qud is how it colors certain words: an item name in a gradient, a faction in its own color. It makes a wall of text easy to scan. I wanted the same thing here, with a few constraints:

• Professional, not zany. It’s a site people look at when deciding whether to hire me.
• Readable for everyone. Every color has to pass WCAG AAA contrast on the dark background, and screen readers have to read the words normally.
• No inline styles. The site has a strict Content-Security-Policy (style-src 'self'), so every color has to come from a class in a stylesheet.

Version 1: Automatic Keyword Matching

The first design was a keyword table in a data file, applied automatically at build time. Add “fuzzing” to the table, and every page that mentions fuzzing gets it colored. That’s retroactive and zero effort per post, which sounded great.

The hard part was that Hugo only gives you the rendered HTML, and I had to color text without ever touching markup. A keyword inside a link, a code block, a heading or an href attribute must stay alone. Go’s regex engine has no lookbehind, so you can’t just write “match this word unless it’s inside <code>.” I ended up splitting each page into tokens (tags vs. plain text), tracking which protected element I was inside, and only running replacements on plain text:

{{- range findRE `<!--[\s\S]*?-->|<[^>]*>|[^<]+` $html -}}
  {{- if hasPrefix . "<" -}}  {{/* a tag: update which protected element we're in */}}
  {{- else if eq $protTag "" -}}  {{/* plain text outside code/links/headings: safe to edit */}}

Matches got swapped for private-use placeholder characters first, so a short keyword couldn’t match inside a longer one that was already colored. Then there were the small surprises: Hugo’s typographer turns ' into ’, so “Let’s Encrypt” never matched, and & becomes &.

The gradients had their own constraint. Coloring each letter separately means one <span> per letter, and current testing shows that screen readers handle per-letter spans badly (spelling words out, or reading only the first letter). So every gradient is a single element with background-clip: text, which paints the gradient inside the glyphs and leaves the text alone.

It worked, but it colored words, not ideas. Pages about topics on the list got crowded, and pages about anything else got nothing.

Version 2: Per-Page Picks

The fix seemed obvious: let each page pick its own terms in front matter, with the shared table kept as a library so “fuzzing” is the same color everywhere. I added build checks too: the build fails on a typo’d term and warns when a picked term never gets colored.

Then the library grew to about 110 terms, including tools and languages in their brand colors (Python’s blue and yellow, Rust’s copper, Claude’s terracotta). A lot of brand colors are too dark for a near-black page, so a script lightened each one in OKLCH until it passed 7:1. Raising only the lightness keeps the hue and saturation, so reds stay red instead of fading to pink.

Two problems showed up once real posts used it:

1. Too many gradients. When everything shimmers, nothing stands out. I cut them to about 20% of styles and made the rest solid colors.
2. First mentions cluster. An intro paragraph previews the whole post, so it holds the first mention of half the picked terms and lights up like a Christmas tree.

I also shipped a bug here worth admitting: a Hugo pipe passes its value as the last argument, I wrote it as if it were the first, and every match on the site silently disappeared. A coverage report I’d written for checking density caught it before anything went live.

Version 3: Just Mark the Point

Eventually I realized I was solving the wrong problem. A machine can match terms reliably, but it can’t tell which phrase in a paragraph is the point, and that’s what I actually wanted readers to catch. So I deleted the matcher, the library and the front matter picks, and replaced all of it with an inline marker you place by hand:

The {=flow: upload step=} {=glitch: skips anything starting with a dot=} by default.
If the build fails, {=point: the live site stays on the last good version=}.

There are two tiers. Colored accents mark the tool, company or idea a paragraph is about, picked from a palette where every style has a short note on when to use it. A key-point style (bright italics, no color) marks the one takeaway of a section, at most once per section. The guideline is about one accent per paragraph, on the phrase that carries the idea.

The syntax took a couple of tries. My first version reused link syntax, [phrase](=style), with a render hook, which worked great on the site and looked like broken links on GitHub. Double brackets ([[style: phrase]]) never fired, because Markdown’s link parser claims [ first. What worked was Hugo’s passthrough extension, which hands anything between custom delimiters to a render hook untouched:

[markup.goldmark.extensions.passthrough]
  enable = true
  [markup.goldmark.extensions.passthrough.delimiters]
    inline = [['{=', '=}']]

I skipped :: and << as delimiters because they show up in normal writing about code (std::vector, heredocs). The render hook splits off the style name, fails the build on an unknown style, and runs the inner text back through Markdown so bold and code inside an accent still work. After converting, I diffed every rendered accent and link against a saved baseline, and the output was byte-for-byte identical.

What I’d Take From It

I think the main lesson is to automate what’s actually mechanical and leave judgment to people. Contrast checks, style validation and “is this markup well-formed” are perfect for the build to enforce. Picking what matters in a paragraph isn’t, and version 1 and 2 were me spending a lot of clever code avoiding that.

The final system is a palette file, a CSS template that generates one class per style, and two small render hooks. That’s less template code than the first version’s matcher alone, and it does the job better. I built it with Claude Code doing a lot of the implementation and testing, which made it cheap to try (and throw away) the first two versions lol.

The Setup In One Picture

The whole thing is pretty simple once you see the flow:

1. I write Markdown and push to main.
2. A GitHub Actions workflow installs Hugo, builds the site, and uploads the result.
3. GitHub Pages serves it, and my domain points at GitHub Pages.

There’s no server for me to patch, no database, and no hosting bill. For a personal site I think that’s the right amount of infrastructure: the attack surface is basically a folder of HTML files.

Why Hugo, And Why PaperMod

I went with Hugo because it’s a single binary, it builds fast (this site currently builds in under 100 ms locally), and the output is plain static files. No Node toolchain to keep updated, which I was honestly happy to skip.

For the theme, the first plan an LLM helped me brainstorm was actually Blowfish. It looks great, but when I compared them, PaperMod won for a couple of practical reasons:

• Readability. PaperMod’s article page is 18px text in a single ~720px column, with a lot less visual chrome. People who read writeups are the main audience, so the article page is what has to be good.
• Build compatibility. Blowfish needs Hugo’s extended edition and capped its supported version below what the official GitHub Pages workflow installs. PaperMod just works with standard Hugo.

The theme is pulled in as a Git submodule, so the repo only stores a pointer to one specific commit of PaperMod instead of a copy of its files:

git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

Updating it is a deliberate step (git submodule update --remote, check locally, commit), so a theme change never lands on the live site by surprise. I also never edit the theme’s files. Every customization lives in my own layouts/ and assets/ folders, which Hugo uses in place of the theme’s versions.

Build And Deploy With GitHub Actions

The workflow is Hugo’s official GitHub Pages workflow, with two small changes. I pulled it from Hugo’s docs repo directly and diffed my copy against it, so I know exactly what’s different:

env:
  HUGO_VERSION: 0.169.0
  TZ: America/Chicago             # change 1: my time zone, for dates Hugo prints
# ...
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v5
        with:
          include-hidden-files: true   # change 2: publish /.well-known/security.txt
          path: ./public

The second one was a fun one to find. The upload step skips anything starting with a dot by default, which is a sensible default, but it means /.well-known/ never gets published. More on why I wanted that folder below.

A few things I like about this setup:

• The build job only gets contents: read, pages: write and id-token: write. It can’t push to the repo.
• If the build fails, nothing deploys, so the live site stays on the last good version.
• The base URL comes from the repo’s Pages settings at build time, so the same workflow worked at erikfailing.github.io first and then at erikfailing.com with zero changes.

Pointing The Domain At It

My domain is registered through Squarespace, so this was mostly clicking through their DNS panel in the right order:

1. Verify the domain with GitHub first. GitHub gives you a TXT record (_github-pages-challenge-<username>), and once it’s verified, only my account can publish a Pages site on that domain. This prevents domain takeover if the repo ever gets deleted or Pages gets turned off while DNS still points at GitHub.
2. Delete Squarespace’s default records (their parking page A records and www CNAME).
3. Add GitHub’s records: four A records and four AAAA records for the apex, plus a CNAME for www pointing to erikfailing.github.io.
4. Set the custom domain in the repo and turn on Enforce HTTPS once GitHub finished issuing the certificate.

No wildcard records, since a wildcard is an easy way to end up with a subdomain someone else can claim.

A Few Security-Flavored Touches

It’s a personal site, so I didn’t go overboard, but there were a few things I wanted as a security engineer:

• security.txt. There’s an RFC 9116 file at /.well-known/security.txt that points to the repo’s private vulnerability reporting, plus a short SECURITY.md policy. It has an Expires field, so it’s a once-a-year chore to bump the date.
• No third-party requests for fonts. I self-host the font instead of loading it from Google Fonts, so loading a page doesn’t send visitors’ IPs anywhere else.
• robots.txt that blocks AI training but not AI search. It turns out the big AI companies use separate crawler names for training and for search (e.g. GPTBot vs OAI-SearchBot, ClaudeBot vs Claude-SearchBot). So I asked the training crawlers to stay out while still letting search engines and AI search assistants read and cite the site:

User-agent: GPTBot
User-agent: ClaudeBot
User-agent: Google-Extended
User-agent: Applebot-Extended
User-agent: Meta-ExternalAgent
User-agent: CCBot
User-agent: Bytespider
Disallow: /

(robots.txt is a request, not access control, but the reputable crawlers do honor it.)

Update (October 31, 2026): I took these rules back out. They only stop crawlers polite enough to ask, so they weren’t keeping out anyone I’d actually worry about, and I’d rather AI assistants know who I am when someone asks about me. The site also has an llms.txt now, a plain-text list of its pages for AI tools.

A Font Flicker I Had To Fix

Open Sans is my favorite font, so the whole site uses it, self-hosted as one variable font file. The first version had an annoying bug though: clicking between pages, the text would visibly shift. It turned out to be a font swap on every page load. The browser only discovered the font after parsing the CSS, and font-display: swap told it to draw the text in the system font first (Segoe UI on Windows) and then redraw it in Open Sans. The two fonts have different widths, so everything jumped. The fix was preloading the font:

<link rel="preload" href="/fonts/open-sans-latin-wght-normal.woff2" as="font" type="font/woff2" crossorigin>

plus switching to font-display: block, so the browser waits the few milliseconds for the preloaded font instead of painting a stand-in.

The colors got a similar amount of care: every text color passes WCAG AAA contrast against the background, and links stay underlined since my link blue is too close in brightness to the body text for color alone to mark them.

How I Used AI On This

I used Claude Code (an LLM coding assistant) a lot on this project, and I think it was genuinely useful, but as an assistant, not as the one in charge. It drafted config, looked up docs, ran test builds, and did research I’d otherwise do by hand (like verifying every crawler name against each company’s docs). I still made the decisions and read every change before it went in.

And reading everything mattered. A few examples:

• On the very first step, the submodule command it wrote had the wrong GitHub username for PaperMod’s author. That would have pulled a theme from a repo that wasn’t the real one, which is a supply-chain mistake in a single typo. It got blocked before running, and the correct URL went in instead, but it’s exactly the kind of thing you only catch by actually reading the command.
• The font flicker above was something I noticed clicking around the site myself. The first font setup it gave me “worked,” it just wasn’t right.

So overall, I think it saved me a lot of time on the tedious parts (looking up DNS records, reading theme source to find the right CSS selectors, etc…), and it left me more time for the parts I actually care about. But anything it hands me still gets read before it ships.

What’s Next

No big roadmap. I’ll update the site as I feel like it, mostly with security projects and writeups, plus some software dev stuff here and there.