# hugo-profile: a mobile first Hugo theme that ships the portfolio structure for you

> hugo-profile is an MIT licensed Hugo theme for a personal portfolio and blog, with light, dark and auto colour modes, three built in languages, and a wizard-like quick start that ends with a site whose sections are already laid out. It suits one person with a handful of pages, and it is a theme rather than a framework, so what you get is a set of sections and a colour scheme rather than a design system.

**gurusabarish/hugo-profile** — A highly customizable and mobile first Hugo template for personal portfolio and blog.

- Repository: https://github.com/gurusabarish/hugo-profile
- Website: https://hugo-profile.netlify.app
- Stars: 1,089 · Forks: 571
- Language: HTML
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/gurusabarish-hugo-profile

## A theme that decides your site structure for you

hugo-profile is a Hugo theme for personal portfolios and blogs, described as high performance and mobile first, and the way it works is that it hands you a complete site rather than a set of building blocks. The `hugo.yaml` file in the site root controls the site title, the homepage content, and which sections are shown or hidden, with About and Education given as the examples. That is the trade in one sentence: you get a coherent structure, a colour scheme and a working blog on day one, and in exchange your navigation is the theme's navigation. The feature list is short and practical: fully responsive layout, minimalist design, SEO friendly output, internationalization support, light, dark and auto theme colour configuration, categories and tags, Google Analytics, Disqus comments and a FormSpree contact form, all built on Bootstrap and Font Awesome. The example site is published at hugo-profile.netlify.app, the deployment badge points at a Netlify site, and the repository carries a `netlify.toml`, so the intended deployment path is a static host with continuous builds rather than a hand rolled pipeline.

## Getting the theme in: clone it or submodule it

The requirements are modest, Hugo version 0.87.0 or higher, and the README gives you the command to check what you have. The theme itself is added in one of two ways, and the difference is a real fork in the road for how you will maintain the site afterwards. Option A is to clone the repository inside your themes folder, which the README says allows you to make lots of custom changes. Option B is to add it as a git submodule, which the README says allows you to get automatic or structured updates from the original repository. The first gives you a fork you own completely and merge conflicts you have to resolve by hand. The second keeps a pointer to the upstream theme so that upstream fixes arrive as a submodule update, and any customization you make in the theme directory has to be carried across those updates. The commands are the standard ones, and the site is created with a YAML configuration rather than the default TOML, so the config file the theme ships is the one you use:

```bash
hugo new site my-site --format="yaml"
```

```bash
cd my-site/themes
git clone https://github.com/gurusabarish/hugo-profile.git
```

```bash
cd my-site
git init
git submodule add https://github.com/gurusabarish/hugo-profile.git themes/hugo-profile
```

Then the example configuration is copied over the site's own, which is the step that actually wires the theme in:

```bash
cp -f themes/hugo-profile/exampleSite/hugo.yaml ./hugo.yaml
```

## The first run looks broken, and the README says why

This is the detail that saves an hour for anyone starting out, and the README handles it head on. When you first run the development server, the site may look incomplete, with images missing and the Blog or Gallery sections not appearing. The cause is that the example content currently resides in `themes/hugo-profile/exampleSite/`, whereas Hugo expects content in the root level `static/` directory for images and `content/` directory for pages. The fix is two rsync commands that copy both trees into place, and the README recommends running them so you can see a complete version of the example site before you start changing it:

```bash
rsync -av themes/hugo-profile/exampleSite/static/ ./static/
rsync -av themes/hugo-profile/exampleSite/content/ ./content/
```

After that you start the server with `hugo server` and edit the copied content, and the README says you can customize or replace it to match your own site. Content is created with Hugo's own content scaffolding command, which writes a file with front matter that includes metadata such as the date:

```bash
hugo new content content/blogs/my-post.md
```

The repository layout explains where everything lives: `layouts/` for the templates, `static/` for assets, `archetypes/` for the content scaffolding, `exampleSite/` for the demo content and configuration, `i18n/` for the translation files, `images/` for theme imagery, `theme.toml` for the theme metadata Hugo reads, and a `wiki/` directory that holds the documentation, which the README points to as versioned in the repository, with the same wiki also published on the GitHub wiki.

## Internationalization that already knows about three languages

Multilingual support is one of the reasons the theme is more than a starting layout, and the implementation is conventional Hugo i18n rather than anything unusual. The theme ships translation files in the `i18n/` directory for English, Spanish and French, and the README explains the three moving parts. The configuration in `hugo.yaml` declares the default language and the languages themselves with a name and a weight, and a language switcher dropdown appears in the navigation bar automatically once more than one language is configured. The third part is backward compatibility: existing sites continue to work without any changes, and the theme falls back to English or your configured language if no multilingual setup is provided. The configuration block is the one the README shows:

```yaml
defaultContentLanguage: "en"
defaultContentLanguageInSubdir: false

languages:
  en:
    languageName: "English"
    weight: 1
  es:
    languageName: "Español"
    weight: 2
  fr:
    languageName: "Français"
    weight: 3
```

Adding a language is a three step exercise. You create a translation file in the site root or in the theme, using Hugo's TOML table format for the translated strings:

```toml
[nav_about]
other = "Über uns"

[nav_experience]
other = "Erfahrung"
```

You add the language to the `hugo.yaml` configuration with its name and a weight, and optionally create language specific content in a `content/de/` directory. Individual strings can also be overridden without touching the translation files, by adding them to a `params.terms` section in `hugo.yaml`, where the README shows `read` and `pageNotFound` as the examples.

## What the theme hooks into and what it leaves to you

The integration list tells you what is already solved and what is not. Analytics comes through Hugo's internal Google Analytics template, comments through Disqus, and the contact form through Formspree, which is a hosted form service rather than a self hosted endpoint, so a deployment that cannot send email to a third party will need a different form. Categories and tags are supported for the blog, and the colour configuration offers light, dark and auto, with the auto option presumably following the system preference, and the wiki page for colour customization is linked from the feature list. What the theme does not provide is a content model beyond a personal site: the sections it knows about are the ones a portfolio needs, and if your site is a magazine or a documentation set you will be writing layouts yourself inside `layouts/`. The documentation is unusually well organised for a theme, with the full documentation versioned in the repository at `wiki/Home.md` and a separate wiki page for tips specific to the theme, so you can read the instructions for the exact version you are using rather than whatever the site currently shows.

## Versioning, licensing and what the tag numbers tell you

The licence is MIT, and the repository is a plain theme repository with the standard Hugo layout. The release history is where the interesting detail sits, because the version numbers are not conventional semver: v4.051 was tagged on 2024-06-15, v4.052 on 2025-10-07 and v4.06 on 2026-02-08. The middle number appears to track a revision count and the third a release series, which tells you the project bumps versions often and that a plain semver range in your own build will not behave the way you expect. The last push was on 2026-10-11, so the theme is being worked on. If you install it as a submodule, the sensible discipline is to pin the submodule to a tag you have read the wiki page for, since the wiki is versioned alongside the code, and to keep your own customizations in the site rather than inside the theme directory, which is the same advice Hugo's own theme practice gives and the reason the README offers the submodule route at all.

## Conclusion

Adopt hugo-profile if you want a personal site with a portfolio structure, a blog and multilingual pages running on Hugo, and you would rather configure an existing theme than design one. Do not adopt it as a base for a large content site with many authors and many page types, because the section structure is the theme's own. Before you start, check that you have Hugo 0.87.0 or later, install the theme as a git submodule if you want upstream updates, and copy the example content and static assets into the site root, otherwise the first run looks broken. The licence is MIT, the latest tag is v4.06 from 2026-02-08, and the last push was on 2026-10-11.

## FAQ

### What Hugo version does hugo-profile need?

Hugo version 0.87.0 or higher. The README tells you to check with `hugo version` and to follow the official installation guide if Hugo is not installed.

### Why does my hugo-profile site look incomplete on first run?

The example content and images live in `themes/hugo-profile/exampleSite/`, while Hugo expects them in the root level `static/` and `content/` directories. The README recommends copying them with `rsync -av themes/hugo-profile/exampleSite/static/ ./static/` and the same for the content directory.

### Should I clone hugo-profile or use a git submodule?

Cloning into the themes folder allows lots of custom changes but leaves you to merge upstream updates by hand. The README presents the submodule route as the way to get automatic or structured updates from the original repository.

### Which languages does hugo-profile ship with?

English, Spanish and French, with translation files in the `i18n/` directory as `en.toml`, `es.toml` and `fr.toml`. A language switcher dropdown appears in the navigation bar when multiple languages are configured, and the theme falls back to English if no multilingual setup is provided.

### How do I add a new language to hugo-profile?

Create a translation file such as `i18n/de.toml` in the site root or in the theme, add the language to the `languages` block in `hugo.yaml` with a name and a weight, and optionally create language specific content in a `content/de/` directory. Individual strings can also be overridden through the `params.terms` section of `hugo.yaml`.

## Sources

- [gurusabarish/hugo-profile on GitHub](https://github.com/gurusabarish/hugo-profile)
- [License: MIT](https://github.com/gurusabarish/hugo-profile/blob/master/LICENSE)
- [Project website](https://hugo-profile.netlify.app)
- [README](https://github.com/gurusabarish/hugo-profile/blob/master/README.md)
- [Releases](https://github.com/gurusabarish/hugo-profile/releases)

---

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