Website/content/docs/infrastructure/hugo/_index.md

title	date	weight
Hugo	2024-02-04T17:41:46+01:00	3

After some years of manually creating.html source files I switch to using a static site generator¹. I got used to the Markdown² format and like the idea of self-contained applications. Thus, the Hugo framework seems to be a promising solution.

{{< figure src="img/hugo-logo-wide.svg" width="25%" >}}

Getting started

{{% steps %}}

Installing Hugo

The installation is straight forward. There's an ArchLinux package of the extended edition of Hugo available, which can be installed directly via pacman:

sudo pacman -S hugo

Afterwards I verify the installation using the hugo version command. For the automated building Hugo also needs to be installed on Uberspace. I refer to the lab guide until Create first website and skip the rest of it to proceed with the local installation.

{{< callout type="info" >}} The Hugo installation on Uberspace is only used for live site building, which is configured later via Forgejo. {{< /callout >}}

Choosing a theme

I search the themes list for a minimalistic yet powerful theme featuring a dark mode and shortcodes so I don't have to reinvent the wheel and existing content can be migrated pretty easily. Some of themes provide a demo and in the end Hextra appeals to me.

Setting up a repo

I use Forgejo for automatically generating the LICENSE, README.md, and .gitignore files while creating a repository and clone the remote repository to proceed with it locally.

git clone https://dri.ven.uber.space/thisven/Website

Configuring a site

Though the Hextra theme documentation recommends installing it as a Hugo module I prefer a Git submodule setup in getting started:

hugo new site --force Website --format=yaml
cd Website
git submodule add https://github.com/imfing/hextra.git themes/hextra
echo "theme: hextra" >> hugo.yaml

Remark: The --force Option of the hugo new site command is required to use the already initialized directory cloned from the remote origin before.

Creating content

I create a home and docs content page:

hugo new content/_index.md
hugo new content/docs/_index.md

and run the development server locally while editing the previous files in a text editor to write the page bodys:

hugo server --buildDrafts

The development server listens on port 1313 and the site can be previewed at: http://localhost:1313

Committing changes

Though there are adaptions necessary, it may be the time to commit my first efforts and push them to the remote origin to get usd to frequent committing.

git add .
git commit -m "Initialize new hugo site"
git push

{{< callout type="warning" >}} Remember to frequently use these commands after applying changes to keep the remote repository up to date and in sync with your local copy. {{< /callout >}}

Customizing the site

The guide in the documentation of the Hextra theme expands on several features. Below are some configurations and quirks that I found useful.

{{% /steps %}}

Customizations

{{< cards >}} {{< card link="archetypes" title="Archetypes" icon="book-open" >}} {{< card link="custom-css" title="custom.css" icon="code" >}} {{< card link="shortcodes" title="Shortcodes" icon="collection" >}} {{< /cards >}}

Resources

Repository: https://dri.ven.uber.space/thisven/Website

---

1. Static site generator in the Wikipedia ↩︎

2. Markdown Guide website ↩︎