A part of the series I Hate the Web

I used to generate HTML from a single big Org-mode file. But it grew and grew and the exported page became sluggish and slow, as the the poor little export theme I was using didn’t seem to handle big content that well.

So today I spent wasted more than ten hours looking for a simple way to generate a static site from Markdown-like data.

Conditions:

  • A simple dark mode theme.
  • Self-hosted, no third-party website involved.
  • Simple and sane generation from plain files (Org or Markdown), preferably without needing to edit any layouts or templates.
  • support, preferably offline as a post-processing option.
  • Code highlighting by default and the usual stuff.
  • Time from download to having a command-line setup to generate output should be less than two hours.

Easy, right?

  • Jekyll: Seemed like a pain to get offline rendering going, plus it’s Ruby. So it was pretty easy to dismiss, because I expected it to be easy to find a good alternative.
  • Hyde: Python 2?! Instant delete.
  • Pelican: Pure Python, which is nice. Found a plugin for math, lots of themes, was raring to go. But then as I went through the themes and templates I started to despair… The few dark ones I found were bad or broken.
  • nikola: looked pretty clean and well-designed. Also Python, checks most of the boxes, but has one dedicated dark mode theme, and it doesn’t look very good.
  • Retype: Tons of good usability features by default, but closed source? There wasn’t a way to do the simplest modifications. It seems they’re preparing to go commercial with it.
  • Hugo: some promising themes and layouts. I’d given up on offline at this point, so I was in compromise mode. I was so tired at this point that I actually started using it. After several hours I was deep into editing HTML templates for page listings and whatever else nonsense before the existential question “what am I doing with my life?” jolted me awake.
  • hexo: a convoluted and bloated mess.
  • At some point I also started to seriously consider just writing some scripts of my own using pandoc, but then I’d have to generate indices and menus and…

In the end I just gave up and went with mdBook even though it lacks several features (the side bar being extremely limiting, not allowing links to sub-sections or generic content).

When I’m less depressed I might go back and try Jekyll or some other alternatives again.