hugo-htmx-go-template

Make static Hugo sites dynamic with htmx and go

This is a project template combining Hugo, htmx, and an optional API server written in Go, using html/template or templ for HTML rendering.

This template in action

You can see this template in action at https://garbagespeak.com and its source code is at https://github.com/acaloiaro/garbagespeak.com

Why?

Hugo is a fantastic static site building tool, and there are few things about Hugo that can or should be improved.

The existence of this project template does not suggest that all static sites should be dynamic. If your site can be static, it should be static.

Yet there are instances in which one might want to add dynamic functionality to static Hugo sites. That is the purpose of this project template. Not to make all static sites dynamic, but to provide a simple solution to add islands of dynamic behavior to static sites.

This allows us to build fast, easily deployable HTML content, with the added ability of meeting a new class of dynamic behavior needs.

Example use cases include

• Contact forms
• Comment systems
• Up/Down vote systems
• You know ... website stuff

You shouldn't have to reach for a SaaS product to offer dynamic content on your static sites.

About

First of all, what is meant by "project template"?

This git repository is to be used as a template from which to create Hugo sites. It does not impose any constraints on how you use Hugo. It is, itself, a simple hugo project created with hugo site new .... You can run hugo serve from this project's root directory and it will behave like every other Hugo site you've developed.

So what does this template provide?

This template provides example code and simple developer tooling for running Hugo along with an optional API server, written in Go, using html/template.

What developer tooling is provided?

1. bin/develop: This utility both starts the hugo server (hugo server) and the API server (go run server.go) for development. If the user has air installed (https://github.com/cosmtrek/air), API server code will hot-reload when changes to server.go are made.
2. bin/build: This utility builds a binary of your API (server.go), with your entire Hugo site embedded within. This allows Hugo sites to be deployed as a self-contained binary.

Getting Started

Clone this project template and initialize it:

git clone git@github.com:acaloiaro/hugo-htmx-go-template.git ./my_new_site
cd my_new_site
# The theme 'ananke' is used here because it's the one used by Hugo's quickstart guide: https://gohugo.io/getting-started/quick-start/
# You can use any theme with this project template, so long as you add htmx to its included scripts: <script type="text/javascript"src="/htmx.js"></script>
# fetch-deps.sh does this automatically for the ananke theme
git clone https://github.com/theNewDynamic/gohugo-theme-ananke ./themes/ananke
bin/fetch-deps.sh
go build -o bin/develop internal/cmd/develop/main.go
go build -o bin/build internal/cmd/build/main.go
mkdir public && touch public/.empty

If you'll be using the API server, it's useful to install air to hot redeploy Go code changes when running bin/develop:

go install github.com/cosmtrek/air@latest

To make changes to templ templates (.templ files), first install templ. Using templ is optional. The goodbye world example shows templ in action.

go install github.com/a-h/templ/cmd/templ@latest

Run locally

To start the development server(s), run bin/develop

Hugo will run on its develop port at http://localhost:1313 and the API server runs on http://localhost:1314.

Example content is available at: http://localhost:1313/posts/hello-world/

bin/build can be used to build fat binaries of your Hugo site, which will be available at http://localhost:1314 after running build/server.

Changing templ templates

To use templ templates, you will need to templ installed. The air configuration watches for changes to templ files and automatically builds them.

Deploying

Hugo sites made from this template project can be deployed in two ways.

Traditional deployment

A traditional deployment is any deployment where Hugo content is deployed to an HTTP server that serves static content. Deploying Hugo content with this project template remains the same as a usual Hugo site.

However, to use the API server in production, you'll need to tell your static site content where to send HTTP requests.

Configure this in config/production/hugo.toml

If you've made your API available at https://api.example.com, add the following to hugo.toml:

[Params]
  apiBaseUrl = 'https://api.example.com'

The API server binary can be had by using bin/build to generate a fat binary, or simply compiling server.go directly: go -o build/server server.go

Fat binary deployment

Fat binary deployment is made possible by bin/build. The build/server executable contains both the API server code and Hugo static site content.

No additional configuration is necessary to deploy a fat binary. Simply copy build/server to the system that will run it.

Note: To build fat binaries for different systems/architectures than the system performing the build, use the GOOS and GOARCH to change system/architecture, e.g.

Build a fat binary for OpenBSD and AMD64 architecture

GOOS=openbsd GOARCH=amd64 bin/build