Notes

Load content from a github repo for a hugo website as a module

loading content from a GitHub repo into my Hugo site as a module, the module.toml mounts, and troubleshooting hugo mod errors

Edit on GitHub


Hugo
3 minutes
Hugo Hugo Modules GitHub

NOTES:

  • In 2024 a bug stopped hugo mod init (and the other hugo mod commands) when a module.toml already existed. Fixed in Hugo v0.134.3 (September 2024).
  • Install Hugo from the apt package or the official release binary instead of the snap. The snap is strictly confined, so hugo mod can’t reach your SSH keys and you get weird permission errors with SSH auth

https://gohugo.io/commands/hugo_mod/

In order to load modules, your site needs to be a module itself.

1hugo mod init github.com/aamnah/fazalashfaq.com
2
3# this will create a file called: go.mod

Define your modules inside config/_default/module.toml

 1# file: config/_default/module.toml
 2[[imports]]
 3  # import the notes repo as a Hugo module
 4  path = "github.com/aamnah/notes.fazalashfaq.com"
 5  disable = false
 6
 7  # mount the imported repo in this location
 8  [[imports.mounts]]
 9  # root of repo can be specified with `.`
10  # if bringing in a subdirectory, mention the subdriectory path in source
11  source = "."
12  target = "content/notes"
13  files = ["! README.md"] # leave out README.md (Hugo 0.153 removed the old excludeFiles setting)

The module can also define its own mounts in a hugo.toml at its root. A site that imports it without [[imports.mounts]] uses those, so the content repo decides what gets published.

Add a Hugo module

1hugo mod clean --all
2hugo mod get -u
3hugo mod get -u github.com/USER_OR_ORG/REPO
4hugo mod vendor

Troubleshooting

If you are getting fatal errors related to Git and Username then it is very likely that the module you are trying to import is not public, i.e. you’re importing a module that is a private repo. On Netlify it looks like this:

12:14:49 AM: go: github.com/user/repo@v0.0.0-20240626152414-39076531a1f3: invalid version: git ls-remote -q origin in /opt/build/cache/hugo_cache/modules/filecache/modules/pkg/mod/cache/vcs/96d4f25fe353b629d6aa0e8760275debc948f906cf940669e8b1a5766c08262c: exit status 128:
22:14:49 AM: 	fatal: could not read Username for 'https://github.com': terminal prompts disabled
32:14:49 AM: Confirm the import path was entered correctly.
42:14:49 AM: If this is a private repository, see https://golang.org/doc/faq#git_https for additional information.

Hugo modules are Go modules, so the fix is the Go one: give git a token (or SSH key) that can read the repo.

By default, go get uses HTTPS. If GIT_TERMINAL_PROMPT is set to 0 or false it will not prompt your for Git credentials and fail instead. And if you have 2FA activated for your git provider, then you either need to use a PAT (Personal Access Token) to get the repo over HTTPS or use SSH instead. Read this.

1# Enable prompting for credentials
2export GIT_TERMINAL_PROMPT=1

1# Mark some repos as private
2# (Hugo already does this for every module: its `module.private` setting defaults to '*.*')
3
4export GOPRIVATE=github.com/ORG_OR_USER/*
5# OR
6go env -w GOPRIVATE=github.com/ORG_OR_USER/*

1# Use SSH versions of repo urls
2git config --global --add url."git@github.com:".insteadOf "https://github.com/"

1# Specify an access token to be used
2FILE="${HOME}/.netrc"
3USERNAME=""   # your GitHub username
4TOKEN=""      # a token with read access to the repo
5
6printf 'machine github.com login %s password %s\n' "${USERNAME}" "${TOKEN}" >> "${FILE}"
7chmod 600 "${FILE}" # only you can read it

How i set this up on Netlify (token as an environment variable, .netrc in the build script) is in Load Go modules from private repos.

Related

Browse all topics