# hugo-coder: a minimalist Hugo theme you install as a git submodule

> A blog theme for Hugo with a checked-in example site, a Makefile for previewing it, and a release history that has moved three times in eight years.

**luizdepra/hugo-coder** — A minimalist blog theme for hugo.

- Repository: https://github.com/luizdepra/hugo-coder
- Stars: 3,115 · Forks: 1,146
- Language: HTML
- License: MIT
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/luizdepra-hugo-coder

## What the repository actually contains

The README calls it a simple and clean blog theme for Hugo, and the tree backs that up without adding anything surprising. `layouts/` holds the templates, `assets/` the files the asset pipeline processes, `static/` the files Hugo copies through untouched, `i18n/` the translation strings, `archetypes/` the content templates that `hugo new` reads, `images/` the logo and screenshot the README embeds, `docs/` a configuration guide, and `exampleSite/` a complete Hugo site wired to the theme. `theme.toml` is the metadata file the Hugo themes site reads, and `netlify.toml` carries the deploy settings for the live demo linked as hugo-coder.netlify.app.

Two entries are worth stopping on because they are not what you expect in a theme. `go.mod` is present and declares a Go module at `github.com/luizdepra/hugo-coder` requiring Go 1.16. That file is what allows the theme to be consumed through Hugo Modules rather than only as a git submodule, which is the more modern path even though the README only walks through the submodule one. The other is `resources/`, a Hugo asset cache that has been committed to the repository rather than left to be generated. The `release` target in the Makefile exists to rebuild that directory from the example site, which tells you the committed cache is treated as a release artifact rather than an accident.

## Adding the theme as a submodule and pointing Hugo at it

The quick start is three numbered steps and the first one is the whole install. There is no package manager, no npm dependency and no init command; the theme is a git repository placed at a path Hugo already looks in:

```bash
git submodule add https://github.com/luizdepra/hugo-coder.git themes/hugo-coder
```

That path is not arbitrary. Hugo resolves a theme name by looking under `themes/`, so the directory name `hugo-coder` becomes the name you pass to `theme =` in your site configuration. Getting the two out of step is the most common way a theme install fails silently, and it fails silently because Hugo will build your site without the theme rather than error out.

Step two is configuration, and the README hands you three references rather than a snippet: a minimal configuration, a full explanation of every option in `docs/configurations.md`, and the `hugo.toml` inside `exampleSite` as a working reference. The `exampleSite` copy is the more useful of the three for most people, because it is a config that has actually been run.

Step three is `hugo server`, which the README says serves the result at `http://localhost:1313/`. That port is Hugo's default rather than something the theme sets, which is worth knowing before you assume a theme change moved it.

## Building the example site without touching your own

The Makefile is four lines of real logic and it exists so you can run the theme the way its author runs it. `HUGO_BIN` is set to `hugo`, and the `--themesDir` and `--source` flags are the important part, because they point Hugo at the parent directory and at `exampleSite` rather than at the repository root:

```makefile
HUGO_BIN=hugo

build:
	$(HUGO_BIN) --themesDir=../.. --source=exampleSite
```

That combination works because the repository is a theme and not a site. Hugo expects `themes/` to sit beside the site, and `--themesDir=../..` fakes that relationship while `--source=exampleSite` says which directory is the site. The `demo` target adds `server -D` and a network bind:

```makefile
demo:
	$(HUGO_BIN) server -D --themesDir=../.. --source=exampleSite --bind 0.0.0.0
```

`--bind 0.0.0.0` is the one line here that deserves a second look before you paste it. It makes the preview server listen on every interface rather than loopback, which is what you want when previewing from another machine or a phone on the same network, and is not what you want on a shared or public host. The `release` target then deletes `./resources` and copies `exampleSite/resources` over it, so the committed asset cache is refreshed from a real build instead of by hand.

Running `make demo` from a clean checkout is also the fastest way to answer the question the README leaves open, which is what all the configuration options actually do. The example site already uses them.

## Release history: three tags in eight years

The tag list is short enough to state exactly. `v1.0` shipped on 2018-08-21, `v1.1` on 2021-11-10, and `v1.2` on 2026-02-23. The gaps are three years and then four, which tells you this is a project whose maintainer treats it as finished rather than as a product with a roadmap. There is no changelog in the tree, no `CHANGELOG.md`, and the README says nothing about what changed between tags.

That silence matters more for a theme than it would for a library, because Hugo itself moves. A theme is a set of templates and partials that call Hugo functions, and the surface of those functions grows between Hugo releases. A theme that tags rarely is not necessarily abandoned, but it is not tracking Hugo's own compatibility either, and nothing in the repository will tell you which Hugo version `v1.2` was tested against.

The last push was on 2026-06-18, which is recent enough that work is still landing. Those commits have not produced a tag. For a reader deciding whether to depend on this theme, that combination, pushes without tags, is the thing to weigh: the fixes are in `main`, and pinning to `v1.2` means pinning to February.

## README links and the default branch do not agree

Two small inconsistencies are worth naming, because both send you to a URL that does not resolve. The default branch is `main`, but every README link to the theme's own files is written against `master`. That includes the MIT license badge, the license paragraph, and the link to `exampleSite/hugo.toml`, which all use `/blob/master/` paths. The installation snippet uses `main`-era URLs because it clones the repository rather than pointing at a file, which is why the quick start works and the badges do not.

The same split shows up in the license itself. The badge points at `LICENSE.txt` and the license section points at `LICENSE.md`, while the tree contains a single `LICENSE.md`. So one of the two paths is stale, and the version that exists is the `.md` one.

Neither of these is a reason to avoid the theme. Both are cheap to work around: clone the repository and read the files locally, or point at `main` explicitly when you need to send someone a permalink. It is worth knowing they exist, because a broken permalink in a README is the kind of thing that makes a maintained project look abandoned when it is not.

## Where hugo-coder sits against the other Hugo themes

Hugo's theme directory is full of academic and portfolio themes, and the search terms people use for this project return names like Blowfish and the academic themes rather than hugo-coder itself. That is a reasonable picture of where it sits: it is a small, opinionated personal blog theme with a working example site, not a documentation or publishing platform.

The difference in approach from a heavier theme is mostly what is absent. There is no menu system beyond Hugo's own, no taxonomy configuration beyond what `hugo.toml` exposes, no bundled JavaScript framework, and no build step outside Hugo. In exchange you get templates you can read, an `i18n/` directory if you need more than one language, and an MIT license that lets you fork it without asking.

The practical comparison is with building the theme yourself. Hugo's default templates get you a site in an afternoon, and a theme gets you a site that looks designed in an afternoon. What hugo-coder costs is the fork decision: once you start editing `layouts/`, you own the updates, and the four-year gap between `v1.1` and `v1.2` is the best available signal about how much upstream work there will be to merge.

## Conclusion

hugo-coder is a good fit if you want a single author blog or small site with no database, no build pipeline beyond Hugo itself, and a layout you can read in an afternoon. The example site and the docs folder mean you can see a working configuration before writing any of your own, and the Makefile gives you a one-command preview of exactly what the theme author ships. What the repository does not give you is a sense of release cadence: three tags across eight years, and a default branch of main while the README links still point at master. Start by cloning the example site, run the demo target, and read docs/configurations.md before deciding whether the theme.toml metadata and the checked-in resources directory matter for your build.

## FAQ

### How do I install the hugo-coder theme into an existing Hugo site?

Add the repository as a git submodule at themes/hugo-coder, so the directory name matches the theme name Hugo looks for. Then set that name in your site configuration and run hugo server. The repository also ships a go.mod, so Hugo Modules is a second supported path even though the README only documents the submodule.

### Does hugo-coder work with Hugo Modules or only with git submodules?

Both paths are available. The go.mod at the repository root declares the module as github.com/luizdepra/hugo-coder, which is what Hugo Modules requires. The README quick start only walks through git submodule add into themes/hugo-coder, so the Modules route is available from the repository layout without being documented step by step there.

### How can I preview hugo-coder before setting up my own site?

Run the demo target in the repository's Makefile, which starts Hugo against the bundled exampleSite with --themesDir=../.. and --source=exampleSite. Be aware it also passes --bind 0.0.0.0, so the preview server listens on every network interface rather than only loopback.

### How often is the hugo-coder theme released?

Rarely. The repository has three tags: v1.0 on 2018-08-21, v1.1 on 2021-11-10, and v1.2 on 2026-02-23. The last push was on 2026-06-18, so changes are still landing on the default branch without producing a new tag, and pinning to v1.2 pins you to February.

## Sources

- [Issues](https://github.com/luizdepra/hugo-coder/issues)
- [License: MIT](https://github.com/luizdepra/hugo-coder/blob/main/LICENSE)
- [luizdepra/hugo-coder on GitHub](https://github.com/luizdepra/hugo-coder)
- [README](https://github.com/luizdepra/hugo-coder/blob/main/README.md)
- [Releases](https://github.com/luizdepra/hugo-coder/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/luizdepra-hugo-coder