New user confused by the current state of the theme ecosystem

support
1

I am new to hugo (but familiar with programming) and have some specific and some general queries. If anything reads funny, please assume error on my part.

The quick start guide mentions using git submodules for theme management. That’s great!

But if you read just a bit enough past surface level, you run into some info about modules. It seems modules are a big part of the hugo ecosystem.

So, a somewhat open ended question: Between git sub-modules and go modules, is one or the other better way to manage themes? What are their respective trade-offs? Does the quick start guide prefer git submodules for theme management over go modules because the former has an easier learning curve? Seems like a pesky question but it looks like static site generation will be a fairly involved part of my day job for the near future and I am trying to build a foundation of tools and methods that are better supported and sustainable for the medium term future.

On the topic of theme management, I tried to play with a few themes using both git and go. And saw the following outcomes:

Ananke

Using git

Commands used


git init

git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke

echo "theme = 'ananke'" >> hugo.toml

hugo serve

outcome: Works!

Using go

commands used


hugo mod init www.sample.com

echo `theme = ["github.com/theNewDynamic/gohugo-theme-ananke"]` >> config.toml

hugo mod get -u

outcome: Works!

Paper-mod

using git

commands used


git init

git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/papermod

echo "theme = 'papermod'" >> hugo.toml

hugo serve

outcome: Works!

using go


hugo mod init www.sample.com

echo `theme = ["https://github.com/adityatelange/hugo-PaperMod.git"]` >> config.toml

hugo mod get -u

outcome : Failed :frowning:

error


go: no module dependencies to download

go: added github.com/adityatelange/hugo-PaperMod v0.0.0-20240308054840-b5f7118d826e

hugo: collected modules in 658 ms

WARN 2024/03/09 21:12:43 Module "github.com/adityatelange/hugo-PaperMod" is not compatible with this Hugo version; run "hugo mod graph" for

more information.

Docsy

Using git


git init

git submodule add https://github.com/google/docsy.git themes/docsy

echo "theme = 'docsy'" >> hugo.toml

hugo serve

outcome: Failed

error


Error: module "github.com/FortAwesome/Font-Awesome" not found; either add it as a Hugo Module or store it in "/home/rijan/work_in_progress/h

ugo_troubles/docsy/git_submodule/themes".: module does not exist

Looks like some kind of missing dependency on the repo.

Using go


hugo mod init www.sample.com

echo `theme = ["github.com/google/docsy"]` >> config.toml

hugo mod get -u

outcome: Works! :confused:

So, in my limited testing, it seems like for some themes both go modules and git submodules work, for some one works and the other does not. So, a little jittery. I guess it comes down to the theme maintainer to maintain the theme’s dependencies and health. But the themes I tested are the themes on the Hugo themes landing page. So,

To people more familiar with hugo:

  • what has been your approach to theme management?

  • What do you use? What is more reliable in your experience?

  • Do you switch between one or other fairly often?

  • Are errors easier to chase down for go modules or git submodules?

Or are theme dependencies and health not really a big enough practical concern?

1 Like
2

The quick start guide adds the theme as a Git submodule because:

  1. You don’t have to install Go, which may scare some users away.
  2. When you git submodule add, the theme (and all of its files) is in the themes/whatever directory, ready for you to explore, copy, poke, etc. When you add a theme as a module, the theme is not visible in your project directory unless you hugo mod vendor it into the _vendor directory; there’s more to learn.

I’ll let others chime in on the rest of your questions.

3 Likes
3

I’ve only used themes a few times for projects that I needed to move quickly. In most all cases I prefer to build my own. At the most I’ll import modules, like bep’s bootstrap and tailwind projects, and build from there.

I don’t know if that makes me rare or normal but I’ll say that my experience with themes is uneven. I don’t like relying on third-party devs to keep a project alive and up to date, and I rarely find a pre-made theme that suits all my needs anyway.

The bigger theme projects out there put me off with feature bloat. I like simple and elegant.

Once Hugo’s modules became robust a few years back I didn’t see any point fiddling around with git’s submodules. I try to avoid too much fanciness with git as a personal rule of thumb. Learning to get comfy doing all that did take some time and a lot of reading jmooring’s posts, but I’ve found it worth the effort.

2 Likes
4

Concerning your failed attempts to set up themes:

Papermod (module approach):

Omit the https://prefix when assignung the module in the theme = line:

hugo mod init www.sample.com
echo `theme = ["github.com/adityatelange/hugo-PaperMod.git"]` >> hugo.toml
hugo serve

and you are fine.

Note:
When using hugo module, I would recommend not using the themes line, always declare the module below [module]:

[module]
  [[module.imports]]
    path = "github.com/adityatelange/hugo-PaperMod.git"

This gives you a lot more possibilities, as described here.

Docsy (git submodule approach):

Docsy theme moved away from git submodules quite some time ago, the theme now offers installation as hugo module or via npm.

Coming back to your question what to use best. I don’t think there is a clear answer to this in the sense ‘Always use git submodule/ hugo module’. Personally, I go for hugo modules if possible. In order to be able to locally edit the theme module, a setup like this works fine for me:

[module]
  # Uncomment the next line to build and serve using local theme clone declared in the named Hugo workspace:
  # workspace = "yourtheme.work"
  [module.hugoVersion]
    extended = true
    min = "0.110.0"
  [[module.imports]]
    path = "github.com/user/your_theme"
    disable = false

and the workspace file yourtheme.work looks like

go 1.19

use .
use ../your-theme/   // Local theme clone resides in sibling folder to this project
// use ./themes/docsy/           // Or: Local theme clone resides in themes folder

That works for me. As said, YMMV.

2 Likes
5

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.