Hugo

Hugo is a fast and modern static site generator written in Go, and designed to make website creation fun again.


Note

For this guide you should be familiar with the basic concepts of

License

From version 0.15 on Hugo is released under the Apache 2.0 license.

Prerequisites

Your URL needs to be setup:

[isabell@stardust ~]$ uberspace web domain list
isabell.uber.space
[isabell@stardust ~]$

Installation

Create website root

Create a new directory containing the sources for your website.

[isabell@stardust ~]$ mkdir hugo_websites
[isabell@stardust ~]$

Download

Check the Hugo website or Github Repository for the latest release and copy the download link to the Linux-64bit.tar.gz file. Then use wget to download it. Replace the URL with the one you just got from GitHub.

[isabell@stardust ~]$ wget https://github.com/gohugoio/hugo/releases/download/v0.121.1/hugo_0.121.1_linux-amd64.tar.gz
[…]
Saving to: ‘hugo_0.121.1_linux-amd64.tar.gz ’

100%[======================================>] 7,750,708   6.64MB/s   in 1.1s

2019-01-14 16:56:27 (6.64 MB/s) - ‘hugo_0.121.1_linux-amd64.tar.gz ’ saved [7750708/7750708]
[isabell@stardust ~]$

Get the hugo binary from the archive, delete the archive and enable hugo to be executed easily. Replace the version in the archive file name with the one you just downloaded.

[isabell@stardust ~]$ tar -xvf hugo_0.121.1_linux-amd64.tar.gz  hugo
hugo
[isabell@stardust ~]$ rm hugo_0.121.1_linux-amd64.tar.gz
[isabell@stardust ~]$ mv hugo ~/bin
[isabell@stardust ~]$

After setting up, test if Hugo works. The output is the version number of Hugo.

[isabell@stardust ~]$ hugo version
hugo v0.121.1-00b46fed8e47f7bb0a85d7cfc2d9f1356379b740 linux/amd64 BuildDate=2023-12-08T08:47:45Z VendorInfo=gohugoio
[isabell@stardust ~]$

Create first website

Hugo is now installed on your Uberspace. This means you’re ready to create your first Hugo site! To do this, switch to the corresponding directory and create the Hugo page there.

[isabell@stardust ~]$ cd ~/hugo_websites
[isabell@stardust hugo_websites]$ hugo new site hugo_web
Congratulations! Your new Hugo site was created in /home/isabell/hugo_websites/hugo_web.

Just a few more steps...

1. Change the current directory to /home/isabell/hugo_websites/hugo_web.
2. Create or install a theme:
   - Create a new theme with the command "hugo new theme <THEMENAME>"
   - Install a theme from https://themes.gohugo.io/
3. Edit hugo.toml, setting the "theme" property to the theme name.
4. Create new content with the command "hugo new content <SECTIONNAME>/<FILENAME>.<FORMAT>".
5. Start the embedded web server with the command "hugo server --buildDrafts".

See documentation at https://gohugo.io/.
[isabell@stardust hugo_websites]$

Add theme

Since Hugo is delivered without a theme, this must now be installed. To do so, look for a theme you like at https://themes.gohugo.io/ and install it into the themes directory of your site. This example uses the theme FutureImperfect, but you are free to use any other theme. Then copy the sample files into the project root, to quickly bootstrap you new site.

[isabell@stardust ~]$ cd ~/hugo_websites/hugo_web/themes
[isabell@stardust themes]$ git clone https://github.com/jpescador/hugo-future-imperfect.git
Cloning into 'hugo-future-imperfect'...
remote: Enumerating objects: 1, done.
remote: Counting objects: 100% (1/1), done.
remote: Total 1386 (delta 0), reused 0 (delta 0), pack-reused 1385
Receiving objects: 100% (1386/1386), 4.38 MiB | 6.65 MiB/s, done.
Resolving deltas: 100% (789/789), done.
[isabell@stardust themes]$ cp -R hugo-future-imperfect/exampleSite/* ../.
[isabell@stardust themes]$

Deploying your site

Hugo is a static site generator. It will build a bunch of HTML and CSS files, which can be served by any web server. In our case, there is a httpd set up to serve files in ~/html, so we tell hugo to drop the files there. Add the following directives to your configuration file, by default ~/hugo_websites/hugo_web/config.toml:

hugo_cache = '/home/isabell/tmp'
publishDir = '/var/www/virtual/isabell/html'

Warning

The following command will delete all existing files in your document root. Make sure it is empty before running it.

[isabell@stardust ~]$ cd ~/hugo_websites/hugo_web
[isabell@stardust hugo_web]$ hugo --cleanDestinationDir

Note

You don’t need the --cleanDestinationDir argument every time. Generally, you only need it to clean up files and folders in the publish directory if you removed, moved or renamed something. Running hugo without arguments will create new files and folders, but won’t remove those that are not needed anymore.

Finishing installation

Point your Browser to your installation URL https://isabell.uber.space and admire your shiny new website!

Tuning

To finish configuring your Hugo website, creating pages and posts, go to https://gohugo.io/documentation.

Updates

Note

Check the update feed regularly to stay informed about the newest version.

If there is a new version available, update the hugo binary in ~/bin (repeat “Download”). It might be a good idea to rebuild your site, too, but that’s not strictly necessary.


Tested with Hugo 0.121.1, Uberspace 7.15.6

Written by: Christian Kantelberg <uberlab@mailbox.org>, luto <http://luto.at>, Julian Oster <https://jlnostr.de>