Choosing a Static Site Generator

23 January 2020

Summarizing the moral of my efforts made so far to build a blog, I’m stating here for the record again that it is not always trivial to find the appropriate tools for the job. Therefore, I must know exactly what problem I wish to solve by using one of these shiny static site generators.

On my motivation you may learn more either on the in the previous articles of the series. On the progress of installing and developing the exact features there I’ve also created a roadmap.

What I am looking for

I think that it is usually wise to enumerate our personal criteria before opting for one tool or the other, also considering whether we need one in the first place. Here are my priorities:

Stability

From a general point of view, I’m planning long term, therefore I would like to build a maintainable system. It either has to utilize less automation (“magic”) or it has to do that behind a stable API and through a stable manner. It is not that great if my product breaks on every minor version update of the framework I use either because of a bug or an interface change.

Maturity

It does impress me when I see a project with over 40 000 stars on GitHub, but building upon it becomes instantly out of question if it isn’t at least 2-3 years old and still actively developed. Given active maintenance, I find the older, the better. I consider it also a good sign if there is a couple major version numbers behind the project.

Ease of use

I think, that the ideal framework is one that allows me to concentrate on creating content and make changes on the appearance or the structure of the site, instead of forcing me to fight against that particular framework itself. It should be well documented, easy to use and out of the way. The perfect tool is a tool I don’t know about. By contrast, a tool that may use some improvement is one that has a steep learning curve.

Versatility

When I’m outsourcing some of my jobs to some form of automation, then I’m also making a decision on what contracts I want to define myself and what are the ones that I don’t find really important, and therefore I am willing to obey to.

The contracts I demand are:

  • The ability to template using layouts and includes/widgets
  • The ability to template “semi-programatically” according to some data model and source - with other words, to generate templates according to, for example, the contents of a .json file. (Jinja2 is a templating language for Python with this capability, meanwhile Golang templates also features that)
  • The ability to start from scratch, without a theme or anything fancy, and start enabling the features one by one.

What I don’t find that important:

  • Which templating language is used
  • What programming language is the framework written in
  • What is the format of the data file
  • Build time, given it is not horribly unacceptably long (more than 1-1.5 second for a post like this one)

On being too critical minded

Note that while I define these needs with ideal assumptions, I am actually aware of the reality that surrounds me. It is a fact that I get most of these tools for free in exchange for a small attribution. It is also true that these are developed mostly by enthusiastic volunteers, by sponsored people in some cases, and it also happens that a company open sources some of its source code.

When I lay out what a particular implementation should or should not do, I’m not claiming that the ones failing the fulfill some of my requirements are worthless software. In fact, I am more than thankful for every developer who help others by providing intermediate tooling. They make the work easier for lots of people creating software for the end user behind the scenes. Nevertheless they are not the ones who receive the most credit however essential their work is. Just think of the well hidden “legal” menu section of Android settings - that is the place for the framework and library creators to receive credit, and I am guilty of this practice myself as well.

Criticism, on the other hand, can have more use than sounding arrogant. I believe, that having a vision of the perfect product is the key for improvement, for it is the way to recognize the practical weaknesses. As someone who thrives for the best what is feasible in a situation, I like thinking critically, and use that mindset as a compass for creating a better product. Meanwhile, defining my requirements also helps me finding a good enough solution instead of the best one, which effort is usually the enemy of getting things done at all.

Once again, I hereby would like to say thank you for all the developers of open source libraries and tools! Please check out the legal acknowledgements menu for all the credits of this site.

Let’s see what we have on the shelf

Time for me to make a choice! Let me share with you my experience with some of the generators I have given a chance.

Hugo

A promising candidate with long history of development, and I would happily come back once to see how it has progressed since. As far as I informed myself, at this stage it complies to my demands on functionality. I would not say yet that I am ready to use it in production, however:

  • We have it since 2013, but it still has not reached version 1.0. Maybe it is just a convention I find weird, but 0.something as a version number usually indicates for me that the project is not yet ready with the originally planned minimal feature set.
  • When I did some test runs, I had a problem with the workflow as well:

There is a lot of work in the documentation which I always find invaluable. I have successfully launched a Hugo site with a recommended theme, and could learn on the concepts a lot. Despite that, when I wanted to build my own look and feel while adding content incrementally, I had a hard time finding anything official on how to start using this generator from scratch, that is, without a theme.

I did not want to learn the complete framework just to get started, only one feature at a time. I wanted to start building block by block, carefully choosing what I need and what I don’t. Using Hugo the way I tried felt like just having to put in too much work to release the first version of the site. After fumbling a couple hours for some days with it without sensing an actual progress, I moved on. (I think, I’m experiencing the phenomenon called feature creep)

Well, note also that Hugo was the first on my list to try and I have got to it with no experience on SSGs whatsoever. It calms me that I know I was not the only one who encountered this issue.

I think, that this problem can be easily fixed by extending its documentation and I’m happy to look back some time later, as it has already gathered around itself a really large community who have put a lot of work into it.

(and I also like the idea of saving processing power by utilizing a resource friendlier programming language)

Gridsome

After having a pleasant experience with Vue.js, I was interested in Gatsby’s clone in the Vue world. Here is my experience.

I could use all the features I had in Vue, including its modular system and element encapsulation - one of my most desperately wanted features.

By element encapsulation I’m referring to bundling HTML structure, CSS styling and JavaScript code to one file, making sure their behavior does not affect the rest of the site. I find the hardest part of that task segregating the targets of the stylesheet, and Vue does a great job with its <style scoped> tag.

As this framework does utilize some JavaScript to cache page content, I could argue that its loading times were even shorter than simply reloading plain html files.

It felt like developing an application in Vue.js as I was used to it, except I already have the routes, layout and include system, etc. wired out. I could just start laying out my site and that was a really great experience! I also would like to mention that the generated starter boilerplate contained a lot of really helpful documentation comment and made it easy for me to know what I should keep and what can I clean up.

I quickly designed the content area and the sidebar, and it was a seamless experience! Somehow, nothing collided! Frankly, I did not have a word.

I fell in love with this framework quickly, then I did some research and backed off two steps.

  • Its most up-to-date version is 0.7.12
  • We have it almost since only yesterday with its first commit dating to August 2018.

I think, given some time to it, this project has really good chances. Also, it is gaining popularity really fast. On the other hand, being so fresh also means that online forums are not yet populated with the solution to its most common problems, and a plugin ecosystem did not really have time to evolve. Also, although it is popular, I still think it is a risky choice given its young age.

It builds its foundations upon Vue.js, which I consider one of the most mature projects in the JS word, but we need some patience. I can’t wait to look back again!

Good luck, Gridsome development team! I’m really excited about your project!

(why not Gatsby then?)

Because I did not like the React ecosystem :P I’ve experienced a steep learning curve, it was really hard for me to judge where to put when and what to keep my codebase maintainable. It did not hide those details that I specifically do not want to hassle about. (but note that it is only specific to my use case!)

I think that I am not mature enough for React and Gatsby yet.

Even if I’m a big fan of Arch Linux, I probably would not recommend it for someone who just wants to see something working, without diving deep into the details.

Hexo

The development of Hexo has started in 2012 and released 1.0.0 in March 2013. Its current version is at 4.2.0, and with all that in mind, it is the most mature one of my options so far.

It was a pleasant experience to get started as it worked right out of the box. It has a default theme that shows you the full capability of the tool, whereas Hugo did not have one… but they at least recommended one in the documentation.

Hexo supports layouts, partials (includes/widgets) and data files. It also focuses on blogging and has pagination included. Also, some helper scripts allow you to quickly scaffold your site. A quick build time is promised as well (even a hundred of pages per second).

It seems like it has all the features I need. I probably wouldn’t regret if I chose that.

In the end, I have chosen Jekyll instead.

Jekyll

Jekyll is even older than all the sites generators mentioned above, it has appeared in GitHub in 2008 - nonetheless it reached version 1.0.0 in 2013 - and version 4.0.0 just has been released. It is actively maintained and features more or less the same capabilities as Hexo. Jekyll and Hexo both look modern and clean to me, not suffering from legacy code problems (or I was not looking enough).

  • It has layouts & includes
  • It supports templating from data files
  • It has a past and a high popularity since then (the second most popular after Hugo, according to GitHub stars) – probably I could count on plugins and online questions on common problems

I would say, that among these options, Jekyll and Hexo are the most decent options for my project.

If there is one thing that I particularly like about Jekyll, it is that you do not need to generate a starter boilerplate to begin building (to clarify myself, the prior ones probably did not need a skeleton project either, I just did not really found documentation on that). First you may just have a markdown file and you can start using the features you need one by one. Lovely! I only spend time to learn those parts of Jekyll that I am particularly interested in! But don’t worry, it has a starter boilerplate generator tool if you wish to use that.

I have chosen Jekyll and I am satisfied with it since. Hexo probably could have been a great choice for me too. I preferred Jekyll for two things:

  • It is older, therefore I expect more community support, plugins and documentation.
  • A Jekyll site can be built up from scratch.

Will any of the above satisfy you?

The answer to this question is the usual: it depends. I strongly recommend you once again to enumerate your specific requirements first on what tool are you looking for, and then start experimenting and searching.

Remember: you choose tools for yourself, nobody else cares whether you used Vim or Emacs to build your site ;)

Good luck, and thanks for reading!

tools