hugo-htmx-go-template

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

Why?

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

The existence of this project template should in no way suggest that static sites should be dynamic. If your site can be static, it should be static.

Yet there are instances in which one might need 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, but with the added ability of meeting a new class dynamic behavior needs.

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), it will hot reload the API server code when changes to server.go are made.
2. bin/build: This utility builds a binary with your entire Hugo site embedded within. Note: this is only to be used to deploy Hugo sites 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 if you want auto-rebuild functionality when running bin/develop:

go install github.com/cosmtrek/air@latest

Run

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 using Hugo/htmx/go api is available at: http://localhost:1313/posts/hello-world/

You can also use bin/build to build a fat binary of your Hugo site, which will be available at http://localhost:1314 after running build/server.

Deploy

Hugo sites made from this template 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