Hugo: Consider components below /themes for vendoring

[bep]

This relates to #5911 -- but I've been going forward and back on this question a few times now, enough to tell me that I will wait and consider this for later. Easier to add than remove.

I will write a fairly detailed summary, as I think this will help add some understanding to the complete topic.

Ref. the site in https://github.com/bep/my-modular-site

The module config in config.toml looks like this:

theme = [
    "in-themesdir",
    "github.com/bep/hugotestmods/myshortcodes",
    "github.com/bep/hugotestmods/myv2/v2",
    "github.com/bep/hugotestmods/mypartials",

    "github.com/bep/hugo-fresh",
]

Some general notes:

• I have vendored this on the top level, but this is also possible to do on component level, and it will work as you would expected re. the inheritance graph. The command to do that is hugo mod vendor.
• in-themesdir is just a component stored directly below /themes.

With that:

▶ hugo mod graph
github.com/bep/my-modular-site in-themesdir
github.com/bep/my-modular-site github.com/bep/hugotestmods/[email protected]+vendor
github.com/bep/my-modular-site github.com/bep/hugotestmods/myv2/[email protected]+vendor
github.com/bep/my-modular-site github.com/bep/hugotestmods/[email protected]+vendor
github.com/bep/my-modular-site github.com/bep/hugotestmods/[email protected]+vendor
github.com/bep/my-modular-site github.com/bep/[email protected]+vendor

▶ hugo mod graph --ignoreVendor
github.com/bep/my-modular-site in-themesdir
github.com/bep/my-modular-site github.com/bep/hugotestmods/[email protected]
github.com/bep/my-modular-site github.com/bep/hugotestmods/myv2/[email protected]
github.com/bep/my-modular-site github.com/bep/hugotestmods/[email protected] => /Users/bep/sites/hugomod/hugotestmods/mypartials
github.com/bep/hugotestmods/[email protected] github.com/bep/hugotestmods/[email protected]
github.com/bep/my-modular-site github.com/bep/[email protected]

Some general remarks:

• Components in a _vendor dir will get top priority. You can tell Hugo to ignore it by giving the --ignoreVendor flag (or setting ignoreVendor = true in config).
• The => syntax above is coming from Go Module's replace directive which, among other things, can be used to tell Hugo to find the source somewhere else (for local development etc.)
• If I find some time, I may add some warnings if there is a "not supported by the current Hugo version" problem in the above.

But to the core question: When you run hugo mod vendor we will (currently) not include the folders below /themes (as seen in the first listing).

/cc @regisphilibert @larzza @budparr @onedrawingperday and gang ...

[onedrawingperday]

But to the core question: When you run hugo mod vendor we will (currently) not include the folders below /themes (as seen in the first listing).

So that when Hugo Modules are launched it will not be possible to ship a Hugo theme that uses them. The Modules will have to reside under the exampleSite/ directory. Right?

Well as long as this is mentioned in the Docs in big bold letters, I don't think it will be a problem also for the following reasons:

• Theme components were not supported on the Themes Site for a while, so there is precedent, (Hugo is after all still a WIP since it's below version 1.0.0)

• Few will notice. For example we have had Hugo Pipes and Image Resources for over a year now and we are still seeing custom (Gulp etc) pipelines in theme submissions. Most authors who write or port themes to various platforms don't really keep up with the latest software developments.

So if you want to wait before adding this I don't see a problem.

[bep]

So that when Hugo Modules are launched it will not be possible to ship a Hugo theme that uses them. The Modules will have to reside under the exampleSite/ directory. Right?

No. Modules should reside in its own repository (which can contain many modules, if needed) and imported by its GitHub (or whatever) path. There is many fine details in this, with vendoring and all, and this particular issue details a corner case with vendoring for the modules that you just clone directly into /themes.

I will not go further into details about this, but I can say this:

The situation for themes and the theme site will dramaticallly improve with all of this. Themes can absolutely use these modules. In most cases, using a theme component (shortcodes etc.) in your theme or project is just to add it to your config and run Hugo.

[larzza]

@bep Maybe I'm missing something but... why should components in the themes dir be copied to _vendor in the first place?

Either I have a "hard"-copy of the components in the themes-dir, i.e bundled with the project git-repo, or I've taken a decision to add them as git-submodules instead of adding the components as Hugo mods.

If I want a standalone project I just use /layouts etc in the project and Hugo mods-vendoring for components, i.e. I don't use themes-dir at all.

[bep]

why should components in the themes dir be copied to _vendor in the first place?

I don't know, which is why I created this issue.

[larzza]

In that case I don’t think they should, i.e. I agree it’s a good idea to wait....