Before putting this website up, I decided to look through my old GitHub repositories. I found a static site generator that I wrote in 2015, which was a really fun project. It just turned markdown into pages and blog posts. I had tried using Jekyll and Hexo, but I wanted to build something similar.

Unfortunately, the generator some edge cases that I couldn't figure out, so I never published it.

Looking back, it was refreshingly concise. It reminds me that rolling your own software is the most efficient way of learning how things work.

The architecture looked something like this:

• Markdown files were stored in a directory.
• A JSON file had a database of metadata; i.e. each Markdown file could be associated with a title, publish date, etc. I couldn't find a Markdown parser that handled front-matter properly, so this was an acceptable workaround.

• A Node server that:

  • Parses these Markdown files into HTML
  • Generates an index
  • Generates as few other static pages
  • Saves all of these to an output directory when building for production
• For development, Nodemon to restart the server whenever there's server changes.
• For client-side javascript, budo to trigger a LiveReload whenever the JS bundle changed.
• A post-push hook would SSH into my server, invalidate caches, and pull the latest commit. This is also how this site is deployed.

The only dependencies were Koa, a markdown parser (I used marked), EJS (to organize code for static pages), and highlight.js (to server-side render code snippets).

Though I'd swap out some tools, this design holds up. It works in modern browsers, Node versions, and adds little bloat. It doesn't do too much.

I love software with narrow scope. The author can inspire readers to easily understand it, remix it, and build something new.