gohugoio / hugoDocs

The source for https://gohugo.io/
Apache License 2.0
1.05k stars 1.48k forks source link

Hugo modules - move overview content to an introduction page #2308

Open jmooring opened 11 months ago

jmooring commented 11 months ago

https://gohugo.io/hugo-modules/

See also https://github.com/gohugoio/hugoDocs/pull/2087

chrillek commented 7 months ago

Currently, the introduction to modules reads

Hugo Modules are the core building blocks in Hugo. A module can be your main project or a smaller module providing one or more of the 7 component types defined in Hugo: static, content, layouts, data, assets, i18n, and archetypes. You can combine modules in any combination you like, and even mount directories from non-Hugo projects, forming a big, virtual union file system. Hugo Modules are powered by Go Modules. For more information about Go Modules, see: https://github.com/golang/go/wiki/Modules https://go.dev/blog/using-go-modules

I think that the first sentence should be immediately followed by an explanation why one would want to use modules. Why would I want to have a "big, virtual union file system" instead of a "small, non-virtual directory" for my project? Referring people to the Go documentation is, in my mind, not very helpful. I find this documentation difficult to read, lacking examples and adding an additional layer of complexity: I don't want to learn about Go, I want to use Hugo.

Also, "you can combine modules in any combination" might be better written like "you can combine modules in any way" – anything that avoids combining combine and combination, because one doesn't combine combinations – combining something results in a combination.