Can this module be called from action-gh-pages and other similar actions?

elsatch commented 2 years ago

I have just discovered this repository and tried to add it to my Hugo site. It is hosted here on GitHub and I am using action-gh-pages to construct it.

I am using the geeky-hugo theme that uses toml files for configuration, so I tried to adapt the yaml format in the documentation. My modules section on config/_default/config.toml looks like this:

############################# Modules ##############################
[module]
[module.hugoVersion]
extended = true
min = "0.87.0"
[[module.imports]]
path = "github.com/peaceiris/hugo-mod-mermaidjs"

As I push this change into the repository, I am getting an error in the action log:

Error: module "github.com/peaceiris/hugo-mod-mermaidjs" not found; either add it as a Hugo Module or store it in "/home/runner/work/elsatch.github.io/elsatch.github.io/themes".: module does not exist

So I am wondering if is it possible to import these modules on the Github actions, or if module import is restricted in some way into this environment.

I have taken a look to the project docs, the Hugo documentation about modules, but there are not lots of examples on how to use these modules in Hugo.

peaceiris commented 2 years ago

Did you commit your go.mod and go.sum files?

elsatch commented 2 years ago

I have taken an extended look to other resources and now it works. So, yes, you can use this module if you use actions-gh-pages to build your site.

These are the steps I took to solve my issue:

Install Go for my operating system as this is required to work with Hugo modules locally.
Execute hugo mod init mysite.github.io at the root level of my repo to initialize it a Hugo module
Execute hugo mod getto make Hugo read the config file and download hugo-mod-mermaidjs
git add go.* to stage go.mod and go.sum
git commit -m 'Initialized repo as Hugo module'
git push origin main

Once the module was loaded on my local Hugo repository, the action-gh-pages executed without any errors. Execution time increased around 20 secs compared to previous executions.

Run hugo --minify
hugo: downloading modules …
hugo: collected modules in 25210 ms

If you believe this could be useful to other people, I could update README.md with the instructions and send you a pull request. What do you think about it?

peaceiris commented 2 years ago

The official documentation Use Hugo Modules | Hugo describes that. We are happy to have the link on our README. Could you make your pull-request? :)

peaceiris commented 2 years ago

Also, I like updating the official documentation.

elsatch commented 2 years ago

I just added the link and a brief description on README and made the pull-request.

Regarding the official documentation, I agree that missing information and examples should be updated there.

As a newcomer to the Hugo ecosystem, there are several parts that are super easy to start working on, but others depend on a deeper knowledge of Go. Some concepts might be evident to more seasoned programmers but invisible to us.

For example, in the Use Hugo Modules guide they explain that you must initialize a module before using it. They use the example of the gohugoio/myShortcodes. I assume this module contains some shortcodes in html files, that can be included in your theme/shortcodes folder.

Then it jumps to the using a module for a theme section. Given I want to import hugo-mod-mermaidjs to my site, and not just to my theme, I assumed this section did not apply to me. Why would I need to init my repo as a Hugo module? It is never explained in the official documentation.

Maybe at this step I was a bit biased after reading Master Hugo Modules: Managing Themes As Modules. I thought people were configuring their themes as Hugo modules but reading the official docs it says: "Use a Module for a Theme" not "Use a Module as a Theme". It is a bit confusing!

peaceiris / hugo-mod-mermaidjs

Can this module be called from action-gh-pages and other similar actions? #1