Documentation Site

The documentation is written in Markdown format to keep it portable. A website is built with the Hugo static site generator, using the Relearn theme.

Development

Build process: The Markdown and Docker Compose files are collected and converted by update-docs.py, then hugo build is executed in a Docker container, producing a container image with nginx serving the static website.

The Relearn revision is pinned in src/go.mod and its module/archive checksums are recorded in src/go.sum. Both Hugo configs use the public Go module proxy with checksum verification instead of direct GitHub Git fetching. The Docker build downloads modules in a cached layer before copying content; rendering then runs without network access and fails on warnings. Dockerfile.dockerignore keeps private host configuration, downloaded Terraform providers, virtual environments and generated content out of this build context.

Build without deploying, from the repository root:

docker build -f docs/web/Dockerfile -t local/homelab-docs:check \
  --build-arg HUGO_BASEURL=http://localhost/ .

After intentionally changing the theme pin, refresh src/go.sum using Hugo’s module tooling with the configured proxy and rebuild. Keep src/config.module.yaml and the module settings in src/config.yaml aligned so cached downloads and rendering use the same dependency configuration. Repository-authored HTML is rendered; placeholders such as <hostname> belong in backticks or code blocks.

Run task docs:deploy to build and locally deploy (using docker/tools/homelab-docs/homelab-docs.yaml) the site.

Hugo

Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again.

▶️ Getting Started With Hugo

Note - Alternatives to Hugo:

• Jekyll
• Astro

Installation

Install with APT (older Hugo version):

sudo apt install hugo

…or install a specific release from Github:

$ wget https://github.com/gohugoio/hugo/releases/download/v0.121.1/hugo_0.121.1_linux-amd64.tar.gz

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

…or use Docker: Hugo Docker Images
Use docker pull hugomods/hugo:exts to update Hugo.

Theme

• Hugo Relearn Theme
• https://mcshelby.github.io/hugo-theme-relearn/basics/installation/index.html
• hugo-theme-relearn/exampleSite at main · McShelby/hugo-theme-relearn

Clone repo: git clone https://github.com/McShelby/hugo-theme-relearn.git --depth 1

Create and serve a new website

Initialize the new site:

hugo new site <site_name> -f yaml

Output:

Congratulations! Your new Hugo site is created in <.../site_name>.

Just a few more steps and you're ready to go:

1. Download a theme into the same-named folder.
   Choose a theme from https://themes.gohugo.io/ or
   create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
   with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".

Visit https://gohugo.io/ for quickstart guide and full documentation.

Install the theme:

cd <site_name>
hugo mod get -u https://github.com/McShelby/hugo-theme-relearn.git

Run the webserver, allowing remote HTTP access:

hugo serve --bind=0.0.0.0 --baseURL=http://0.0.0.0:1313