Building Human Codebase: Technical Notes

A brief account of how this site was built and why.

Stack

• Framework: Next.js 14 with App Router
• Styling: Tailwind CSS v4
• Language: TypeScript throughout
• Content: MDX files with gray-matter for frontmatter parsing
• Hosting: Vercel (planned)

The goal was minimal complexity and maximum writability. Adding a new piece of content means creating a .mdx file — no database, no CMS, no build step beyond what Next.js handles automatically.

The Content System

Content lives in /content/[section]/[slug].mdx. Each file has frontmatter (title, date, section, type, excerpt, readTime) parsed by gray-matter. A small utility in /lib/content.ts handles reading, parsing, and sorting.

This scales reasonably well to hundreds of posts without needing a database, and it means content is version-controlled alongside code.

Design Decisions

Dark theme, no toggle: This is an editorial product, not a productivity tool. The aesthetic is intentional. A theme toggle adds complexity for marginal value.

No JavaScript framework for content: Article content renders as static HTML. The only client-side JavaScript is the navbar (for the mobile menu) and the newsletter form.

MDX over plain Markdown: Allows interactive components to be embedded in articles when needed for experiments and visualisations, without requiring every article to use them.

What I'd Do Differently

In retrospect, I'd start with a proper type for the navigation structure rather than duplicating the array in Navbar and Footer. Small thing, but it violates the single-source-of-truth principle.

I'd also think harder upfront about the article URL structure. Currently /[section]/[slug] — which means a slug must be unique within its section. Works fine at this scale.

What's Next

• Search functionality
• Related articles
• Reading progress indicator for long-form pieces
• Dark/accessible colour contrast audit