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.
content/posts/npm run build and writes dist/dist/ goes to any static hostShort 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.
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.
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.
userHelper is near users; formatUserName is a thing.// 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.
]]>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.
An entry written the day of the change takes a minute. The same entry reconstructed a month later takes an hour and is worse.
]]>For notes, documentation and most marketing pages, that trade is not close.
]]>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.
| Need | Markdown |
|---|---|
| A heading | ## Title |
| Emphasis | *this* |
| A link | [text](url) |
| Code | backticks |
Tables, footnotes and task lists are extensions; use them when the renderer supports them and the text still reads without them.
]]>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.
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.
]]>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.
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.
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.
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.
]]>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.
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.
]]>cp.
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.
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.
llms.txt is a plain-text file at the root of a site: a title, a line about the site, and a list of links to markdown versions of its pages.
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.
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.