# Gokarna is a deliberately small Hugo theme with a long contributor list

> Gokarna is a Hugo theme with a focus on minimalism and simplicity, and it is opinionated enough to say so. It ships light and dark modes, seven translations, math typesetting and syntax highlighting, and it reports a Google Lighthouse score of 100. The installation is one git submodule command.

**gokarna-theme/gokarna-hugo** — A minimal opinionated theme for Hugo

- Repository: https://github.com/gokarna-theme/gokarna-hugo
- Website: https://gokarna-hugo.netlify.app
- Stars: 544 · Forks: 173
- Language: HTML
- License: GPL-3.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/gokarna-theme-gokarna-hugo

## Opinionated, and named after a beach town

The theme describes itself as an opinionated theme with a focus on minimalism and simplicity, and that word opinionated is the one to take seriously.

A Hugo theme is, in principle, a set of templates and assets you can adjust. An opinionated one is a set of decisions made for you: the type scale, the spacing, the colour palette, the shape of a post page. The value of that is that a new site looks considered immediately, and the cost is that changing it means overriding things.

The name comes with a story. The theme is inspired by, and accordingly named after, Gokarna, a small and peaceful beach town on the west coast of India. That is a small, pleasant piece of design rationale, and it says what the aesthetic is aiming at without having to argue about it.

The people behind it are listed up front. The authors are Yash Mehrotra and Avijit Gupta, and then there is a major contributors list with five names: James Davidson, David Kröll, Mansoor Barri, Oliver Freyermuth and JulietEchoDelta.

That list is longer than the author list, and it is a fair signal about how a theme like this actually gets built. A theme is a small, self-contained thing that lots of people want and few people maintain, and the contributors are usually people who came along with a specific pull request: a translation, a fix for a template edge case, a feature.

There is a live demo at gokarna-hugo.netlify.app, and the theme itself is HTML and Hugo with the primary language listed as HTML, GPL-3.0 licensed, with the last push on 2026-10-05.

## The feature list, and what each entry actually involves

The features section is a bulleted list, and it is worth reading the entries closely because several of them represent more work than they look.

Light and dark modes is the first, and for a Hugo theme this is a substantial feature rather than a toggle. The screenshots in the documentation are shown as light and dark pairs for the home page, the post page and the list page, which tells you the dark variant is designed rather than a filter.

Icons come in two sets, Feather and Simple, and the Simple set is documented separately as icons on the homepage. So the theme ships two icon systems and lets you pick, which is a reasonable answer to the fact that icon style is a matter of taste that no default can settle.

KaTeX math typesetting is there, and that means the theme pulls in a typesetting library and gets the rendering and the styling right for it. That is a real integration rather than a claim.

Syntax highlighting is included, and it is listed alongside a configuration entry in the customization section, where you can choose the syntax highlighting colour scheme. So the theme ships with a default scheme and lets you change it, which is the right way round because a default that cannot be changed is a default you have to override in the templates.

Custom HTML, JavaScript and CSS is supported, and the documentation explains the mechanism: use the head and footer elements to add arbitrary HTML, JavaScript and CSS. That is a Hugo concept, where you can add your own blocks to the generated page, and it is how a theme stays out of the way of things like analytics snippets or a web font you prefer.

The configurable table of contents is a feature in its own right, because the default table of contents in many themes is fixed and the only way to change it is to write a template.

Then there are the translations, the Google Lato fonts, and an auto-generated RSS feed. The list ends with And more..., which is the honest way to signal that the documentation is the real feature list.

## Translations, and seven languages

Seven languages ship with the theme: Spanish and Catalan under one label, German, French, Polish, Brazilian Portuguese, Russian and Traditional Chinese.

That is a substantial amount of work for a theme, and it is worth understanding how the translations are structured, because the mechanism is Hugo's rather than the theme's.

To use one, you change the locale in the Hugo configuration to the value corresponding to that translation, and the strings come from the i18n directory in the repository. That is standard Hugo practice, where the theme ships a set of translation tables and the site configuration selects one.

The documentation also tells you what to do if your language is missing, and the answer is to make Gokarna multilingual by creating a translation table, with a link to the Hugo documentation on simple translations.

That is the right guidance, because it hands the work to the person who knows the language rather than to the maintainers. A translation table is a set of key and value pairs, and the person who reads the language natively can produce a correct one without understanding Go templates at all.

The theme repository has an i18n/ directory at the top level, which is where those tables live, and the documentation links directly to it so a translator can see the existing ones as a model.

It is worth noting what is not here. The list does not include Japanese or Simplified Chinese, and it includes Catalan, which is much less common. That is a reasonable sign that the translations came from the people who needed them rather than from a coverage plan, which is the healthier way for them to arrive.

## Installation, customization and the theme structure

The installation is one command, and it is the submodule route:

```sh
git submodule add https://github.com/gokarna-theme/gokarna-hugo.git themes/gokarna
```

That places the theme in the themes/gokarna directory of the site, and the documentation points at the basics page for the remaining steps.

The theme structure follows the Hugo convention, which is worth knowing if you want to extend it. There is a layouts/ directory for the templates, an assets/ directory for the stylesheets and scripts that Hugo processes, a static/ directory for files copied as they are, and an i18n/ directory for the translation tables. There is an archetypes/ directory, which holds the front matter templates Hugo uses when you create new content, and an exampleSite/ directory, which is the demonstration site.

The exampleSite is the most useful thing in that list for a new user. It is a complete, working site configured against the theme, so you can look at a real configuration file rather than assembling one from the documentation.

The customization section links to two documentation pages, one for basics and one for advanced, and then lists the kind of things you can change without touching a template. Adding an avatar and changing its size. Adding text to the footer. Changing how dates are formatted on posts. Choosing the syntax highlighting colour scheme. Composing navigation menu items. Defining the site's accent colour, which changes the colour of hyperlinks including icons. Displaying recent or popular posts on the home page. And injecting custom HTML into the head and footer elements.

The accent colour entry is the one that shows the design philosophy. One configuration value changes the link colour and the icons together, which means the palette stays coherent without the user having to pick a matching colour for each element. That is the opinionated part working in your favour.

The theme.toml file at the root is the metadata Hugo reads to know what the theme is, and the netlify.toml at the root configures the deployment of the demo site.

## Screenshots, performance and the automation around them

The documentation shows a lot of screenshots, and there is a script at the repository root called screenshot.py with a requirements file listing selenium, pillow and soldier.

So the images in the documentation are produced by automation rather than captured by hand. That is a detail with real consequences for a theme: every screenshot in the documentation shows the current design, and if a change to the templates alters the layout, the regenerated screenshots show it rather than the documentation quietly going stale.

The dependency list tells you the shape of that. Selenium drives a browser, which is what you need to capture a page that only exists after client-side rendering. Pillow handles the image work. The third entry, soldier, is a further dependency of the same script.

The performance section is the other piece of the story, and it is a single claim. The Google Lighthouse score is 100%, with a screenshot of the score to back it up.

A Lighthouse score of 100 is not a small claim for a static site generator theme, and it is worth thinking about why it is achievable here. Lighthouse rewards small payloads, no render blocking, good accessibility signals and good SEO signals. A Hugo theme that ships one font family, no JavaScript framework, minimal CSS and a static RSS feed has a good starting point, and the theme's minimalism and its performance claim are really the same fact seen from two sides.

The container file at the root is for building the site in a container, and the Netlify configuration handles the demo deployment. Neither is unusual for a Hugo theme, but having both means you can run the site the same way locally as it runs in the demo.

The.gitignore is there for the usual Hugo reasons, since a Hugo site accumulates public/ and resources/ directories that are generated rather than authored.

## Where this fits against the other Hugo themes

Hugo has a lot of themes, and the useful comparison is not a feature checklist but a question of what you are optimising for.

If you want a personal blog that looks finished in an afternoon, a theme like this is a good fit. The decisions are made, the dark mode works, the typography is settled, and the amount of configuration before you publish your first post is close to zero.

If you want a distinctive site, the same decisions are a liability. Every opinionated choice is something you now have to override, and overriding a theme is more work than the theme saved you. In that case a deliberately unopinionated theme, or a from-scratch Hugo site, is the better starting point.

The middle case is a site that needs specific things: math, syntax highlighting, several languages, a table of contents. Gokarna has all of those working, which is where the value of an opinionated theme lies, because those are the features most likely to be half-done in a from-scratch build.

There is also the question of maintenance, and here the information in the repository is useful. The last push was on 2026-10-05, the theme has a named list of authors and major contributors rather than a single maintainer, and the repository has no GitHub releases.

The theme is GPL-3.0 licensed, which is worth noting for anyone considering a fork for a commercial site, since GPL obligations apply to a modified distributed version. For a personal or company blog that publishes its source, that is rarely an issue.

The one thing to check before committing is the Hugo version. A theme with this much in it, particularly the KaTeX integration and the icon systems, has a minimum Hugo version. Installing an older Hugo is the most common reason a theme appears to be broken on first try.

## Conclusion

Adopt Gokarna if you want a Hugo site with a restrained look, working dark mode and no configuration work, since the theme makes all of those decisions for you. Skip it if you want a theme you can reshape heavily, because the point of it is that it is opinionated, and if you need a language outside the seven it ships with. Verify first which translations you need, that your Hugo configuration sets the locale to match one of them, and how you want the site deployed, since the repository carries both a Containerfile and a Netlify configuration for the demo.

## FAQ

### What is Gokarna and what does the theme include?

It is an opinionated Hugo theme with a focus on minimalism and simplicity, named after a small beach town on the west coast of India. It includes light and dark modes, Feather and Simple icon sets, KaTeX math typesetting, syntax highlighting with a configurable colour scheme, a configurable table of contents, support for custom HTML, JavaScript and CSS through the head and footer elements, Google Lato fonts, an auto-generated RSS feed and seven translations.

### How do I install the Gokarna Hugo theme?

Follow the theme documentation basics page, and add the theme as a git submodule with `git submodule add https://github.com/gokarna-theme/gokarna-hugo.git themes/gokarna`. The repository includes an exampleSite directory with a complete working site, so you can copy its configuration rather than assembling one from scratch. The theme is licensed under GPLv3.

### Which languages does Gokarna ship and how do I add another?

It ships Spanish and Catalan, German, French, Polish, Brazilian Portuguese, Russian and Traditional Chinese, selected by changing the locale in the Hugo configuration. To add a language, create a translation table following the Hugo documentation on simple translations; the existing tables are in the i18n directory of the repository and serve as a model.

## Sources

- [gokarna-theme/gokarna-hugo on GitHub](https://github.com/gokarna-theme/gokarna-hugo)
- [Issues](https://github.com/gokarna-theme/gokarna-hugo/issues)
- [License: GPL-3.0](https://github.com/gokarna-theme/gokarna-hugo/blob/main/LICENSE)
- [Project website](https://gokarna-hugo.netlify.app)
- [README](https://github.com/gokarna-theme/gokarna-hugo/blob/main/README.md)

---

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