These docs are based on gwern.net commit 4d6661114 (2026-07-02); all pages were audited against that commit's source in 2026-07.
gwern.net Codebase Documentation
This is an unofficial map of the gwern.net codebase: how Markdown essays move through the Hakyll/Pandoc build, how link metadata becomes annotations, and how the frontend turns static HTML into interactive pages.
Quick Start
| If you want to... | Start here |
|---|---|
| Get the system model | Architecture at a Glance |
| Follow one page from source to browser | Page Lifecycle |
| Find the file responsible for a feature | Functional Taxonomy |
If you are new to the codebase, read the architecture overview first, then use page lifecycle for the end-to-end flow and functional taxonomy as the map of individual files.
Guided Topics
These are shorter paths through the larger reference when you already know what subsystem you care about.
| Topic | Start here | Covers |
|---|---|---|
| Build pipeline | Build Pipeline | Hakyll, Pandoc, generated content, validation, and deployment |
| Annotation metadata | Annotation and Metadata | GTX records, metadata scrapers, annotation fragments, and frontend loading |
| Popup system | Popup System | Hover previews, mobile popovers, Extracts dispatch, transclusion, and annotation display |
What is gwern.net?
gwern.net is a long-form essay site by pseudonymous writer Gwern Branwen, with frontend work by Said Achmiz. It is known for long, heavily cited essays and for a site design that treats the web page as an extended reading environment rather than a simple document.
The codebase is interesting because many of the reading features are custom infrastructure: hover popups for citations and local pages, inline transclusion, margin sidenotes, generated bibliographies, annotation databases, and link archiving.
The backend is built around Hakyll and Pandoc, with Haskell modules handling metadata, transforms, validation, generated pages, and deployment support. The frontend is vanilla JavaScript built around an event system that coordinates popups, transclusion, theming, layout, and other runtime behavior.
Why This Exists
Gwern has written about the site's design in About This Website, Design Graveyard, and Typography. This reference is meant to complement those essays by organizing the source code itself: what the major modules do, where features enter the pipeline, and how the build-time and runtime systems fit together.
Use it as a companion while reading the upstream source, or as a routing layer when asking an agent to inspect a subsystem. These docs are source-derived but unofficial; the codebase changes often, and the source remains the authority.
How These Docs Were Created
To create the docs, I first built a rudimentary map with notes I wrote while reading the codebase. I then fed this map to multiple Claude Opus 4.5 agents, with each cohort documenting a different part of the codebase. I manually reviewed the output and did a secondary fact-checking step with GPT 5.2 and Claude again.
Every now and then I find a new mistake or a not-quite-accurate description. These docs are by no means authoritative, comprehensive, or fully correct. If you find any problems or inaccuracies, feel free to contact me and I'll correct them as soon as possible.
Documentation Structure
The overview section has three layers: Architecture at a Glance for the system model, Page Lifecycle for the chronological flow, and Functional Taxonomy for the full file map with importance scores.
| Category | Description |
|---|---|
| Overview | High-level architecture, page lifecycle, and functional taxonomy |
| Build Pipeline | Core build scripts (sync.sh, hakyll.hs, bash.sh) |
| Annotation & Metadata | Link metadata system, scrapers, and processing |
| Popup System | Popups, popovers, and extract handling |
| Link Processing | Archives, icons, auto-linking, and interwiki |
| Content Rendering | Core JS framework, transclusion, and DOM rewriting |
| Typography & Layout | Text transforms, sidenotes, columns, and images |
| Theming & UI | Dark mode, reader mode, colors, and CSS |
| Backend Utilities | Haskell helper modules |
| Frontend Utilities | JavaScript helper modules |
| Tags & Navigation | Tag management and directory generation |
| Content Features | Blog, X-of-the-day |
| PHP Asset Pipeline | CSS/JS bundling and asset generation |
| Python Utilities | LLM-based text processing tools |
| Shell Utilities | Embedding, archiving, uploading scripts |
| HTML Templates | Hakyll/Pandoc templates |
| Server & Nginx | Server configuration |
Quick Links
| If you want to... | Start here |
|---|---|
| Understand the JS architecture | initial.js |
| Understand popups | popups.js |
| Understand annotations | LinkMetadata.hs |
| Understand the build | sync.sh |