Hugo¶

License: Apache License 2.0

This guide is tested with Hugo 0.165.0 on Uberspace 8.0.91. We can't guarantee it to work with newer versions.

Hugo is a static website generator using the Go programming language for its super-fast execution and rendering times. It's basically a single binary file, fed with Markdown-based text-files as a source.

A large Theme directory exists as a good entry point for novice users.

Note

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

Git
Domains

Prerequisites¶

An URL needs to be set up:

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

Installation¶

Let's use GitHub's API to fetch the latest version of Hugo, followed by extracting the binary file in the newly created ~/bin folder:

[isabell@moondust ~]$ mkdir -p ~/bin
[isabell@moondust ~]$ hugourl=$(curl -fsSL https://api.github.com/repos/gohugoio/hugo/releases/latest|grep -o 'https://[^"]*hugo_extended_[^"]*_linux-amd64.tar.gz'|head -1)
[isabell@moondust ~]$ curl -fsSL "$hugourl" | tar -xz -C ~/bin hugo

Check if Hugo works properly by asking for its version:

[isabell@moondust ~]$ hugo version
hugo v0.165.0-76a5e1880ab46688155b02e99bab9be2a6134492+extended linux/amd64 BuildDate=2026-08-12T14:26:28Z VendorInfo=gohugoio

The first website¶

Create a new folder for Hugo's assets, themes and configuration files, as well as for your Markdown documents:

[isabell@moondust ~]$ mkdir ~/hugo_sites && cd ~/hugo_sites
[isabell@moondust hugo_sites]$ hugo new project an_astronauts_blog
Congratulations! Your new Hugo project was created in /home/$USER/hugo_sites/an_astronauts_blog.

Just a few more steps...

1. Change the current directory to /home/$USER/hugo_sites/an_astronauts_blog.
2. Create or install a theme:
   - Create a new theme with the command "hugo new theme <THEMENAME>"
   - Or, 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/.

Adding a theme¶

Your newly created website needs a theme. We use the theme named in Hugo's official documentation here.

You may also pick one in the Theme directory.

[isabell@moondust ~]$ cd ~/hugo_sites/an_astronauts_blog
[isabell@moondust an_astronauts_blog]$ git init
[isabell@moondust an_astronauts_blog]$ git submodule add https://github.com/gohugo-ananke/ananke themes/ananke

Add the following to hugo.toml in your site folder (e.g. ~/hugo_sites):

theme = 'ananke'

Your first blog post¶

[isabell@moondust an_astronauts_blog]$ hugo new content content/posts/my-first-post.md
[isabell@moondust an_astronauts_blog]$ nano content/posts/my-first-post.md

Now write your first blog post:

+++
date = '2026-09-07T16:09:44+02:00'
title = 'My latest trip to the space'
+++
## Recommondation

Visit the [Uberspace](https://uberspace.de) for a joyful ride on an asteroid!

Deploying the site¶

Set the following values in your site's hugo.toml, replacing the existing baseURL entry rather than adding a second one. Replace isabell with your Uberspace username and use your site's public URL for baseURL, including the trailing slash.

baseURL = 'https://isabell.uber.space/'
hugo_cache = '/home/$USER/tmp'

Now, build a public website. Pass the document root with --destination so that the shell expands $USER; Hugo does not expand shell variables in hugo.toml.

Warning

This will delete all data in your html/ directory! Double-check for other existing projects on your asteroid!

[isabell@moondust an_astronauts_blog]$ hugo --cleanDestinationDir --destination "/var/www/virtual/$USER/html/"

Further thoughts¶

The documentation of Aneke is a useful ressource if you keep this theme (for now).

You may set up Hugo on your local machine in order to manage posts, pages and media assets in a more pleasant environment. Using hugo server, you may check the results in your web browser before a deployment to Uberspace.

Updates¶

Note

Check the update feed regularly.

Update with a single line:

[isabell@moondust ~]$ curl -fsSL "$(curl -fsSL https://api.github.com/repos/gohugoio/hugo/releases/latest | grep -o 'https://[^"]*hugo_extended_[^"]*_linux-amd64.tar.gz' | head -1)" | tar -xz -C ~/bin hugo