I share 2 years of experience using the Hugo static site generator . This post is intended for beginners, but this post will not provide instructions on how to install Hugo or how to create a first post. This post will be useful to those who choose and compare alternatives for blogging.

Why static site generator and Hugo

Static site generator is a program that processes structured source files (texts, pictures, templates) and generates a static HTML site that can be uploaded to the server.

Site sources are a set of folders on a computer:

Separate subfolders contain theme templates, source codes of posts, general pictures. Several bat-files contain commands for typical operations: recording blog updates, starting the server for local viewing, creating a new post from the template.

Despite the seeming hostility, this approach, unlike CMS, is convenient for those who have some knowledge in HTML, CSS and other web technologies, but want the blog to remain technically primitive.

Subjectively, editing basic scripts on 5-10 lines is easier than digging into the source code of some CMS page. Also, you do not need to configure the environment on the server, deal with the database and installation security issues.

Limitations of static sites are that there is no way to use functions that are tied to users. As an example, you have to use a third-party comment system. For a blog, such restrictions are not critical.

For static sites, it’s easy to find and configure hosting

Static hosting, while the site does not have volumes of traffic, like Google’s, is configured easier than for dynamic sites, and in many cases it’s free.

I keep the source code and the blog itself on GitLab. Here's how it works:

1. GitLab's private git repository contains the source code for the blog.
2. When updating the repository, GitLab CI independently launches the generation of a new version of the site and puts it on GitLab Pages.

Scheme how it works:

At the end of the stack, Cloudflare is used to organize an SSL certificate for the https version of the blog.

Updating a site from making changes to the availability of an online new version of a blog in the Hugo-GitLab configuration takes 0.5-1 minutes. Most of the time Gitlab CI spends preparing to build the site. Directly generating a site takes 1-2 seconds. Other site generators will have a different update speed. For example, with another popular Jekyll site generator, building pages for a new version of a site can be several times slower .

Sources and hosting can be divided - generate site pages on the local computer, and upload only the resulting HTML files to the hosting. For statics, there are convenient hosting services, for example, Netlify. GitHub Pages previously worked on this principle. Some time ago, GitHub introduced CI automation tools, like GitLab.

No need to think about blog health support

If once without errors I uploaded a finished site to a server and you don’t change anything, then efforts to maintain the site are minimized. You only need to pay for the domain once a year. There is no need to think about security (for example, update CMS and plugins), pay hosting monthly, you can not be afraid of automatic updates.

Full control over source is maintained

Each post is a separate folder with Markdown text and immediately lying image files.

The posts prepared in this way, in theory, are easily transferred to other platforms. In practice, it is difficult to judge this, since it is difficult to find cases on the Internet.

This is what the data folder for 1 blog post looks like:

And this is editing the post itself in Sublime Text and the output page:

If you add the source code to the version control system, you can see the history of changes in the blog. The screenshot below shows a review of the change history from May 2018 in Sublime Merge:

Hugo was chosen among different generators due to its popularity, speed and ease of installation

Hugo is in the top 3 popular site generator on the Internet by the number of stars on GitHub.

The program itself is a 1 exe-file. Starting the generator does not require installation, but in order to call it with the hugo command, you need to register the path to it in the PATH system variable.

I already wrote about the speed of work above - Hugo is much faster than many other generators, which becomes important as the volume of the site grows.

Difficulties faced

You need at least a little understanding of programming or scripts

HUGO and other generators do not have a familiar user interface. Starting a site update is done through a set of commands or a single bat-file.

"Interface":

If you load a site through GitLab CI, then you need to be able to slightly edit the CI configuration file.

GitLab offers a number of ready-made files for different generators, which can be taken as a base:

But still you have to plunge into the config to fix something. For example, in the standard config (in the screenshot below) I recommend at least changing the version of Hugo (I will analyze the reasons later):

You have to manually edit the selected theme for yourself, you need HTML knowledge

The Russian-speaking Hugo community is not too large, so there are very few ready-made solutions that take into account the specifics of the Russian audience. There are no Russian-language themes, social buttons are adapted for foreign networks, themes are focused on using only Disqus comments, and so on. I had to independently rewrite the system inscriptions into Russian and put in sets of social buttons with networks that are popular among the Russian-speaking audience.

Even if you are not a front-end developer, welcome to the world of HTML templates with inserts on Go:

In Hugo, until recently, there was no such thing as plugins. All edits must be done in the source code of the topic. For example, if you need to correct text in the footer of a page, you have to edit the HTML theme template.

If the theme needs to be updated, then you must manually transfer your edits between versions of the theme. In case you need a complete transfer, you have to keep a text log with a description of all the changes in the original topic.

In the screenshot below ~ 1/3 of the list of changes:

It's hard to figure out how the generator engine works.

I didn’t try, but for all the time of use I couldn’t fully understand how the generator works. I won’t be able to create a topic or a complex blog structure from scratch.

It is not always possible to find a solution to the problem

If the problem is common to many users, then it is quickly repaired. But you can run into a problem that only you will encounter.

For example, after the upgrade, GitLab began to convert non-English characters in file paths to web-encode. This significantly increased file paths if they contained non-English letters. Because of too long paths, the process of building a site fell with an error. Mention of this particular problem I could not find. Got a ticket on the GitLab issue tracker, but there was no movement on it. I assume that the problem was related to a larger bug in GitLab CI, which was fixed somewhere in a month. This month, I temporarily solved my problem through hosting transfer.

The danger of updates and reasons to commit the version of Hugo

There is no guarantee that your settings, documents and the finished theme will work correctly without changes in the new version of Hugo.

For example, in Hugo version 0.57.0, the main page is no longer properly assembled. I could not understand what the problem was: in the bugs of the new version of the generator, in an unopened topic or in my source structure. I decided to stay on version 0.56. Then it turned out that the developers made compatibility-breaking changes to the configuration of the page generation algorithm.

The relevant question is whether it is worth updating in principle, if not to use the new functionality. After all, the lack of updates does not affect security, and compatibility can break. Example from the official Hugo forum:

On GitLab CI, in the script settings, I recommend that you hard-fix which version of Hugo to use.

By default, I used the "latest relevant", but several times I came across the fact that the new version changed important parameters of the site's rendering. Up to the point that the process of building a blog broke, or unnecessary posts appeared in RSS. I learned about this only after updating the site on the hosting or after getting into RSS. In the screenshot below, the feedly RSS story with permanently saved erroneous entries:

To summarize

Generator of static sites - suitable for those who are already a little versed in the front-end, wants with a limited immersion in the technical aspects to get a technically simple site / blog.

Hugo is a good choice if speed and ease of installation are a priority.

You can’t do without technical knowledge. Here and there you have to immerse yourself in HTML, CSS and other technical issues. On the other hand, once configured a site requires significantly less maintenance.