Finding a Static Home

23 Jan, 2018

Having decided to move from Wordpress to a static site, I had to find a generator. I don’t know enough, and have not explored enough, to have an informed opinion, but I will write about my particular experiences and try to explain why I am choosing to use Hugo

What a Static Site Generator Does

In theory it’s simple. The generator works through a series of folders on my local machine and parses the files it finds into a different series of folders and files that make a web site. Usually, it will take text files (typically written in markdown) and turn them into the html files that a web server can send to your browser for display. While doing this it reads layouts and styles (also stored on the local machine with the text files) and incorporates these into the web files it generates. this provides a common look and feel to all the pages in the site.

Generators have rules about where these various files have to be placed within the folder on your local machine, and creates the web files in a specific folder too, ready for upload. They also allow templates and styles to be applied in flexible ways by adding “top matter” to the top of each text file (for example to say whether that text file should be generated as a blog post, index page, gallery etc.). It would be limiting if every web page on a site had exactly the same layout and style. The creation of text files for content and the templates and styles (usually called “themes”) create the site. The generator itself simply processes what it finds into the web files and places them in a folder ready to be uploaded to the server. Generators can do this quickly (typically a few seconds to process hundreds of files) and the templates and styling give a consistency that would be very hard to achieve if you manually coded each web page.

You can create your own themes or download (and maybe adapt) themes that have been created by other people. That leaves you to use the editor of your choice to create the content files, which include relevant top matter. You then run the generator to create the site. Most generators also allow you to run a simple web server on your local machine so you can test the site before uploading it to a “production” web site.

There is very little need for the generator to communicate with the person running it, except perhaps to give you error messages. For this reason, most generators run from the command line and do not have a user interface (windows, buttons etc.). This also allows people developing generators to use computer languages like Python or Go that are available for free on a range of systems, rather than having to “buy into” an Apple or Microsoft development system and deal with the complexity of opening windows, interpreting mouse clicks and the like.

This immediately puts some users into an unfamiliar environment. We are so used to seeing what we are doing with a computer, and interacting in a concrete form (e.g. clicking to make something happen) that working with the command line or in a terminal seems more abstract; almost “one step removed” from what you are trying to achieve. Many people who create and run web sites, however, are used to at least some of this abstraction and some of the people who define themselves as web developers will take pride in their mastery of the command line and the “hidden depths” of the operating systems they use.

My experience

I started with Jekyll, mainly because it comes up first when you search. It is probably the most popular static site generator and seems to have a lively community. Jekyll is developed and provided by github and is used to create their extensive sites as well as being recommended for the many developers and others who have web sites hosted on their system.

I found there was a significant learning curve, not helped by the bright and breezy approach that github takes to explaining how it works and what to do. I fully understand that their audience is people who are already involved in github and so used to the command line and the inner workings of their systems, but the quickstart instructions are simply five lines of code to be entered into the command line or terminal. I knew enough to be able to do that but hit immediate problems because the first line called two commands that were not installed on my mac. It took some extensive googling and fiddlling, for a couple of hours, for me to get to the point where I could actually run the five lines of code (actually four lines and a comment). That’s not a good start!

What was impressive, and delightful after quite a lot of frustration, was that it worked first time. I had a minimal but working local web site and I was able to add content.

Unfortunately, that early experience was not sustained. I managed to install a theme and push the web site on a little and was feeling quite pleased with myself. Time to start a real, rather than experimental, site. I set up a new folder and ran Jekyll, only to get a lot of error messages about packages not being installed. I ran the Jekyll installation again. It worked. I set up a folder for another site and hit the same problem. It looked like I had to install Jekyll every time I created a new web site. That could not be right! I often hit errors and problems whenever I tried to add a new theme or try a suggestion. I’m sure the underlying issues were not Jekyll itself, but the set up of my machine. Macos High Sierra is rightly sensitive about what can be written where and with what permissions. I needed some clarity about my Jekyll installation and what I needed to do to have it working and robust. I spent hours looking for this in the Jekyll documentation, but ended up in that familiar hell of contradictory opinions in forums, huge assumptions being made by official documentation (e.g. “make sure you gems installation is up to date” when I really needed to know how to install gems properly in the first place) and the github positivity which assumes that issues are not going to occur and you will somehow just fix them if you do.

After about two days of this (on and off) I remembered that I was trying to avoid spending too many hours dealing with the technicalities of my web site and the frustrations that go with complex and poorly explained software systems and decided that Jekyll simply is not for me. It looked very promising, but if I had to be an expert on all the subsystems of my mac in order to get it working, it was just not worth it.

Jekyll, like lots of github related things in my experience, does not feel like a place for beginners. It is for developers who think in code and have learnt their operating system commands and all their complexities by heart. Having said that, it had a logic and organisation that I really liked. Setting up sites and getting them working was fairly easy and you could have a good guess at what to do. It was my failure to get a consistently working installation and nowhere to tell me how to do that, that made it no-go for me.

If the complexity of installing packages and setting permissions in the subsystems of my mac were an issue, perhaps someone had a native mac generator. A quick search led me to Hammer for Mac

This generator is written as a mac application so you do not have to use the terminal. You create content files and click your way to the right folders and click a button to run the generator. It worked. First time. No problems. I was relieved and pleased. I was ready to pay for the software simply to avoid the frustration I had with Jekyll.

I soon turned to building a web site and it was here that the frustration returned. Hammer is pretty “bare bones”, at least at the moment. There are few templates and although the documentation is reasonably clear, it was obvious that I would be coding my site from scratch: creating templates and styles for myself. I wanted to create a simple blog site to start with, but where it was very easy to set a basic site with Jekyll, I would be coding all the logic myself with Hammer and I was really not sure where to begin. I got as far as looking for examples of how to have a main page which indexes other “post pages” but realised that I was already back into complexity and frustration and moved on.

I think there is a lot of potential in Hammer. I liked the interface and concept but having that, without the scaffolding that lets you get basic sites up and running quickly, limits it at the moment.

By this stage, I was ready to give up on static sites! After a gap when I was doing other things, I decided to try out the two other major systems, Hexo and Hugo. In the event, I tried Hugo first and was happy, so have not tried Hexo.

Whether it was luck, or its design, I was able to install Hugo easily, following its clear quickstart and having a working site within a couple of minutes. Hugo’s documentation was clear enough to let me set up several sites, with different themes, and to adapt them all within a short time. You’re reading one of them!

I am sure I will write more about Hugo soon, but an hour or so later, I was giving a sigh of relief and working on converting my main site from Wordpress to Hugo, which I was able to do within a couple of hours, including creating an accessible and re-styled archive of the old wordpress site. I was happy and now feel at home.

Of course, other people will have different experiences, but I think it is perfectly OK to adopt software that makes sense to you and that you, with your unique experiences and skills, can use productively and creatively with the least effort. I think that’s what software is for, but that’s another story.