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

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

After some years of manually creating`.html` source files I switch to using a
static site generator[^1]. I got used to the Markdown[^2] format and like the
idea of self-contained applications. Thus, the [Hugo](https://gohugo.io/)
framework seems to be a promising solution.

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

## Getting started

{{% steps %}}

### Installing Hugo

The [installation](https://gohugo.io/installation/) is straight forward. There's
an [ArchLinux](https://gohugo.io/installation/linux/#arch-linux) package of the
extended edition of Hugo available, which can be installed directly via pacman:

```bash
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](https://lab.uberspace.de/guide_hugo/) 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](../forgejo/).
{{< /callout >}}

### Choosing a theme

I search the [themes](https://themes.gohugo.io/) 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](https://themes.gohugo.io/themes/hextra/)
appeals to me.

### Setting up a repo

I use [Forgejo](/docs/infrastructure/forgejo/) for automatically generating the
`LICENSE`, `README.md`, and `.gitignore` files while  [creating a repository](https://forgejo.org/docs/latest/user/first-repository/#creating-a-repository)
and clone the remote repository to proceed with it locally.

```bash
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](/docs/infrastructure/forgejo/submodules/) setup in
[getting started](https://imfing.github.io/hextra/docs/getting-started/#setup-hextra-as-git-submodule):

```bash
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:

```bash
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:

```bash
hugo server --buildDrafts
```

The development server listens on port 1313 and the site can be previewed at:
[http://localhost:1313](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.

```bash
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](https://imfing.github.io/hextra/docs/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](https://en.wikipedia.org/wiki/Static_site_generator)
in the Wikipedia
[^2]: [Markdown Guide](https://www.markdownguide.org/) website