Static
Introduction
You want a website for yourself, perhaps a one page portfolio or a simple blog? Or perhaps take that a bit further and have content about you and what you do. But how? Learn HTML and CSS? Spend ages creating it, then a month down the line you want to add more content and then you need to remember what you did, then duplicate the supporting code to adjust the content. Then later on you want to change the layout, and what happens, you have thirty or more files to update! That’s when a content management system comes into play. One that can organise and transform your content into web presentable material.
Website content is shown to the user typically with a web browser, that content is a mixture of HTML and one or more of CSS and JavaScript. The content itself can be generated either dynamically or statically. With ‘dynamic’ the content is created in response to zero or more inputs from the client (for an overview of this, please see ‘The first step – part one’). This is great when you have lots of users and a complex system, but there is a downside, speed. This is because the server needs to generate the content (ignoring the possible benefits of caching) for each page it serves to the client. Such content management systems for generating dynamic content are WordPress (what eLearningWorld employs) and Moodle. But what if there is only you? That you need a simple website that you (or possibly if managed, a few others) update every now and then? That’s when you can generate the content locally and then put it on the server. The content does not change in response to the client (generally) but is the same to everybody that visits your site, thus ‘static’. All the server then needs to do is serve the content, there is no additional processing = speed. That’s what I decided I needed last year after I found out about a generator called ‘Hugo’ from Bas Brands (nl.linkedin.com/in/bas-brands-31940416). In this post, we’ll start to look at how you go about this.
Disclaimers
Names / logos can be trademarks of their respective owners. Please review their website for details.
I am independent from the organisations mentioned and am in no way writing for or endorsed by them.
The information presented in this article is written according to my own understanding, there could be technical inaccuracies, so please do undertake your own research.
The featured image is my copyright, please don’t use without my permission.
Enter Hugo
Hugo (gohugo.io) is one such content management system that generates the output you need from the content that you provide. And best of all, that content is in Markdown (daringfireball.net/projects/markdown and en.wikipedia.org/wiki/Markdown) format. Markdown is a simple text based format that allows you to specify how content should be rendered using a text based syntax. As well as text, you’ll almost certainly want to use images and other binary files. Hugo supports this through an organised content folder structure and text based references in the markdown files.
Intent
I have no intent of duplicating the documentation already provided, gohugo.io/documentation, but instead will focus on a progressive practical tutorial in building a Hugo site. There are three key elements to a site, the configuration, the theme, and the content. The later, you’ll be able to adjust and add to, the theme I’ll initially provide and the configuration I’ll guide you through. There are lots of themes already available, themes.gohugo.io, but I wanted to provide one that was simple and we could improve over time. And so allow you to learn a bit about the Go (go.dev) language, HTML, CSS, SCSS and the Bootstrap (getbootstrap.com) framework if desired.
Get and install Hugo
You can download and install Hugo from gohugo.io/installation, we will need the ‘Extended’ edition as the theme I’m using has SASS (sass-lang.com) that needs to be compiled into CSS (en.wikipedia.org/wiki/CSS). Another reason for providing the theme is the complexity, something that took me a ‘moment’ to get my head around a new language and Hugo specific templating syntax (unlike Mustache that Moodle uses – A_bit_of_Mustache_December_2021), and thus not lumber you with a steep and scary learning curve.
Get the example
You can download the example site and contained theme from github.com/gjb2048/hugo-elw/tree/Oct_2023 or if you’re happy using Git (git-scm.com), ‘git clone -b part_one https://github.com/gjb2048/hugo-elw.git’ and checkout the ‘Oct_2023’ branch. Once you have done that, and extracted the files / folders for the zipped version, then open up a terminal or command prompt and head off to that folder.
Note: The images are my copyright, and are licensed under CC BY-NC-SA 4.0. To view a copy of this license, please visit creativecommons.org/licenses/by-nc-sa/4.0/.
Running locally
Firstly, we’ll only serve the site locally using Hugo’s built in web server (gohugo.io/commands/hugo_server) which is great for both content and site creation / development. Type ‘hugo server –disableFastRender’, where the ‘disableFastRender’ option will ensure that we see any changes to the theme code:
Now that it is up and running, open up a web browser and enter the address shown by the server:
Have a browse of the content and compare with the supplied ‘content’ folder.
Add a little content of your own
When adding content its initially in a draft state and won’t be generated, so close down the server with ‘Ctrl-C’ or what the key press is that the server tells you and add the ‘—buildDrafts’ option and restart.
In another terminal / command prompt in the same folder, type ‘hugo new posts/mypost/index.md’. This will create the bare markdown file for a post which is a transposed copy of the ‘template’ in the ‘archetypes’ folder called ‘posts.md’ using the ‘Front matter’ (gohugo.io/content-management/front-matter). In a text editor of your choice and with the syntax of Markdown in mind, such as www.markdownguide.org, and type what you wish! As soon as you save the file Hugo’s server will rebuild the site and you can see the result in the browser.
A quick deploy
At this point I’m not going to deep into ‘deploying’ your site, which is to generate the output for the web browser as files and folders. However, if you have a local web server (en.wikipedia.org/wiki/Web_server) such as ‘Apache’ (httpd.apache.org) installed, perhaps as a part of an ‘AMP’ package (en.wikipedia.org/wiki/List_of_Apache%E2%80%93MySQL%E2%80%93PHP_packages), a physical server (even remote), or even better a ‘single board computer’ such as the Raspberry Pi (www.raspberrypi.com) then edit the ‘hugo.toml’ file in text editor and change the ‘baseURL’ to that of your server and the folder (if any) that you’ll put the site in. Then run:
hugo --minify --cleanDestinationDir
Which will generate the site and put it in the ‘public’ folder. The ‘minify’ option makes the output as small as possible and the ‘cleanDestinationDir’ option cleans the public folder before outputting so that you always know that you have no old files. Then copy the files and subfolders to your server as normal and serve:
Pi deploying
To get up and running with Apache on your Pi, install Apache with:
sudo apt install apache2
Then change the permissions to the served folders user that Apache is using:
cd /var/www sudo chown -R www-data:www-data . sudo chmod -R 0755 .
By default, ‘/var/www/home’ will be served. Now type ‘ip add’ to get the IP address of your Pi, and put that in the ‘baseURL’ of ‘hugo.toml’, ensuring that you have ‘http’ and not ‘https’ (unless you’ve configured that in Apache), thus “ baseURL = ‘http://yourPiIP/’ ”. Generate the site and then copy the contents of the ‘public’ folder to a folder in your home folder on the Pi, as you’ll be logging on not as the ‘www-data’ user (a no logon user). You could use WinSCP (winscp.net/eng/index.php) for this if you’ve installed Hugo on Windows. Then copy the files to the ‘home’ folder, for example:
cd /var/www sudo -u www-data cp -R /home/pi/transfer/elw/* .
Where I’ve placed the contents of the ‘public’ folder in ‘/home/pi/transfer/elw/’. If you want to redeploy, then with caution, remove with:
cd /var/www/home sudo -u www-data rm -Rf *
Then repeat the copy after re-transferring.
Note: In case you’re wondering why I’m not running Hugo on my Pi, that’s because the one I’m using is a B+ and that only supports the 32-bit OS, whereas Hugo Extended requires 64-bit.
Next time
In the next post we will look at adding images to your posts and site.
Conclusion
I hope that you’ve been able to install Hugo, download and use my example site to serve locally, explore the structure of the content, create your own page, generate the minified site and upload to a test server.
What do you think please?
- Moodle 4 Security – A Review – 16th April 2024
- A little bit #fab – 16th March 2024
- Static framework – 16th February 2024
Very interesting – I’d never really taken the time to look into Hugo.
But it’s very cool !