A Hugo blog starter that deploys itself and updates its own theme
A quickstart template to create a Hugo blog using hugo-theme-stack
At a glance
- What is it?
- hugo-theme-stack-starter is a template repository rather than a theme, and it is deliberately thin: a content directory, a configuration directory, assets, and a Hugo module file that pulls the Stack theme in by version. A GitHub Action deploys the site to GitHub Pages and a scheduled job keeps the theme current, so the whole thing is a working blog before you write a word.
- Who is it for?
- Adopt hugo-theme-stack-starter if you want a Hugo blog running on the Stack theme today and you are happy with GitHub Pages as the host, since the template wires up the build, the deploy action and the theme update job for you. Skip it if you need to host elsewhere without adapting the action, or if you need the theme version to move automatically, because the documentation says the Go module limitation means a new major theme release has to be applied by hand.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 151 days ago.
- What is it written in?
- Mainly Dockerfile, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 23, 2026, and from our analysis. They are not legal advice.
Editorial analysis
It is a template for a template
This is a quick start template for the Hugo theme Stack, and the distinguishing feature is stated in the second sentence. It uses the Hugo modules feature to load the theme.
That single decision shapes the whole repository. It is not a fork of the theme with a demo post in it, and it is not a theme variant. It is a starting site that pulls the theme in as a dependency, the same way a Go program pulls a module.
The consequence is that the theme is not in the repository. What is in the repository is the site: a basic theme structure and configuration, and the go.mod and go.sum files that record which version of the theme is being used. The module file is three lines of content, naming the module as the starter template repository, declaring Go 1.17, and requiring the Stack theme at version 4.0.3.
That matters for anyone reading the repository. The word template in the name refers to GitHub's template repository feature, which is why the getting started instructions begin with clicking Use this template. The result is a new repository containing the site scaffolding and nothing else, with the theme arriving at build time.
The theme itself lives at CaiJimmy/hugo-theme-stack, and the starter is at starter.stack.cai.im, with a live example of what the result looks like.
The project is MIT licensed, the last push was on 2026-05-26 and there are no GitHub releases, since the template is used through the GitHub template button rather than downloaded.
The deployment and the theme update are both handled for you
Two automation jobs are set up in the template, and they are the reason the repository is more than an empty Hugo site.
The first is the deploy. A GitHub action has been set up to deploy the theme to a public GitHub page automatically. So once you commit and push, the site goes live without you touching a build command or a hosting control panel.
The second is the theme update. There is a cron job to update the theme automatically every day. Since the theme arrives as a Go module rather than as copied files, the update is a matter of moving the module version, and the scheduled job does that for you.
Together those two jobs answer the two objections people have about starting from a template. The first is that a template goes stale, which the daily update addresses at the theme level. The second is that a template deploys but then you are on your own for the hosting, which the action addresses.
There is also a devcontainer and a .vscode directory at the top level, alongside assets/, config/ and content/, so the environment for editing the site is defined rather than assumed. The primary language of the repository is listed as Dockerfile for the same reason.
The one thing the automation does not cover is the site content, obviously. The content/ directory is where your posts go, and the config/ directory is where the site's identity is set, and both are yours from the first commit.
Six steps, and step three is the one people miss
The getting started section is a numbered list, and reading it in order avoids the two failure points people hit.
Step one is to click Use this template and create your repository as `<username>.github.io` on GitHub. The documentation allows a different repository name, but then the resulting website will be available at `https://<username>.github.io/<repository-name>` instead of the root domain, and that has to be reflected in the configuration later.
Step two is to create a GitHub codespace associated with the repository, which gives you a working environment without installing anything.
Step three is the one that is easy to skip and expensive to skip. While you are waiting for the codespace to be created, go to the Settings then Pages of your newly created repository and set Build and deployment then Source to GitHub Actions.
The reason is that GitHub Pages by default expects to build your site itself, and it does not know how to build a Hugo site. Until the source is set to GitHub Actions, the deploy workflow that the template gave you has nowhere to publish to, and the first push produces nothing.
Step four is to test the build. After the codespace is created you can test that the site is built successfully by running `hugo server` in the terminal and seeing the site in action. That is a local server with live reload, and it is the fastest loop for the editing that follows.
Step five is the configuration. The config folder holds the configuration files and you edit them to suit your needs, and the instruction is to make sure you update the `baseurl` property in `config/_default/config.toml` to your site's URL, with the example being that a repository named my-blog needs `https://<username>.github.io/my-blog/`.
Step six is to commit and push, and the GitHub action deploys the site automatically to the GitHub page associated with the repository.
There is also a video tutorial for anyone who got lost during setup, which sets up a new Hugo site using this template and deploys it to GitHub Pages.
Running it locally instead of in a codespace
The documentation covers the case where you do not want to use a GitHub codespace, and the requirement is stated in bold. You need to install Git, Go and Hugo extended locally.
The Hugo extended edition matters and is easy to miss, because some Hugo themes need it to build their stylesheets, and the error from a standard Hugo binary tends to look like a missing binary rather than a wrong edition.
Go is in the list because Hugo modules are resolved with the Go toolchain. When you run a Hugo command that touches modules, Hugo shells out to Go, so a missing Go installation shows up as a module error rather than as an obvious missing dependency.
The alternative to installing all three is the codespace, which is the route the instructions lead with, so the local path is for people who already have the toolchain or who want their own editor and preview server.
The official Hugo installation documentation is linked for the details.
For deploying somewhere other than GitHub Pages, the pointer is also the official Hugo documentation, on hosting and deploying. That is an honest signpost rather than a dead end, since the action in the repository is specific to GitHub Pages and moving to another host means writing a different build and deploy step.
The theme version is pinned, and a new major release means work
There is one maintenance caveat, and it is stated in a note directly under the update commands.
The manual theme update is two commands:
hugo mod get -u github.com/CaiJimmy/hugo-theme-stack/v4
hugo mod tidyThe first fetches the latest version of the theme module, and the second tidies the module files so go.mod and go.sum match what is actually used.
The caveat follows. This starter template has been configured with the v4 version of theme. Due to the limitation of Go module, once the v4 or up version of theme is released, you need to update the theme manually, by modifying the `config/module.toml` file.
That limitation is a Go modules behaviour rather than something Hugo imposes. A Go module version is immutable, so a new major release of the theme is a different module path rather than a new version of the same one. Moving to it means editing the module path in config/module.toml, which the daily cron job cannot do for you because it would have to rewrite a file.
So the automation has a clear boundary. Patch and minor updates within a major version arrive automatically, and a major version bump needs a manual edit. For most people that is the right trade, because a major version of a theme can carry breaking configuration changes that you would want to look at anyway.
The go.mod file in the repository shows the current state, requiring github.com/CaiJimmy/hugo-theme-stack/v4 at version 4.0.3, so the v4 path is in place and the version is a specific patch.
Where this sits against forking the theme
The realistic alternative is to fork the theme repository and copy its files into your own site, which is what people did before Hugo modules were convenient, and the comparison is instructive.
Forking gives you total control. You can change any template file, override anything, and your site has no dependency on the theme's release cycle. The cost is that you now own the merge problem. When the theme fixes a bug or updates for a new Hugo version, you have to notice, pull the change and resolve it against your modifications, and there is no upstream doing that for you.
The module approach inverts that ownership. Your repository holds only your content and configuration, the theme is a versioned dependency, and the daily job keeps it current. If the theme moves to a new major version and you do not follow, your site keeps working on the version you have.
For a blog where the content is the point and the design is a given, that is clearly the better arrangement, and it explains why the template exists as a separate repository rather than being a branch of the theme.
The compromise many people end up with is a hybrid. They use the module for the bulk of the theme and add their own overrides on top, which Hugo supports, so the customised parts live in the site repository and the rest stays upstream.
What this starter adds on top of the module mechanism is the automation. A module dependency alone leaves you running hugo and copying output somewhere. The template gives you a repository that builds and publishes itself, a scheduled theme update, and a codespace or local environment for editing, which is the difference between a starting point and a finished pipeline.
The theme structure and configuration that come with it are described as basic, and the baseurl line in step five is the one setting you are expected to change before the first deploy. Everything else is a working default.
Editorial conclusion
Adopt hugo-theme-stack-starter if you want a Hugo blog running on the Stack theme today and you are happy with GitHub Pages as the host, since the template wires up the build, the deploy action and the theme update job for you. Skip it if you need to host elsewhere without adapting the action, or if you need the theme version to move automatically, because the documentation says the Go module limitation means a new major theme release has to be applied by hand. Verify first that you name your repository as username.github.io or that you update the baseurl property to match, that you set the Pages build source to GitHub Actions before the first deploy, and that you can install Git, Go and Hugo extended locally if you want to run the site outside a codespace.
Frequently asked questions
How do I create a site from the hugo-theme-stack-starter template?
Click Use this template and create your repository as `<username>.github.io` on GitHub, create a GitHub codespace for it, and while it is being created go to Settings then Pages and set Build and deployment then Source to GitHub Actions. Once the codespace is ready you can run `hugo server` to test the build, edit the configuration in the config folder including the `baseurl` property in `config/_default/config.toml`, then commit and push and the GitHub action deploys the site.
How do I update the Hugo theme manually?
Run `hugo mod get -u github.com/CaiJimmy/hugo-theme-stack/v4` and then `hugo mod tidy`. The template is configured with the v4 version of the theme, and because of a Go module limitation, once a v4 or later major version of the theme is released you have to update manually by modifying the `config/module.toml` file.
What do I need to run this template locally instead of in a codespace?
You need to install Git, Go and Hugo extended locally, and the official Hugo installation documentation is linked for the details. Go is required because Hugo modules are resolved with the Go toolchain. Deploying to a static host other than GitHub Pages means following the official Hugo documentation on hosting and deploying, since the action in the repository targets GitHub Pages.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/caijimmy-hugo-theme-stack-starter)Was this useful?