Building this site

This site is a few dozen files. There's no CMS, no database, and no frontmatter parser. A post is a folder, and the folder's name is its address.

I wanted something closer to a notebook than a publishing platform: open a file, write, push. Everything else (the title above, the date, the list on the homepage) comes from one small registry so it can't drift out of sync.

How it's put together

Each post lives at app/(articles)/<slug>/page.mdx. The parentheses make (articles) a route group, so it shares a layout without appearing in the URL. This post is served at /building-this-site.

app/posts.json
{
  "posts": [
    { "slug": "building-this-site", "title": "Building this site", "date": "2026-11-19" }
  ]
}

The homepage reads that list. So does the article layout, which looks up the current route segment and renders the title and date. Adding a post means adding one line here and one folder there.1

Posts that do things

Because posts are MDX, they can import components. The counter below is an ordinary client component sitting in the same folder as this file.

page.mdx
import { postMetadata } from "@/lib/posts";
import { Counter } from "./counter";
 
export const metadata = postMetadata("building-this-site");
 
<Counter />
0

A live component, imported at the top of this very file.

Code is highlighted at build time with rehype-pretty-code, so the page ships as plain HTML with no highlighting script.

The small parts

Some words get a highlighter pass. Its gradients, padding and corner radii are seeded by the text itself, so ink pools at the ends the way a real marker does, and the same phrase always gets the same stroke. Others get a quick pen underline or a circle, drawn with rough-notation the first time they scroll into view.

Diagram of a narrow text column with a bracketed paragraph and a handwritten note in the right margin.
The column is about 34rem. Notes hang in the margin when there's room for one.

On a phone there's no margin, so notes drop below the paragraph they belong to and the bracket isn't drawn. With reduced motion turned on, everything appears already drawn.2

Typography over decoration. If an element doesn't earn its place, it goes.

PieceChoice
FrameworkNext.js App Router, MDX
Highlightingrehype-pretty-code, build time
Annotationsrough-notation, seeded CSS gradients
HandwritingCaveat (OFL), swappable

Footnotes

  1. If a post folder exists without a registry entry, the build fails loudly rather than shipping a page with no title. ↩

  2. The margin notes are real text in the DOM, read in order after the passage they annotate, so they work with screen readers and text selection. ↩