~ / journal

Journal

Occasional notes about how this notebook is made and the small decisions that keep it pleasant to maintain.

Why a tiny custom publisher beat a full wiki engine

Keeping pages as plain text files in a version control repository has one enormous advantage: the work can be done with whatever editor is already open, and every change carries a message explaining itself. The web layer only needs to turn those files into pages and commit what was just typed.

For a while a larger wiki engine did the job. It was pleasant in theory and tiring in practice. The runtime was heavy on the machines at hand, and occasionally the editing view would quietly drop a chunk of a long code example. When a tool eats your work, you stop trusting it.

So the publishing side was rewritten as a thin layer: a small server side script reads the markdown files, hands them to a renderer, serves the result, and writes edits back through the same repository that was always there. No database, no daemon to babysit, no surprises with unusual characters in a code block.

The lesson was not that the big engine was bad. The lesson was that the problem was small enough to solve with a few hundred lines, and owning those lines made every later change cheap.

Notes on writing in the terminal

• Write in markdown, keep one idea per file, and let the file path carry the topic.
• Commit early. A commit is a bookmark you can return to when an edit goes sideways.
• Keep code examples literal. If a snippet needs escaping to survive, the renderer is the problem, not the snippet.
• Prefer plain text over a rich editor for anything that will be read by a script.

What changed in this rebuild

The notebook now ships as static pages with a single stylesheet and one small script. The reading surface is the same idea told with a calmer layout: a fixed index on the left, a wide page on the right, and code blocks that stay readable on a phone. Nothing here phones home, and nothing is loaded from a third party except the two typefaces.