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
| Layer | Tool | Notes |
|---|---|---|
| Server | net/http | stdlib mux, longest-prefix routing |
| Templates | a-h/templ | typed, compiled to Go |
| Content | internal/content/norg | my own parser, about 1,000 lines in five files |
| Code blocks | Chroma | highlighting at parse time |
| Styles | Tailwind v3.4.17 | standalone binary, pinned by SHA-256, plus handwritten CSS |
| Logs | zerolog | JSON in production |
| Deploy | Docker on Railway | distroless 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
blogandprojectsfilters - 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
.norgfile 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.