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 an 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