# toha: a Hugo theme for a personal portfolio with 23 languages

> Toha is an MIT-licensed Hugo theme for personal portfolios, with a minimalist responsive design, shortcodes, analytics and comment integrations, and 23 translations. It is installed as a Hugo module, and its author says plainly that he is not a web developer and wrote it for his own needs.

**hugo-themes/toha** — A Hugo theme for personal portfolio

- Repository: https://github.com/hugo-themes/toha
- Website: https://toha-preview.hugo-themes.com
- Stars: 1,252 · Forks: 720
- Language: HTML
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/hugo-themes-toha

## A personal site theme, not a blog theme

Toha is a Hugo theme for a personal portfolio with minimalist design and responsiveness, and the emphasis on personal shows in the feature list. There is an experience timeline, an achievement gallery, carefully designed cards, and a sidebar to categorize posts. There is no mention of documentation layouts, taxonomy-driven knowledge bases or a documentation sidebar, which is the clearest signal of what this theme is for.

The primary language of the repository is HTML, and the tree reflects how a Hugo theme is actually built: `layouts/` holds the templates, `assets/` the SCSS and JavaScript sources, `static/` the files copied verbatim, `i18n/` the translation files, `data/` the data files, `content/` the site's own content, and `archetypes/` the front matter templates for new content.

There is also a `theme.toml`, which is the metadata file that makes the theme installable from the Hugo themes directory, and an `exampleSite/` folder holding a working example configuration for running the theme locally.

Two things in the tree are worth a second look. `mise.toml` and the README's mention of jdx/mise point at how the project itself is developed and run, and `AGENTS.md` suggests the repository is set up for automated contribution tooling. The theme ships with a Netlify configuration in `netlify.toml`, and the README carries a Netlify deploy status badge for the site named toha.

## 23 translations, and how to add more

The translation list is the longest single feature of the project, and it is worth reading as a set rather than a boast. The available languages are English, Bengali, French, Indonesian, German, Spanish, Simplified Chinese, Traditional Chinese, Hindi, Italian, Japanese, Korean, Russian, Finnish, Vietnamese, Azerbaijan, Turkish, Arabic, European Portuguese, Catalan, Brazilian Portuguese, Dutch and Hebrew.

The important caveat is that the README does not claim these are all equally complete, and it points to two resources for adding more. One is a translation guide on the project documentation site, and the other is the example site, which the README tells you to follow for the data and post format. That second pointer is the practical part: a translation needs more than a strings file, since the example site shows the data shape that the layouts expect.

Hugo's internationalisation system is what makes this cheap, with the `i18n/` directory holding the translation files and each key resolved per language. For a theme author, the value of 23 existing translations is that a new site in one of those languages starts with working navigation strings, footer text and date formats rather than English placeholders.

The number also tells you something about the user base, since the set spans South and Southeast Asia, Europe, East Asia and the Middle East, and the presence of both Simplified and Traditional Chinese, both Brazilian and European Portuguese, and Korean alongside Japanese suggests a genuinely international user base rather than a token translation effort.

## Analytics and comments without a build-in plugin system

The integrations list is where a personal theme earns its keep, and it is split into two groups.

For analytics, the theme supports GoatCounter, counter.dev, Google Analytics, Matomo and Piwik, and Umami. That range is deliberate: two of them are cookie-free and self-hostable, one is a hosted service with a simple script tag, one is the enterprise incumbent, and one is a long-standing self-hosted tracker. A theme that picked only Google Analytics would rule out a whole set of privacy-conscious users, and this one does not.

For comments there are four options: Disqus, Valine, Utterances and Giscus. The two at the end of that list are worth distinguishing. Utterances stores comments in a GitHub issue on your repository, which means no separate comment service to run and no database. Giscus works the same way but on a discussion rather than an issue. Valine is the option that stores comments in the cloud rather than in GitHub, and Disqus is the commercial incumbent in the space.

None of this is a plugin architecture. The theme ships with these integrations built in, which means you pick one of each and configure it, rather than installing a plugin per analytics or comment provider. That is a simpler model and also a less flexible one, and it explains the presence of `package.json` and `package-lock.json` in the tree, since the front-end assets are assembled with Node tooling rather than left to Hugo's asset pipeline alone.

## Shortcodes for the layout blocks a portfolio needs

Toha provides shortcodes, which is Hugo's mechanism for embedding richer content in Markdown without raw HTML. The list is small and each one covers a layout element a personal site actually needs: Alert, Image, Split, Vertical Space, Video and Mermaid.

Split is the one that matters most for a portfolio, since a two-column block with an image beside text is the standard shape for a project entry or an about section. Image gives control over how figures are presented, Video handles embedding media, Vertical Space exists purely for layout rhythm, and Alert produces callout boxes.

Mermaid is the one that dates the theme. Diagram rendering has moved from an exotic feature to a default expectation, and having it as a built-in shortcode means a developer can put a flowchart in a post without adding a render step to the build. The shortcode documentation lives on the project documentation site, with the Mermaid example linked to a page on the example site.

Worth noting is what is not in the list. There is no carousel, no gallery shortcode, no icon shortcode and no tab shortcode. The theme leans on the achievement gallery as a section rather than as a shortcode, which tells you the gallery is a curated list of entries in the site data rather than something embedded in posts.

## Installing it as a Hugo module, in five commands

The easiest route is to fork the toha-example-site repository and change the configuration, and the README recommends that for good reason, since a working site comes with content and data already in the right shape. Starting from scratch takes a few more steps.

First, initialize Hugo modules in your repository, which creates a `go.mod` file:

```bash
hugo mod init github.com/<your username>/<your repo name>
```

Then add a module section to your `hugo.yaml`:

```yaml
# Use Hugo modules to add theme
module:
  imports:
    - path: github.com/hugo-toha/toha/v4
```

The module path in the repository's own `go.mod` is `github.com/hugo-toha/toha/v4`, so the import path has to match it. Then load the theme as a module:

```bash
hugo mod tidy
```

Running the site locally takes two more steps. Generate the Node dependency configuration, which creates a `package.json`:

```bash
hugo mod npm pack
```

Install the dependencies with `npm install`, then start the server:

```bash
hugo server -w
```

On first run you get the default parameters, which look like the example site but with no sections on the homepage, because the sections have not been configured yet. The requirements are Hugo 0.163.0 extended or higher, Go 1.19 or higher for Hugo modules, and Node 18.x with npm 8.x or later. Note that the `go.mod` in the repository declares `go 1.21`, which is above the stated minimum.

## The author's own caveat, and what the dependency list implies

The most honest paragraph in the README is the one about the author. He writes that he is not a web developer, that he created the theme for his personal needs, that it is reasonable to have some flaws in the codes, and that issues and pull requests acknowledging the problems are welcome. He asks contributors to keep it simple, keep it consistent with the design, use as few dependencies as possible, and have patience.

That framing is worth carrying into an evaluation, because it predicts where the rough edges are. A theme built for one person's site will be opinionated about layout, and a small project will have uneven translation coverage and occasional rough code.

The dependency list bears this out in an interesting way. The `package.json` declares an empty `dependencies` object and puts everything in `devDependencies`, with the front-end libraries listed as `project` in the comments section, which is Hugo's module mechanism resolving them through `package.hugo.json` rather than a direct npm install. The set itself is a curated one: Bootstrap 5, Font Awesome and feather-icons for icons, KaTeX for maths, highlight.js and mark.js for code and text highlighting, Mermaid for diagrams, Plyr for media, filterizr for the gallery filtering, Fuse.js for the fuzzy search, include-media for responsive media, and typeit for the typewriter effect on the landing page.

That is a lot of JavaScript for a minimalist theme, and it is the real cost of the design. The theme works out of the box with the gallery, the search and the animated hero, and the price is a page weight that a hand-rolled portfolio would not pay. The author's own principle, as few dependencies as possible, is the one the shipped set most visibly departs from.

## Conclusion

toha fits a developer who wants a polished personal site with a portfolio layout, a CV timeline and a working multi-language setup without designing a theme, and who is comfortable with Hugo modules and a Node build step. It does not fit someone who needs a corporate blog, a documentation site or a headless CMS, because the homepage is built around personal sections. Before adopting it, fork toha-example-site rather than starting from scratch, run `hugo server -w` to see the default homepage, and check the i18n directory for the languages you need, since the translation list is long but the quality of each is another matter.

## FAQ

### What is the toha Hugo theme?

Toha is a Hugo theme for a personal portfolio with minimalist design and responsiveness, offering an experience timeline, an achievement gallery, a post categorising sidebar, shortcodes, and 23 translations. It is MIT licensed and works as a Hugo module.

### How do I install the toha theme?

Run `hugo mod init github.com/<your username>/<your repo name>`, add the module import `github.com/hugo-toha/toha/v4` to your hugo.yaml, then run `hugo mod tidy`. For a local build, run `hugo mod npm pack`, `npm install` and `hugo server -w`. Forking toha-example-site is the easier route.

### What versions does toha require?

Hugo version 0.163.0 extended or higher, Go language 1.19 or higher for Hugo modules, and Node version v18.x or later with npm 8.x or later. The repository's own go.mod declares go 1.21.

### Which analytics and comment services does toha support?

Analytics support covers GoatCounter, counter.dev, Google Analytics, Matomo and Piwik, and Umami. Comment support covers Disqus, Valine, Utterances and Giscus, with the last two storing comments in a GitHub issue or discussion.

### What shortcodes does toha provide?

The shortcodes are Alert, Image, Split, Vertical Space, Video and Mermaid. Each has its own page in the theme documentation under the shortcodes section.

## Sources

- [hugo-themes/toha on GitHub](https://github.com/hugo-themes/toha)
- [License: MIT](https://github.com/hugo-themes/toha/blob/main/LICENSE)
- [Project website](https://toha-preview.hugo-themes.com)
- [README](https://github.com/hugo-themes/toha/blob/main/README.md)
- [Releases](https://github.com/hugo-themes/toha/releases)

---

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