What I Learned Building A Site Generator

Last month, I accidentally broke my blog setup. I wiped out the node_modules directory for some experiment, and ended up not being able to re-download the dependencies due to some error. I thought I was done for, and was already looking for alternatives. Fortunately, all I needed to fix it was to bump up the generator's version. The older version relied on really old dependencies that didn't install well. However, I did build a static site generator... from scratch.

From scratch you say?

Yep, from scratch and here's why. When I accidentally destroyed my setup and was redownloading the dependencies, I noticed that it was like pulling in the entire internet. Hundreds of dependencies, a minute or two of downloading, some even compiling. WTF is going on? Then I thought: What if I can rebuild my blog with really few dependencies. Really ambitions. I'm sure I can't pull it off, but that's the fun of it. I get to try.

Native APIs are like half a sports car

(Get it? Sports car? Node.js? V8? Nevermind).

Now the first problems that came were from the native APIs of Node.

Question: How do you copy files in node? Answer: You can't witout some lengthy code. Use a module.

Question: How do you do a mkdir -p in node? Answer: You can't witout some lengthy code. Use a module.

WTF?! I thought that Node was just a high-level wrapper to unix operations, but these things don't exist? Seriously? No copy()? No mkdir({ parents: true })?

A build tool as a generator?

That's right. So after I tinkered around a bit with a few loose modules, the only thing I was missing is some system that just handled most of the heavy lifting. Grunt could have done it, but it's a task runner. Gulp could have done it, but I'd have to read up on streams which are a problem by themselves. Then I remembered Gobble. Plugins are just functions that either receive input and return output, or receive an input path and write to an output path. Sounds like I have a winner, I'll take it.

Remote systems are a mess

So time came that the site generator was ready for prime time. I had content migrated over, my templates were all in handlebars, had compilers and minifiers in place. Everything was ready until... I hit errors during the remote build. Errors that include npm saying architecture or OS not supported, to Node's notorious symlink errors to just plain old file system permission errors. WTF? It's one thing I hate about PaaS systems. You're provided this half-paralyzed Linux system which causes your stuff to blow up in spectacular ways. (sigh)

And there it is!

Anyways, If you want to see the static site generator, it's called Mechanical Pencil. Why the name? It's because I can't think of any. Why is it only the generator piece? That's because it was designed so that you can add your own bells and whistles to it. Development is as easy as building a Gobble plugin, and adding it to the build pipeline. No frills, no magic, just raw power of JavaScript.


Four weeks of design, 1 day to strip it back down to bare essentials and publish. Not too bad for an exercise. I currently have a version of my blog using the thing, complete with SCSS compilation, HTML minification and all that. Just need to find another hosting service that doesn't suck. Currently looking at Heroku, but the server has to sleep 6 hours of sleep everyday? Seriously? Is this a bad joke?

site generator learnings javascript

© Joseph Descalzota