/ writing

Building this site

Notes on the stack, the trade-offs, and what I'd do differently.

·2 min read·#nextjs#mdx#meta

A quick tour of how this site is put together, in case it's useful to anyone building something similar.

The stack

  • Next.js 15 with the App Router
  • MDX posts living in content/posts/
  • Tailwind CSS for styling
  • Octokit for the GitHub integration
  • Vercel for hosting

That's it. No CMS, no database, no auth. Everything is a file in a Git repo.

Why MDX over a CMS

The honest answer: I trust Git more than I trust myself to keep paying for a CMS subscription. Files in a repo are forever. Drafts are branches. History is git log. And because MDX is just Markdown with React, I can drop interactive components inline when I want to.

function Example() {
  return <p>This is a React component inside a blog post.</p>;
}

Trade-offs

The main downside is no WYSIWYG editor. If I'm out and want to fix a typo, I either pull up GitHub on my phone or just leave it. I've decided I'm okay with that.

The other thing: with this many static pages, build times will eventually get long. I'm not worried yet — but if you've got hundreds of posts, you'd want ISR or a partial build strategy.

This stack assumes you're fine writing in your editor and committing. If that's not you, a hosted CMS (Sanity, Contentlayer, Notion) is probably the better call.

Lessons from building it

A few small things that turned out to matter more than expected:

  1. Pin a featured project via GitHub topics. Tag a repo helios-featured and it bubbles up on the homepage. No config file to keep in sync.
  2. Use Server Components for everything GitHub-related. All the Octokit calls run on the server at build time, so secrets never reach the browser and the rendered HTML is fully static.
  3. Cache the GitHub API responses. Even with a token, the API has rate limits. revalidate: 3600 is plenty.

More posts to come.