So I just read about the modules in the release notes and went and read the documentation about it. But I’m still very confused about them. From your documentation you link to the modules in Go. And those are basically all about Go code. I don’t write Go code. But then there are mentions that themes should now be done via modules. So Hugo modules are not only Go code? But they still need the go.mod? And how do they link, download, what, how?
Honestly, this is really badly documented. And it is now the first topic after “Getting Started” so it seems very important? But as someone not writing Go code I have no clue what this is about.
So let me find some simple questions:
How exactly is a Hugo module defined?
How can a Hugo module be downloaded? Is a link to a Zip file okay? Does it have to be a Git URL? Which branch would be used?
How do you use the module in Hugo? How does this work together with the Hugo virtual file system? There seems to be some mounting configurations, but from where do they mount? What should the source for those mounts be? Can you give an example? And then mount to … what exactly? A directory in my Hugo site?
I’m sorry … those aren’t really simple questions, are they? But I’m so confused by this and to me there is so little documentation available.
I’m sorry that you think the documentation I wrote was really bad. I tried my best. We will improve on this, I’m sure, and your contributions to improve on this documentation is also welcome.
I’d be happy to help out. But I think I first would need to understand this. While waiting for an answer I tried to further understand those modules. But so far didn’t get really far.
For a start it might be helpful if one of those examples gets documentation alongside. Also I would suggest to remove the links to the modules blog and wiki. Especially that wiki entry, just think about a beginner reading through Hugo and then get hit by that wiki entry. That entry is gigantic and I have no clue what is actually important in there for me. And they talk about so many things that seems completely unrelated to Hugo.
You basically ask the beginner to first learn the Go language before continuing to learn about Hugo. I really hope that isn’t your intention
So far … imports are dependencies? Similar to dependencies in Maven or NPM/Yarn? Their versions get defined in a go.mod? So a folder with a go.mod is a module? In that blog and wiki entry they also mention packages, which I’m not sure relate to this? But I’m still very unsure about the source of mounts? To which import does the source definition relate? I took a look at the config.toml of the examples and it didn’t really help. From where does Hugo know which path of which dependency should be mounted into the virtual file system? And that is also what I got so far, the target is a component path in the virtual file system of the site … I guess? How does this work out with transient dependencies though? And who wins when there are multiple targets to the same path?
I think what also confuses me is this answer in the topic over here: Hugo 0.56.0 Released!
I would have assumed that it simply maps the dependency in and thus gets then interpreted by Hugo. But that is not the case? Then for what are modules used? How are they used?
Please don’t feel bad about this. I know very well that writing documentation can be really hard, especially about a topic you understand yourself very well. I feel like the major problem here is that it is too close to Go and thus a lot was forgotten to be explained that someone knowing Go would already know. I would suggest, don’t even mention the Go modules to explain the Hugo modules. Or mention it only as an unimportant side note.
@bep great job! I think that we can all tell that Hugo Modules is a big step forward which will enable a lot of powerful things!
I’ve been reading the docs/code and playing around with the examples in the version release. Some questions come up as to if modules help in particular use cases (and how):
(this is all with the assumption that to use Hugo Modules, your “main site” must be a module itself (go.mod + go.sum present))
Use Case 1: Import external Hugo Theme
Can it Help: Yes
How: ? (Hugo seems to be smart enough to recognize a Hugo theme and will mount it in the correct place? as per https://github.com/bep/my-modular-site )
Use Case 2: Remap Directory structures so Hugo can build a site
Can it Help: Yes
How: Using module.mounts in the config file
Use Case 3: Import Content from external source
Can it Help: Yes (but do these need to be modules? or is that just needed to take advantage of VCS?). The Content’s content can also be remapped (and is available … somehow in templates?)
How: as per https://github.com/bep/my-modular-site
Use Case 4: Create Pages from data source(s)
Can it Help: No (not yet? … this is a completely different thing? … this is kind of connected?)
How: n/a
Use Case 5: Import External Assets (like JS libraries) to site assets
Can it Help: Yes?
How: ? little bit lost here
@HenrySkup all of your yes/nos are correct. I’ll comment shortly on a couple:
3: No, they do not have to be modules. I’m maybe missing some fine detail her: But the project you import only needs to be a module if itself imports modules.
5: This is the use case with some open questions that I hope I’m going to eventually fill.
As JS projects (NPM) builds their output to a folder (typicall dist) you can do the same with those (either to /assets or /static), but for non trivial setups, you will probably want to use NPM…
I have some ideas about how to integrate NPM into Hugo Modules, but those are a little … windy at the moment.
To be precise, they don’t have to be “Go Modules” – they kind of become a Hugo Module when you import it into your project. My definition of a “Go Module” is that they have a go.mod file.
I’m trying to import and mount a JS library from GitHub ( P5.JS to be precise ) and am a little lost. Not sure if the issue is how the repo is structured or with how Hugo Mods work.
Is there some way to display the Hugo virtual file system? this might help with debugging and figuring our where this are located and what has been imported.
