How it is built

Every post is a markdown file with a little YAML front matter at the top. The build reads the files, renders them once to HTML, and writes one static page per post — no server, no database, nothing to keep running.

• Posts live in content/posts/
• The build runs npm run build and writes dist/
• dist/ goes to any static host

What to expect

Short notes, mostly. A longer piece now and then. Every post is also available as raw markdown at the same path with a .md extension, and there is an RSS feed if you would rather read from a feed reader.

Lower the bar on purpose

Write badly, on purpose, and quickly. Leave placeholders like [example here] instead of stopping to find the example. Keep a list of questions at the bottom of the file instead of answering them inline.

Separate the two modes

Drafting and editing use different parts of the mind. Mixing them means doing both slowly. Draft in one sitting; edit tomorrow.

The draft is for you. The edit is for the reader.

Three tests

1. Could it mean something else? If a name fits two things, it describes neither.
2. Does it say what the thing is, not what it is near? userHelper is near users; formatUserName is a thing.
3. Would a stranger place it? Read the name out of context. If it needs the folder to make sense, it is not finished.

// before
      const data = await get(id)
      // after
      const invoice = await fetchInvoice(id)
      

Renaming is cheap early and expensive late — a published API name is forever.

One line per change, for strangers

Write each entry for someone who has never seen the code. Say what changed and why it matters, in their words. Internal narrative — which gate was wrong, what confused whom — does not belong there.

Keep it as you go

An entry written the day of the change takes a minute. The same entry reconstructed a month later takes an hour and is worse.

What you give up

• No per-request logic: personalisation happens in the browser or not at all.
• No database: content is files in the repository, edited like code.

What you get

• Nothing to patch, restart, scale or back up.
• Every page is cacheable forever and served from the edge.
• The build is the only moving part, and it runs on your machine or in CI where you can watch it.

For notes, documentation and most marketing pages, that trade is not close.

Structure you can see

Headings, lists, emphasis, links and code — that is the structure of almost every document worth reading, and markdown spells each one with a character you can type.

Everything else is a plugin

Tables, footnotes and task lists are extensions; use them when the renderer supports them and the text still reads without them.

Start at the entry point

Print the actual input where it enters the system. Not what the docs say it should be — what it is. Half the bugs end right there.

Then work inward

Follow the value one step at a time, printing as you go, until it stops being what you expect. That step is the bug. Everything before it was fine.

console.log('[handler] body =', JSON.stringify(req.body))
      

Delete the line afterwards. Keep the habit.

One logical change

If the message needs the word "and", it is two commits. A reviewer can hold one idea in their head; a reverter can remove one idea without collateral.

Commit before the risky step

About to run a script over two hundred files? Commit first. Recovering from a bad sweep is a one-line git revert — if the good state was committed.

Publish both

RSS 2.0 and Atom 1.0 are both a few hundred bytes of XML per post. Readers handle either, so publish both and let them choose. This site does: feed.xml and atom.xml.

Put the whole post in the feed

A feed that holds only the first paragraph trains readers to leave. Put the full text in; the reader who wants the page will click anyway.

Test the outcome, not the mechanism

A test that asserts a function was called passes when the function does the wrong thing. A test that asserts the result the user sees fails when it should.

Anchor to something visible

For user interfaces, at least one assertion per test should touch the screen — a heading, a button, a URL. A suite that only hits the API stays green while the page is blank.

Build

npm run build
      

The build type-checks, bundles the app, then prerenders every route to dist/<route>/index.html — in Node, with no browser involved — and writes the feeds, the sitemap and llms.txt next to them.

Copy

Upload dist/ to any static host. If the site lives under a sub-path, build with BASE_PATH=/notes and every link, asset and feed URL follows.

Why markdown

A language model reading HTML spends most of its attention on navigation, scripts and markup. The same page as markdown is a tenth of the size and all signal.

This site's copy

Every post here is served twice: as a page, and as the original markdown at /<slug>.md. llms.txt lists the markdown copies with a one-line description each.