Hugo: Consolidate theme.toml and config.toml, add a module config section etc.

[bep]

I will make sure that having a theme.toml will keep on working, but having both of these is confusing and adds work in more than one way.

A theme.toml can look like this:

name = "Component o1"
license = "MIT"
min_version = 0.38

For a component with the above theme.toml I will rewrite it internally to this new structure in config.toml:

[module]
name = "Component o1"
license = "MIT"
[module.hugoVersion]
min = "0.38"

With this we will also

• retire the theme config option (which will also still work), and introduce a new imports slice, e.g.:
• replace min_version with hugoVersion with min, max and extended (as discussed in #5450)

A more complete config.toml could look like this:

title = "My Module"
[module]
imports = ["component1", "component2"]
description = "Component n1 description"
[module.hugoVersion]
min = "0.40.0"
max = "0.50.0"
extended = true

As I'm extremely bad at naming, please shout if you strongly disagree with the above.

/cc @onedrawingperday @regisphilibert @kaushalmodi and gang

[onedrawingperday]

I think that @digitalcraftsman also needs to read this issue.

So basically a theme becomes a module. I'm fine with the proposed setup and the backwards compatibility for theme.toml

I suppose that this will change the submission process for Hugo Themes.

[larzza]

@bep Hm.... now I’m confused... isn’t what you call component1, component2 also each a module, i.e Go modules? It seems that there can only be one config entry of what you now call module. Is that right?

[digitalcraftsman]

The names for the variables look fine. Can someone explain to me why the title isn't part of the [module] block, which seems to contain the metadata of the module?

Hence I would expected something like this:

[module]
title = "My Module"
imports = ["component1", "component2"]
description = "Component n1 description"

But an extra block for the metadata would not add much value on its own.

@onedrawingperday: I suppose that this will change the submission process for Hugo Themes.

The build script for the Hugo theme site would have to be adjusted accordingly, because we have to fetch the required components of the theme as well.

Further, it can make the debugging of themes more extensive. We would also loose control of the Hugo theme site to a certain degree. Right now it's a garden with somewhat maintained flowerbeds that fulfill a certain threshold of quality. After a theme submission our small fence around the garden, that protects it, can be overcome. If something goes downhill we eventually notice and fix it, but the garden is already large. If we add support for third-party components that we can't control, we might open our gates a bit to wide - without knowing whether the third-parties, that enter the garden, behave well or not.

@onedrawingperday do your see other concerns or larger adjustments that have to be made?

[bep]

Can someone explain to me why the title isn't part of the [module] block, which seems to contain the metadata of the module?

Probably a bad example from me, but everything outside of the module is what already exists in a config.toml (whether it's a "main project" or a "theme component") -- title is typically used in the project config. module will contain imports and Hugo version restrictions + whatever was in theme.toml.

The build script for the Hugo theme site would have to be adjusted accordingly because we have to fetch the required components of the theme as well.

The script needs to be adjusted, but I suspect it will make it simpler (we will get rid of the 350 submodules). If it for the theme site gets too hard to control random third-party components referenced by path, we can easily put some restrictions, either 1) no components or 2) only vendored components (which will be browsable and part of the theme repo). My main use in this is anyhow not the themes on the themes site, but to make it much simpler for myself and others like me to compose my projects/themes from smaller modules.

[onedrawingperday]

@digitalcraftsman But if we add support for third-party components that we can't control, we might open our gates a bit to wide - without knowing whether the third-parties, that enter the garden, behave well or not.

We have already seen third parties who have not behaved well in the garden.

I see your point. We cannot blindly trust user input in this case.

@bep 1) no components or 2) only vendored components (which will be browsable and part of the theme repo)

I opt for option 1 for now. At least until me and @digitalcraftsman grow familiar with the new way of doing things. Then we can go for option 2.

[larzza]

@bep Did you see my question above? I’m curios... Isn’t it confusing to call a theme a module and module a component?

[digitalcraftsman]

I opt for option 1 for now. At least until me and @digitalcraftsman grow familiar with the new way of doing things. Then we can go for option 2.

Sounds like a good approach. Option 1 is the easiest one but also the most restrictive. What if a component is essential to a theme and we remain with option 1 (at least for a certain amount of time)?

[bep]

Isn’t it confusing to call a theme a module and module a component?

Sure. Have I?

[onedrawingperday]

@digitalcraftsman We can set a time frame if you want. A month or two. Then we go for the second option, once we know everything there is to know about Hugo Modules.

I doubt that we will see a theme submission that relies on a Hugo (Go) module so soon. We still get themes with Gulp Pipelines and theme authors (that I've written to) were unaware of the fact that they could have done the same with Hugo Pipes.

If for some reason you want to go with option 2 right from the start, then we can also do that, although the submission process might take longer (since everything will be new to us also).

[digitalcraftsman]

If for some reason you want to go with option 2 right from the start, then we can also do that, although the submission process might take longer (since everything will be new to us also).

@onedrawingperday Option 1 would be my preferred one. This way we've time to experiment and to adjust our workflow for a submission.

[larzza]

title = "My Module"
[module]   <============================= old theme config param?
imports = ["component1",  , "component2"] <================ modules/components
description = "Component n1 description"
[module.hugoVersion]
min = "0.40.0"
max = "0.50.0"
extended = true

Sure. Have I?

@bep Hm.... now I’m confused... isn’t what you call component1, component2 also each a module, i.e Go modules? It seems that there can only be one config entry of what you now call module. Is that
right?

@bep It seems so to me, but I guess you can explain...

[onedrawingperday]

@bep no Hugo modules for the Themes Site for now.

We will let you know me and @digitalcraftsman once we're comfortable with the Hugo Modules workflow, so that the Build Script can be adjusted to allow for Vendored Components.

[bep]

@larzza OK, so I may have used those words in "free text" to describe old vs new...

My thought was that a module is the wrapper with some configuration and some component imports ... But maybe we can use fewer words and do:

[component]
imports = ["component1", "component2"]
description = "Component n1 description"

I have certainly gone enough rounds on this to confuse myself from here to Rome.

[larzza]

@bep Yeah, I understand that... but there can only be one [component] block in the config file? Is the theme-concept that bad?

[theme]
imports = ["component1/module1, "component2/module2"]
description = "Component n1 

Or what about this?

[composition]
imports = ["component1/module1, "component2/module2"]
description = "Component n1 

[bep]

No, I personally love the theme word, I think it was @kaushalmodi who had some strong arguments ...

[regisphilibert]

I personnaly think the theme word refers to aesthetics. I try and ask those simple questions and always end up with a 🙅‍♂ .

• Is something that simply mashup good seo tags for your site a theme?
• Is something that adds a WP data source to your site a theme?

[larzza]

I think theme is better than component and module (I have forgot why it should be replaced).

But I also like composition (theme) and part (component) if things should be rebranded.

[kaushalmodi]

I think it was @kaushalmodi who had some strong arguments ...

It has been a while since I took part in this discussion.. back then I was suggesting to add theme_extensions: https://github.com/gohugoio/hugo/issues/4460#issuecomment-392296382

I agree with @regisphilibert that "theme" doesn't apply now as we do a lot more than just tweaking looks of a site.

[larzza]

I don’t think the word theme has to be interpreted as looks. It can have a broader meaning, for example when talking about a narrative.
https://en.m.wikipedia.org/wiki/Theme_(narrative)

[regisphilibert]

Well, you would agree though that in the web world, it has a very clear meaning.

In the end it's all about explaining to people what "this" do. Removing any confusing well known notion from the name seems important.

What Bjørn Erik is building is closer to a management for module/component/dependency/plugins/ than an solution for handling your site's theme/skin.

[larzza]

Well, you would agree though that in the web world, it has a very clear meaning.

Yes!

In the end it's all about explaining to people what "this" do. Removing any confusing well known notion from the name seems important.

I agree! Which is why, in the context of Hugo, it might be a good idea to keep the theme-name. And also the reason why I spend time on thinking about the matter.

What Bjørn Erik is building is closer to a management for module/component/dependenconcept.cy/plugins/ than an solution for handling your site's theme/skin.

That’s true too.

But I still think theme is better than module and component. And that compositionand part is an alternative terminology to consider.

[regisphilibert]

But I still think theme is better than module and component

Nothing I can do about what you "still" think :)

And that composition and part is an alternative terminology to consider.

Yes this also works.

[onedrawingperday]

I think that the following:

[theme]
imports = ["component1/module1, "component2/module2"]
description = "Component n1 

Makes the hierarchy pretty explicit i.e. Theme > Component > Module

So I agree with @larzza lets keep theme as an umbrella term.

[bep]

@onedrawingperday -- the "component1/module1" is a rather constructed hierarchy. I will sleep on it and probably do it my way ...

[onedrawingperday]

Sure. That was just me following the discussion. It's your call.

[regisphilibert]

I keep liking stack. It resonate a "list" of tools/parts you use.

title = "My Module"
[stack]
imports = ["component1", "component2"]
description = "Component n1 description"
[stack.hugoVersion]
min = "0.40.0"
max = "0.50.0"
extended = true

Also, I think the initial example is better, with module map including the name rather than relying on config.toml's title which should be reserved for the website's (available in site.Title).

[larzza]

While sleeping I realized it was just a missing ”s” that confused me in the initial proposal... so...

module -> modules/mods or components (or theme/composition)

title = "My Module"
[mods]       <==================================
imports = ["component1", "component2"]
description = "Component n1 description"
[mods.hugoVersion]
min = "0.40.0"
max = "0.50.0"
extended = true

[bep]

A stack has a very distinctive meaning in CS (push/pop) which does not match what I have in mind for this. Also, the configuration element we're looking for is singular, e.g. a module definition -- aka "the components imported into this module definition has these version restrictions", it's not an array.

I suspect we be better off using something completely different, though, e.g "the package definition", or even "the project definition":

[package]
imports = ["github.com/bep/hugo-components/myshortcodes", "github.com/bep/hugo-components/mypartials"]
[package.hugoVersion]
min = "0.40.0"
max = "0.50.0"
extended = true

Where then only metadata inside that config is technical data about the project (not meant to be rendered), e.g. version info, license metadata (for the theme site). This would be analogous to package.json -- which would be even more fitting if you pull it out into config/_default/package.toml.

OK, I think we need help from the great Hugo Community. Given the discussion above, what would be a cool and fitting name for this new configuration element.

[larzza]

@bep Didn´t [composition] (or maybe [compose]) even make it to the list of choices.. :-D

The more I think of it, it seems that a project/site leveraging the Hugo Module concept (even more so if content will be a module in the future) will, in the extreme case or maybe even for most common use cases(?), consist of just a config-file – everything else is a Hugo Module. That's why I, at the moment, think terms like project, composition is the better fit.

I also think that if you haven't followed along in the discussion and therefore might not have a "deeper" understanding of what Hugo Modules are and what they imply, you might just end up voting for a well known term... if that's good or bad, on the other hand, is something to think about.

[larzza]

Isn't [compose] a nice candidate.

You compose a Hugo project out of components/modules/plugins/....

(If you are a Docker user you can think of Docker Compose)

@bep @regisphilibert @onedrawingperday @digitalcraftsman @kaushalmodi

[brycewray]

I prefer package because I think it’s a more accurate descriptor of its purpose, but truthfully can see it either way.

[regisphilibert]

Everyone will instantly grasp package. That's for sure.

[jough]

package makes the most sense to me, since it’s a collection packaged together. I’m not sure that module has the same connotations. If anything, I might assume that a package consists of multiple modules.

[kaushalmodi]

Yep, compose was a good candidate. But in any case, this is too much bikeshedding .. either of package, module and compose are fine in IMO.

[DirtyF]

I'm fine with modules since it's the Go dependency management system.

[regisphilibert]

Note that it will be module, singular, to describe the system by which you import/order/define your set of components.

In node.js/npm terms, I think the module would be the package while the components are the dependencies.

I may be wrong though 🤔

[DirtyF]

Yeah right. I was referring to the generic term.

A module is a collection of Go Packages — https://blog.golang.org/using-go-modules

[larzza]

Go and Java (for example) thinks that a module is made of packages. Npm has reversed the concept, sort of, which is kind of strange... see details below.

The conclusion of this, I think, is that module is the winner between those two (on the other hand my guts tell me that package is better). But I don't like either because what we are doing here is to put together the final product – the project/site (a project can't be a part of another project as a module, can it?) – and technically we are gathering Hugo Modules which, for the moment at least, are Go modules which are a collection of Go packages.

That's why I think a term like project or compose is better. For one thing it would take us away from the module/package confusion.

npm

The npm registry contains packages, many of which are also Node modules, or contain Node modules.

A package is a file or directory that is described by a package.json file.
A module is any file or directory in the node_modules directory that can be loaded by the Node.js require() function.

Note: Since modules are not required to have a package.json file, not all modules are packages. Only modules that have a package.json file are also packages.

In the context of a Node program, the module is also the thing that was loaded from a file.

Go

A module is a collection of Go packages stored in a file tree with a go.mod file at its root. The go.mod file defines the module’s module path, which is also the import path used for the root directory, and its dependency requirements, which are the other modules needed for a successful build. Each dependency requirement is written as a module path and a specific semantic version.

A module is a collection of related Go packages that are versioned together as a single unit.

Summarizing the relationship between repositories, modules, and packages:

• A repository contains one or more Go modules.
• Each module contains one or more Go packages.
• Each package consists of one or more Go source files in a single directory.

Java

A module is a named, self-describing collection of code and data. Its code is organized as a set of packages containing types, i.e., Java classes and interfaces; its data includes resources and other kinds of static information.

[jough]

compose is a fine verb, but then the noun Hugo would use would be composition which may not be the clearest name. I think a good argument could be made for both package and module but a module is usually some code that does one thing.

As mentioned already, Node and Python think packages contain modules, Java and Go have it reversed, which doesn't make as much sense semantically but since Hugo is in Go, maybe the Go paradigms should win out, although I guess using either "package" or "module" is problematic if it doesn't conceptually match Go's use of the same terms.

I hate how generic project is but at least it's unambiguous.

[DirtyF]

since Hugo is in Go, maybe the Go paradigms should win.

At least @bep has a clear justification on why it's named like that : it's Go!

[bep]

And now I just have to find a way to hack into that polling thing so I can push module up, up ...

[DirtyF]

@bep That's exactly what Theresa May must have thought after the British referendum. 😭

[regisphilibert]

@bep you deserve to choose that name. And module is growing on me now :)

[jough]

@bep You're the one that decided to make the naming process democratic. You can always just decide. :)