# I built my own blog generator because jekyll annoyed me

So I needed a blog, right? And everyone always says "just use Jekyll," which is, like, the defacto thing for GitHub Pages. It's mature, well-documented, tons of people use it. The "safe" choice.

Which obviously meant I had to go build my own static site generator instead. Because that's just what I do when there's a perfectly working solution - build my own. This happened during one of my classic procrastination spirals where I was desperately avoiding AP Physics homework and French assignments. Suddenly, building a static site generator seemed way more important than conjugating French verbs, which tells you everything you need to know about my priorities.

Does this sound completely ridiculous? It probably does. Why reinvent the wheel when perfectly good wheels already exist? But hear me out - I legitimately had reasons, I swear. (Though, honestly, part of it was just me being stubborn and wanting to do it my own way.)

# What Bugged Me About Jekyll

Look, Jekyll isn't terrible. Actually, it does what it's supposed to do pretty well. But every time I tried to use it, I just... ugh. Here's what got under my skin:

Ruby dependencies are an absolute nightmare. I work in JavaScript, mostly. Don't get me wrong, Ruby has its place, but I wasn't about to install Ruby, figure out gem management, and troubleshoot Ruby-specific build errors just to have a blog. Every time I switched computers or updated my macOS, something would randomly break. Suddenly I'm spending 20 minutes troubleshooting RVM vs rbenv issues instead of actually writing. That's just... nope.

The plugin situation is wild. Need search? Plugin. Want better syntax highlighting? Plugin. Want RSS that actually works the way you want? Another plugin. Soon you're playing dependency jenga, hoping all your plugins still work together. And like half of them haven't been updated in 3+ years. It starts feeling like WordPress territory. Nothing inherently wrong with that... (okay there's a lot wrong with it, but that's a different rant)

GitHub Pages restricts which plugins you can use. You can't just install any Jekyll plugin on GitHub Pages - they have this approved list. So either you're limited to their blessed plugins, or you build locally and manually push the compiled site. Which defeats the whole "automatic builds" convenience. Arg.

Configuration is unnecessarily confusing. That _config.yml file has like a billion options, and the documentation assumes you already know what you're doing. Simple stuff like "display 10 posts per page" requires diving deep into their pagination system and understanding template inheritance. Why does this have to be so complicated?

It felt like Jekyll was designed for people who were already Jekyll experts. No beginner-friendly path, just "either you know it or spend hours figuring it out." I was not here to spend hours.

# What I Actually Needed

I just wanted something super, stupidly simple:

  • Write Markdown files (this part is easy)
  • Run one command (this should be simple)
  • Get a website (then I'm done)

No Ruby dependency hell. No complex configuration maze. No plugin treasure hunts. Just Node.js (which I already use for all my other random scripts) and some npm packages that do exactly one thing and do it well. Period.

I also wanted certain features baked in from the start:

  • Full-text search without running a separate server
  • Dark mode that respects system preferences (I always browse in dark mode, and it's annoying when sites don't support it)
  • Clean URLs without .html extensions everywhere
  • Fast builds even if I somehow end up with lots of posts someday
  • RSS feeds + sitemap generated automatically (for SEO and people who want to follow my writing)

None of these are exotic requirements, right? But getting them working in Jekyll meant wading through the absolute mess that is plugins, themes, and confusing config options. I was spending more time configuring than writing. That's completely backwards. I want to write, not futz around with build configurations.

# Making MarkSite Happen

So yeah, I built MarkSite. Took me about two weeks of messing around in the evenings. Was it worth it? Jury's still out, honestly.

Tech stack I went with (the "simple" version)

  • Node.js (was already on my machine, zero setup needed)
  • Marked for parsing Markdown (does exactly one thing, does it well)
  • Nunjucks for templates (like Liquid/Jinja but using JavaScript, so I can actually debug it when things go wrong)
  • Highlight.js for code syntax highlighting (just works)
  • Date-fns for formatting dates consistently (because JavaScript dates are a trip)

That's literally it. No bloated frameworks, no complex build pipelines. Just a few packages that do their job without extra drama.

How it actually works

  1. Read all the Markdown files from the content/ folder
  2. Parse that frontmatter metadata (title, date, tags, etc.)
  3. Convert Markdown to HTML
  4. Apply those Nunjucks templates
  5. Generate RSS feed, sitemap, and search index
  6. Dump everything to the _site/ folder

The entire build script is maybe 300 lines of JavaScript. Not rocket science. I can open it and understand what's happening, which is more than I can say for Jekyll's internals.

Basic commands

marksite build        # builds the site
marksite serve        # runs local server for testing
marksite new "title"  # creates a new post template

That's all I needed. Everything else is just writing Markdown.

# How I Made Some Key Decisions

Why Nunjucks instead of other template engines?

Mozilla maintains it, has decent documentation, and the syntax is similar to Liquid templates (Jekyll's default). So I could borrow ideas from existing Jekyll themes if I needed inspiration. Plus it's just JavaScript underneath, so I don't have to deal with weird compilation steps.

Why client-side search instead of a server?

I wanted search functionality without running my own server or paying for a service. Client-side search means I generate a JSON index at build time, then JavaScript searches that in the browser. Works instantly and costs me nothing. Win-win. No server infrastructure to manage.

The search index is literally just an array of objects containing post titles, content previews, and tags. Bundle it as /search-index.json. Load it when someone hits the search page. Super simple. And it works surprisingly well.

Why not use React-based stuff like Next.js or Gatsby?

Too heavy for what I needed. I don't need React just to serve static blog content. Those frameworks are great for complex web apps, but for a simple content site they're overkill. Plus slower build times and way more moving parts to potentially break. I wanted something fast and simple.

Why did I add dark mode support?

Honestly? Because I use dark mode constantly and it's so annoying when websites don't support it. Adding it was literally just CSS custom properties and a prefers-color-scheme media query. Took maybe an hour to implement. Such an easy win.

# What This Whole Thing Taught Me

Look, building your own tools will teach you way more than just using existing ones ever could. Fair warning though - this also means you're on the hook for any issues that come up. Can't blame poor documentation or buggy third-party packages. When something breaks, it's 100% your fault. Though strangely, that's kind of liberating.

Here's what I learned:

  • How Markdown parsers actually work under the hood
  • How template engines render HTML (fascinating and more complex than I expected)
  • How to structure a simple command-line tool (more involved than I thought)
  • How RSS feeds are formatted (turns out they're just XML with specific tag structures)
  • How sitemaps function for search engine optimization
  • How to build a search index from raw content

This knowledge is helpful for more than just blogs. Now when I look at other static site generators or build tools, I actually understand what they're doing internally. I'm not just copy-pasting configuration snippets from Stack Overflow anymore.

The real reason I built this (honestly): I wanted to understand how these tools actually work. Documentation only sinks in so much - you learn by doing. I'm hands-on like that, so actually building something helps clarify concepts I'd otherwise struggle with. I learn by breaking things, not reading about them.

# Would I Suggest This Approach?

If you just need a blog and don't care about understanding the internals: definitely go with Jekyll. Or Hugo. Or 11ty. Honestly, they're all fine. They work, and you don't have to build anything from scratch.

But if you want to genuinely understand how static websites function, building your own is totally worth the effort. The time I "wasted" on MarkSite wasn't actually wasted. I understand web fundamentals a lot better now. I know exactly how Markdown parsing works, how templates render, how RSS feeds are structured.

Plus, now I have something I actually control completely. No waiting around for plugin updates. No mysterious build errors from third-party code. When something goes wrong, I know exactly where to look because I wrote the whole thing. That's valuable to me.

Also, it's kind of a flex depending on who you're talking to. "I built my own static site generator" definitely sounds cooler than "I use Jekyll."

# The Downsides (or Upsides, depending on perspective)

MarkSite definitely doesn't have:

  • A theme marketplace (so you're on your own for styling)
  • Plugin system (any enhancements require code changes)
  • Large user community (it's just me and maybe a few early adopters)
  • Proven scalability (I have less than 10 posts right now, so scale-testing is premature)

For a personal blog like mine, none of this matters. For a company blog or massive website, you'd probably want something more established and tested.

But for learning and having complete control? Building your own approach wins hands down. No question about it.

MarkSite is on GitHub if you're curious. The code is messy (I'm sure I made some dumb decisions), but it works for me. Feel free to use it, improve it, whatever. Just don't call me out if you spot something embarrassing I did - I already know it's there.

Also, this was built during what I can only describe as a particularly intense period of French homework avoidance. My teacher definitely would not be impressed with my time management priorities.