Hugo modules for "dummies"

tips & tricks
1

For the first time I have been able to use the Hugo modules feature. Thanks to @chreliot and his post, I finally figured out how to use it. I’m not smart enough to figure it out out through the documentation that are available so far.

For other Hugo modules noobs that are fighting with Hugo modules. This is a step by step guide to help you to get up and running with Hugo modules.

Table of Contents:

  • Part 1. Prepare a Hugo site to test out Hugo modules
    • Install latest version of go on your computer
    • Prepare a test site to implement a theme as a Hugo module
  • Part 2. Add a theme as a Hugo module
    • For now it has only been bureaucracy. The fun part is starting now
  • Part 3. Add content as a Hugo module
    • Adding content as a module, that is what you really, really, really whant
    • Upload your site to GitHub with two modules added.
    • You can use Hugo modules to mount any kind of resources to your Hugo site.

Part 1. Prepare a Hugo site to test out Hugo modules

Install latest version of go on your computer

Make sure that you have installed a recent version of go on your computer. Here is the link to the go install. Follow the instructions carefully. The Hugo mod commands do not work without doing this. If you use the Hugo mod commands, without installing go, nothing happens. You don’t get an error message as feedback.

Prepare a test site to implement a theme as a Hugo module

The theme hugo-xmin are used as an example (yes that’s exactly the same as @chreliot used in his post)

First you have to prepare a Hugo site to test out the hugo-xmin theme as a Hugo module

  1. Download the example site for the hugo-xmin theme:
    You can download the zip file here
  2. Extract the folder exampleSite to your harddrive
  3. Rename exampleSite to hugo-test-modules

Later on, you will add the hugo-xmin theme as a Hugo module.

Part 2. Add a theme as a Hugo module

There are different ways to use Hugo modules to add a theme to your Hugo site. This is one of them.

When you test your site in this stadium. You get an error message.

hugo serve

Error: module "hugo-xmin" not found; ...

That’s because no theme is added to the Hugo site.

For now it has only been bureaucracy. The fun part is starting now:

  1. Comment out or delete the variable theme in config.toml file

    # theme = "hugo-xmin

    We no longer need this variable since we make use of Hugo modules (It is possible to use the theme variable to mount modules. For simplicity you use the new preferred method).

  2. Add this to your config.toml to specify a theme as Hugo module:

    [module]
  [[module.imports]]
    path = "github.com/yihui/hugo-xmin"

    You don’t have to specify the folder to mount to, neither that it is a theme you are mounting. By default Hugo modules behave as it is a theme. Hugo mounts GitHub - yihui/hugo-xmin: eXtremely Minimal Hugo theme: about 150 lines of code in total, including HTML and CSS (with no dependencies) in the Hugo theme folder.

  3. Initialize project as Hugo module. Go to CLI and type in this command in your Hugo site:

    hugo mod init ugly-dummy

    YES IT WAS ugly-dummy (It really doesn’t mater what the parameter is to the hugo mod init command, but there are some restrictions on “.”, “/”, etc.). I think it’s more appropriate to name the module as your Hugo site name. In this case hugo-test-modules. but ugly-dummy is also fine.

    The command could output something like this:

    go: creating new go.mod: module ugly-dummy

    information: a new file go.mod was created

  4. Test your site:

    hugo serve

    Your site should look exactly the same as this site

    information: a new file go.sum was created

  5. Now its time to upload your finished site to GitHub.

    Create a GitHub Repo and name it hugo-test-modules

    Git commands to upload repo:

    git init
git add -A && git commit -m "Initial Commit"
git remote add origin https://github.com/< your username >/hugo-test-modules.git
git push -u origin master

  6. When you now clone your newly updated repo to your machine, there is no need for git clone --recursive. It’s just plug and play. Just do a regular git clone

    git clone https://github.com/< your username >/hugo-test-modules.git

That was all “happy moduling”

Part 3. Add content as a Hugo module

Adding content as a module, that is what you really, really, really whant

Your site is up and running with a Hugo module, the theme hugo-xmin . Now lets add some markdown files to your content. You can mount folders with markdown files from any git repo(It’s also possible to mount folders from your hard drive). The repo you mount, don’t has to be a Hugo repo. You are going to mount a folder from this repo. Check it out and be familiar with it. The repo contains a folder testing-hugo-modules, that could be mounted. The folder contains two files:

  • testing-hugo-modules/file-1.md
  • testing-hugo-modules/file-2.md

Here is the configuration that you could drop in your config.toml file. Add it just under the theme stuff, under [module] section:

[[module.imports]]
    path = "github.com/craftsmandigital/markdown-content-repo"
    disabled = false

    [[module.imports.mounts]]
    source = "testing-hugo-modules"
    target = "content/new-stuff"
  • path describe the repo you mount content from
  • source describe witch folder(from root) in mounted repo you could append to your Hugo site (this link brings you inside the actual folder)
  • target describe witch folder(from root) in your Hugo site the mount could appear (content/new-stuff)

After updating config.toml there is nothing more to do. It’s time to test your site.

hugo serve

Now you can see your two new posts at the bottom of the start page (http://localhost:1313/)

  • 2019/09/12 file 1 for testing Hugo modules for content
  • 2019/09/12 file 2 for testing Hugo modules for content

Click on one of the posts. Check out the URL address

Do you recognize new-stuff from your config.toml file. That was your target for your mounting point(content/new-stuff)

Upload your site to GitHub with two modules added.

git add -A && git commit -m "Initial Commit"
git push -u origin master

Try to clone your Hugo site:

git clone https://github.com/< your username >/hugo-test-modules.git

Your site could work right out of the box:

hugo serve

You can use Hugo modules to mount any kind of resources to your Hugo site.

You can mount layouts like partials, shortcodes, resources like JS libraries. Etc. Use your Imagination.

That was all, really really really “happy moduling”

2 Likes
2

Hi, This documentation is looking pretty good, but there are a few things:

Does my site need to be a Git Repo?

Having your website in a Git repository is not necessary for Hugo Modules to work – it can even be local files on your computer.

The key is that your site needs to be a Hugo Mod itself, which only means that it has a go.mod file in its directory. This doesn’t need to look any more special than:

module website

go 1.12

NB there might be some restrictions about slashes at start / end of name.

Does theme = ... still matter?

The distinctions here are a little ties up in multiple changes in Hugo including:

  • see: Hugo Theme Components which are tightly coupled to Hugo Mods.
  • Hugo’s defaults + “smartness” : Hugo Mods import will, by default, import things into your site’s /theme directory and guesses that you want to apply these themes to your website build
  • see: this thread and this thread where i’m playing around with different ways to pull in themes (with and without mods) note that there might be some different behavior with.yaml vs .toml

TLDR: yes and no

theme = ... isn’t dead and might have multiple uses :

  • A Guess : you could shape the Theme Inheritance
  • I use Hugo Module Mounts to mount a theme directory and then use theme = ... to select the theme(s) that I want to render with.

@bep correct? or have I massively misled people? :grimacing:

3

Mostly:

But you use either

theme = ...

or [module].

Not both. They serve the same purpose. The latter has more options (mount …), the former is mostly kept for backward compability.

1 Like
4

Thank you for your feedback @HenrySkup

I have experimented with the hugo mod init command. I admit that I reealy cant grasp all of it. It does not matter what you write to the parameter, it works anyway.

  • Even if you have a non-existent gitHub repo as a parameter, the command will work anyhow.
    hugo mod init github.com/doesnt/exist
  • This one will also actually work
    hugo mod init ugly-dummy

As you say. You do not need a GitHub repo as a parameter.

I have updated the post according to your guidelines.

I have also updated that it is still possible to use the theme variable in config.toml

1 Like
5

A post was split to a new topic: My first reaction to Hugo Modules is to look for alternatives

6

Tnx, for the great tutorial. Just want to give an additional hint. Modules still do not work with the snap installation. Use brew instead. Took me two hours :unamused:

8

A related hint from me (which should get a more prominent place in the docs):

  • Hugo uses a /tmp dir for the cache if cace dir is not set (in config.toml or environment)
  • Go downloads the modules and write protects all directories
  • On MacOS I have experienced some occasional issues which I guess relates to MacOS trying to clean out these directories, but only partly succeeds.
  • Setting HUGO_CACHEDIR os env variable to something outside /tmp is the solution to the above. It’s also in general a good thing.