Hugo HTMX Go Template is an open-source project starter that pairs Hugo's static site generator with htmx for interactive HTML fragments and an optional Go API server. It takes a Hugo site as input and produces either a statically deployable site or a self-contained Go binary with the site embedded, running on localhost ports 1313 (Hugo) and 1314 (API) in development. The template is maintained by acaloiaro and can be seen in production at garbagespeak.com.
What is Hugo HTMX Go Template?
Hugo HTMX Go Template is a git repository template that combines Hugo, htmx, and a Go API server so static sites can gain islands of dynamic behavior without losing the speed and deployability of static HTML. The API server renders HTML using either Go's html/template package or templ, and the repository includes example code plus developer tooling for running both servers together.
Key features
- bin/develop — starts the Hugo development server and the Go API server concurrently; if air is installed, API server code hot-reloads on changes.
- bin/build — compiles server.go into a single binary with the entire Hugo site embedded, enabling fat binary deployment.
- htmx integration — ships with htmx loaded so static pages can request dynamic HTML fragments from the API server without a front-end JavaScript framework.
- templ or html/template rendering — the API server can render HTML with Go's standard html/template or with a-h/templ templates; the "goodbye world" example demonstrates templ.
- Multiple deployment modes — deploy via traditional static hosting with an apiBaseUrl setting in config/production/hugo.toml, or copy a fat binary to any machine; cross-compilation works with GOOS and GOARCH environment variables.
- Theme agnostic — works with any Hugo theme as long as the htmx script is included; the quickstart clones the Ananke theme and fetch-deps.sh adds the script automatically.
Who should use Hugo HTMX Go Template?
- Hugo developers building marketing sites or blogs that need one or two dynamic widgets, such as a working contact form, without moving to a full SPA.
- Go programmers who want a small API server embedded in a static site and prefer Go templates or templ over a separate Node.js backend.
- Indie webmasters who want to avoid SaaS services for comments, voting, or forms and instead self-host a tiny API alongside static content.
What can you do with Hugo HTMX Go Template?
- Contact forms: add an htmx-enabled form on a Hugo page that POSTs to the Go API and returns a success message without a page reload.
- Comment systems: let visitors submit and load comments through API endpoints while the rest of the site remains pre-built static HTML.
- Up/down voting: implement lightweight vote buttons on pages or blog posts, with the vote state stored by the Go server.
How does it work?
The setup is a git clone followed by a few commands. You clone the template, fetch the Ananke theme for the quickstart, run bin/fetch-deps.sh, then build the two helper binaries (bin/develop and bin/build). Running bin/develop starts the Hugo server on port 1313 and the API server on port 1314. To build for production, bin/build produces build/server, a fat binary you can run directly.
FAQ
Can I use this with my existing Hugo theme?
Yes. The template does not constrain your Hugo usage; you only need to include htmx in your theme's scripts with a script tag pointing to /htmx.js. The provided fetch-deps.sh does this automatically for the Ananke theme.
Do I need to use templ?
No. The API server can render HTML with Go's html/template package, which requires no extra tools. templ is optional, and you only need to install the templ generator if you edit the .templ example files.
What ports does the development environment use?
Hugo runs on localhost:1313 and the Go API server runs on localhost:1314. Example dynamic content is available at localhost:1313/posts/hello-world/.
Can I deploy this as a traditional static site?
Yes. Build the Hugo site as you normally would, but you must also run the API server somewhere and configure its base URL via apiBaseUrl under the Params section of config/production/hugo.toml. Alternatively, use bin/build for a fat-binary deployment that needs no separate static host.
Has the repository moved?
Yes. As the README's notice explains, the project moved from GitHub to code.adriano.fyi/me/hugo-htmx-go-template, with garbagespeak.com and its source at github.com/acaloiaro/garbagespeak.com still serving as live examples.
