Overview

This engine runs this site. I write posts and project notes as .norg files, the app parses them at startup, and every request reads from memory. You get one binary, no database, and no JavaScript framework.

Why build one

Off-the-shelf tools gave me two of these three at best:

  • Neorg as the source format, with no Markdown step
  • a single deployable binary
  • projects as folders, each holding its own devlogs

Stack

LayerToolNotes
Servernet/httpstdlib mux, longest-prefix routing
Templatesa-h/templtyped, compiled to Go
Contentinternal/content/norgmy own parser, about 1,000 lines in five files
Code blocksChromahighlighting at parse time
StylesTailwind v3.4.17standalone binary, pinned by SHA-256, plus handwritten CSS
LogszerologJSON in production
DeployDocker on Railwaydistroless image, also published to GHCR

What works

  • folder-based project loader with draft and duplicate-slug checks
  • nested routes for project devlogs
  • flat devlog list on each project page

The Blog and Projects indexes, with an outlined year above each group and one line per title, come from Anthony Fu's site. The devlog list below uses the same rows, with the year in each date.

  • search with blog and projects filters
  • RSS and sitemap entries for posts, projects, and devlogs
  • link validation, request limits, and pinned build inputs
  • parser split into its own package
  • coffee menu front page with a brand view transition
  • phrase matching in search
  • stemming so rebuild finds rebuilt
  • comments through a third-party widget

Terms

index.norg
the required entry file in each project folder; it holds the project metadata.
devlog
any other .norg file in a project folder, listed below the project with its date and reading time.

The whole engine is about 2,400 lines of Go and 2,200 lines of tests. The devlogs below cover how it got here.