I guess some of you have heard about HUGO and how it is a great tool for building static websites. Personally I have used it for creating this blog and also for my father’s company website ptaino.com. I don’t have any prior experience with other static generation tools so I am not in a position to compare it to other solutions like Jekyll. What I can share with you though is my personal experience after using it, why I love it and tips to get started.
HUGO?
HUGO is an open source static site generator written in Go and is a proper choice for people who want to create their personal blog, a portfolio site, company sites etc. . It uses Go’s package template standard library.
What are static sites?
In static websites all content (HTML,CSS, JS) is pre-build and stored on the server. Instead of dynamically producing content, server’s only responsibility is to send a file, which makes the whole process quite fast. All JS that comes with the web page will run exclusively on the client and no content rendering is done server side.
What is a static site generator?
The main ingredient of static site generators are templates which act as the base in which you place your content. When those two get rendered, the result is static pages.
Why should I use it?
One of the amazing features of Hugo is its blazing fast build times, since it can generate a simple one page site in a matter of milliseconds and that makes it a great tool for blogs like this one. You can watch this benchmark video showing how HUGO can generate 5000 static pages within 6 seconds :-) .
Also another great feature to consider is that all changes you make are almost instantly displayed on your running localhost server, so you can edit things on the spot (live reload feature).
Finally the installation process is quite easy and the learning curve is quite small.
OK where do I start?
To install hugo, follow these steps here. Also the detailed documentation can be found here. A great tutorial to guide you through HUGO’s basics is this one and this is the official get started guide. If you want to use a custom theme for your site (which is the most reasonable thing to do), there is a plethora to choose from which can be found here.
Starting the server
To run hugo type in your console hugo server -D -t theme_name. The parameter -D is optional and is needed only if you have created .md files or draft content.
Also -t theme_name is used for loading your theme.
Generating the content
Run hugo -D -t theme_name to generate static content from your HUGO code. All the generated files are located in your public folder.
Now, a tedious work you must always be prepared to do is deleting the contents of your public folder before generating a new version of your static page.
The reason is that something might be left from previous builds and thus affect your final result.
My approach
Now all of the above sound and are great, so I will share you my personal recommendation on how to approach HUGO if you want to build you own static website fast and with exploratory attitude. If you need additional help, just search the references above.
1) Important step but not mandatory, is to go through the tutorial. In my opinion you don’t need to watch all 23 chapters, just pay attention to directory structure, how markdown .md files work and how config.toml works.
2) Download an existing template and start playing around. Compare the template’s demo page with the repository code and with your code as well and see how your changes affect the final result.
How customizable can it be?
Well my answer is that I don’t know what you have in mind but yes, it is quite customizable. For my blog I added tags on every post, for categorization, navigation and searchability. Some coding was necessary but not that time was needed to short thing out. Also for ptaino.com I added a google map iframe which is nicely displayed. So yes you can add staff but it mostly depends on what you have in mind. The two themes I used are Stellar and retroful.
Difficulties I faced with HUGO
The biggest problem I faced after completing my two static websites, was that CSS wouldn’t load when hosting them on GitHub pages. For
thefuriousprogrammer.com, there was a global setting in my template which I hadn’t setup properly and thus the CSS file path was not valid. All the formatting displayed perfectly on localhost though, so I couldn’t notice that earlier. Forptaino.comthere was a problem with mixed content where some .js and .css references where is plainhttp://and nothttps://.Also another issues was ‘markdownify’ parameter on my template which caused some build issues. Well I just deleted it problem solved :-)