Why this way
This section covers nuckty's architectural decisions. Each page is a record of a choice: which alternatives were considered, why one of them won, and what had to be sacrificed.
The selection principle is simple: a record is needed when the decision is nontrivial and its rationale will be useful later. If the choice is obvious, it does not belong here.
Every record follows the same template: Decision → Context → Alternatives → Argument → Consequences.
Records
- The Markdown engine — remark/unified instead of markdown-it
- BEMJSON as the data model — a typed tree instead of string templates
- Two-pass rendering — separating tree construction from serialization
- Sitemap instead of routes — an explicit URL tree instead of file-based routing
- Compression without zstd — Brotli Q11 and Gzip 9, no third codec
- Hosting and format negotiation — format selection at a single URL
- The repository family — independent
nuckty-*repositories and a singlenuckty-codestylerulebook
The common criterion
The criteria running through every decision: long-term support of a TypeScript project, ease of maintenance, and speed. The amount of code already written and the cost of migration are not counted. Sunk costs are not an argument for a worse decision going forward.
Each record connects the choice to concrete data structures, extension contracts, and maintenance tradeoffs. Comparisons of build speed or maintenance cost require separate evidence; the records do not establish a measured advantage by themselves.