Managing Hugo themes with modules for new those new to Hugo

support
1

Hello. I am getting started with Hugo and trying to identify which of the optoins I should be going with. There are a lot of themes and I read about modules but not all of the themes have clear instructions about how to include them as modules. A couple of questions, I’m glad to RTFM but the Hugo documentation doesn’t make sense and RTFG has a maze of twisty little pointers, all different.

Goal - I want to try out some different themes for my new site. So many themes on the “best hugo theme” google circuit are dead/archived, I need to test them to see which ones still actually work with modern Hugo releases.

If I want to use a module, Hugo module guide (Use Hugo Modules | Hugo) says I need to start by running this command

hugo mod init github.com/gohugoio/myShortcodes

a. this seems like a command for using a custom shortcode. I don’t want to use a custom shortcode, I want to use a theme like Paper or Book.

b. My site is not in github.com. It’s only going to be deployed on my local network as a reference wiki.

c. I don’t need shortcodes, etc - yet.

The rest of the guide doesn’t say anything else about initializing my new site to be able to add modules and I can’t find a clear workaround. Searches and ChatGPT just repeat the same shortcodes command above.

Is there a step-by-step guide for NTH (new to Hugo) people to initialize a site, install a module using a theme and then update the theme from the publisher’s repo?

2

I started my first Hugo project by migrating a blog from WP and writing my own theme. That taught me all I needed to know and avoided all the pitfalls of under-documented, over-engineered and abandoned themes. YMMV, of course.

It is a sample line, I’d wager. As indicated by the abbreviation “e.g.” just before this line.

Then don’t use them. There’s no obligation.

Personally, I refrained from themes as modules. There might be advantages to it that I don’t see or don’t need, though. Simply downloading the theme worked ok for me.

3

Thanks - are you recommending creating my own theme?

I could do that, but I’m pretty basic in HTML/CSS/JS engineering and I thought the idea of themes was that one could re-use instead of re-engineering functionality some of the themes offer.

4

I wouldn’t go so far as to recommend anything. But from lurking here, I have the impression that newbies tend to have difficulties getting Hugo up and running with many themes.

It is my impression that solid HTML/CSS knowledge makes it a lot easier to work with Hugo. It is definitely not like WordPress, where plugins attempt to shield you from all the gory details (and create security issues along the way). You could start out with some simple HTML and add CSS along as you go. And you probably don’t even need JS.

5

@moonlighter

The quick start guide provides this example to create a site and then install a theme as a Git submodule:

hugo new site quickstart
cd quickstart
git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
echo "theme = 'ananke'" >> hugo.toml
hugo server

The equivalent, installing a theme as a Hugo module, is:

hugo new site quickstart
cd quickstart
hugo mod init github.com/jmooring/quickstart
echo "theme = ['github.com/theNewDynamic/gohugo-theme-ananke']" >> hugo.toml
hugo server

Line 3 (hugo mod init) is necessary because the project itself must be a module. The identifier (github.com/jmooring/quickstart) can be anything, even “foo”, as long as it doesn’t conflict with the identifiers of other modules in your project. If you plan to keep your project under source control, either privately or publicly, use the tld/user/repo syntax.

The commands above produce this site configuration file:

baseURL = 'https://example.org/'
languageCode = 'en-us'
title = 'My New Hugo Site'
theme = ['github.com/theNewDynamic/gohugo-theme-ananke']

Although specifying modules in the theme array (as shown above) works fine, you have more control if you explicitly import the theme as a module:

baseURL = 'https://example.org/'
languageCode = 'en-us'
title = 'My New Hugo Site'

[[module.imports]]
path = 'github.com/theNewDynamic/gohugo-theme-ananke'

To add another module, for example, a content module:

baseURL = 'https://example.org/'
languageCode = 'en-us'
title = 'My New Hugo Site'

[[module.imports]]
path = 'github.com/theNewDynamic/gohugo-theme-ananke'

[[module.imports]]
path = 'github.com/jmooring/hugo-content'

To update modules, run hugo mod get --help for details.

1 Like