Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Consolidate theme.toml and config.toml, add a module config section etc. #5996

Closed
bep opened this issue May 29, 2019 · 44 comments

Comments

@bep
Copy link
Member

commented May 29, 2019

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

@bep bep added the Enhancement label May 29, 2019

@bep bep added this to the v0.56 milestone May 29, 2019

@bep bep self-assigned this May 29, 2019

@onedrawingperday

This comment has been minimized.

Copy link
Contributor

commented May 29, 2019

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

This comment has been minimized.

Copy link

commented May 29, 2019

@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

This comment has been minimized.

Copy link
Member

commented May 29, 2019

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

This comment has been minimized.

Copy link
Member Author

commented May 29, 2019

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

This comment has been minimized.

Copy link
Contributor

commented May 29, 2019

@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

This comment has been minimized.

Copy link

commented May 29, 2019

@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

This comment has been minimized.

Copy link
Member

commented May 29, 2019

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

This comment has been minimized.

Copy link
Member Author

commented May 29, 2019

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

Sure. Have I?

@onedrawingperday

This comment has been minimized.

Copy link
Contributor

commented May 29, 2019

@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

This comment has been minimized.

Copy link
Member

commented May 29, 2019

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

This comment has been minimized.

Copy link

commented May 29, 2019

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

This comment has been minimized.

Copy link
Contributor

commented May 29, 2019

@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

This comment has been minimized.

Copy link
Member Author

commented May 29, 2019

@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

This comment has been minimized.

Copy link

commented May 29, 2019

@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

This comment has been minimized.

Copy link
Member Author

commented May 29, 2019

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

@regisphilibert

This comment has been minimized.

Copy link

commented May 29, 2019

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

This comment has been minimized.

Copy link

commented May 29, 2019

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

This comment has been minimized.

Copy link
Member

commented May 29, 2019

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: #4460 (comment)

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

@larzza

This comment has been minimized.

Copy link

commented May 29, 2019

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

This comment has been minimized.

Copy link

commented May 29, 2019

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

This comment has been minimized.

Copy link

commented May 29, 2019

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 composition and part is an alternative terminology to consider.

@regisphilibert

This comment has been minimized.

Copy link

commented May 29, 2019

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

This comment has been minimized.

Copy link
Contributor

commented May 29, 2019

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

This comment has been minimized.

Copy link
Member Author

commented May 29, 2019

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

@onedrawingperday

This comment has been minimized.

Copy link
Contributor

commented May 29, 2019

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

@regisphilibert

This comment has been minimized.

Copy link

commented May 30, 2019

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).

bep added a commit that referenced this issue Jun 3, 2019

Add Hugo Modules
Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940

bep added a commit that referenced this issue Jun 10, 2019

Add Hugo Modules
Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940

bep added a commit that referenced this issue Jun 10, 2019

Add Hugo Modules
Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940

bep added a commit that referenced this issue Jun 10, 2019

Add Hugo Modules
Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940

bep added a commit that referenced this issue Jun 11, 2019

Add Hugo Modules
Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940

bep added a commit that referenced this issue Jun 16, 2019

Add Hugo Modules
Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940

bep added a commit that referenced this issue Jun 18, 2019

Add Hugo Modules
Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940

bep added a commit that referenced this issue Jun 18, 2019

Add Hugo Modules
Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940

bep added a commit that referenced this issue Jun 20, 2019

Add Hugo Modules
Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940

bep added a commit that referenced this issue Jun 21, 2019

Add Hugo Modules
Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940

bep added a commit that referenced this issue Jun 26, 2019

Add Hugo Modules
Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940

bep added a commit that referenced this issue Jun 26, 2019

Add Hugo Modules
Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940

bep added a commit that referenced this issue Jun 28, 2019

Add Hugo Modules
Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940

bep added a commit that referenced this issue Jul 3, 2019

Add Hugo Modules
Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940

bep added a commit that referenced this issue Jul 5, 2019

Add Hugo Modules
Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940

bep added a commit that referenced this issue Jul 6, 2019

Add Hugo Modules
Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940
Fixes #6074

bep added a commit that referenced this issue Jul 10, 2019

Add Hugo Modules
Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940
Fixes #6074
Fixes #6082

bep added a commit that referenced this issue Jul 10, 2019

Add Hugo Modules
Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940
Fixes #6074
Fixes #6082

bep added a commit that referenced this issue Jul 17, 2019

Add Hugo Modules
Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940
Fixes #6074
Fixes #6082

bep added a commit that referenced this issue Jul 19, 2019

Add Hugo Modules
Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940
Fixes #6074
Fixes #6082
Fixes #6092

bep added a commit that referenced this issue Jul 21, 2019

Add Hugo Modules
Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940
Fixes #6074
Fixes #6082
Fixes #6092

bep added a commit that referenced this issue Jul 22, 2019

Add Hugo Modules
Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940
Fixes #6074
Fixes #6082
Fixes #6092

bep added a commit that referenced this issue Jul 23, 2019

Add Hugo Modules
Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940
Fixes #6074
Fixes #6082
Fixes #6092

bep added a commit that referenced this issue Jul 24, 2019

Add Hugo Modules
This commit implements Hugo Modules.

This is a broad subject, but some keywords include:

* A new `module` configuration section where you can import almost anything. You can configure both your own file mounts nd the file mounts of the modules you import. This is the new recommended way of configuring what you earlier put in `configDir`, `staticDir` etc. And it also allows you to mount folders in non-Hugo-projects, e.g. the `SCSS` folder in the Bootstrap GitHub project.
* A module consists of a set of mounts to the standard 7 component types in Hugo: `static`, `content`, `layouts`, `data`, `assets`, `i18n`, and `archetypes`. Yes, Theme Components can now include content, which should be very useful, especially in bigger multilingual projects.
* Modules not in your local file cache will be downloaded automatically and even "hot replaced" while the server is running.
* Hugo Modules supports and encourages semver versioned modules, and uses the minimal version selection algorithm to resolve versions.
* A new set of CLI commands are provided to manage all of this: `hugo mod init`,  `hugo mod get`,  `hugo mod graph`,  `hugo mod tidy`, and  `hugo mod vendor`.

All of the above is backed by Go Modules.

Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940
Fixes #6074
Fixes #6082
Fixes #6092

bep added a commit that referenced this issue Jul 24, 2019

Add Hugo Modules
This commit implements Hugo Modules.

This is a broad subject, but some keywords include:

* A new `module` configuration section where you can import almost anything. You can configure both your own file mounts nd the file mounts of the modules you import. This is the new recommended way of configuring what you earlier put in `configDir`, `staticDir` etc. And it also allows you to mount folders in non-Hugo-projects, e.g. the `SCSS` folder in the Bootstrap GitHub project.
* A module consists of a set of mounts to the standard 7 component types in Hugo: `static`, `content`, `layouts`, `data`, `assets`, `i18n`, and `archetypes`. Yes, Theme Components can now include content, which should be very useful, especially in bigger multilingual projects.
* Modules not in your local file cache will be downloaded automatically and even "hot replaced" while the server is running.
* Hugo Modules supports and encourages semver versioned modules, and uses the minimal version selection algorithm to resolve versions.
* A new set of CLI commands are provided to manage all of this: `hugo mod init`,  `hugo mod get`,  `hugo mod graph`,  `hugo mod tidy`, and  `hugo mod vendor`.

All of the above is backed by Go Modules.

Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940
Fixes #6074
Fixes #6082
Fixes #6092

bep added a commit that referenced this issue Jul 24, 2019

Add Hugo Modules
This commit implements Hugo Modules.

This is a broad subject, but some keywords include:

* A new `module` configuration section where you can import almost anything. You can configure both your own file mounts nd the file mounts of the modules you import. This is the new recommended way of configuring what you earlier put in `configDir`, `staticDir` etc. And it also allows you to mount folders in non-Hugo-projects, e.g. the `SCSS` folder in the Bootstrap GitHub project.
* A module consists of a set of mounts to the standard 7 component types in Hugo: `static`, `content`, `layouts`, `data`, `assets`, `i18n`, and `archetypes`. Yes, Theme Components can now include content, which should be very useful, especially in bigger multilingual projects.
* Modules not in your local file cache will be downloaded automatically and even "hot replaced" while the server is running.
* Hugo Modules supports and encourages semver versioned modules, and uses the minimal version selection algorithm to resolve versions.
* A new set of CLI commands are provided to manage all of this: `hugo mod init`,  `hugo mod get`,  `hugo mod graph`,  `hugo mod tidy`, and  `hugo mod vendor`.

All of the above is backed by Go Modules.

Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940
Fixes #6074
Fixes #6082
Fixes #6092

bep added a commit that referenced this issue Jul 24, 2019

Add Hugo Modules
This commit implements Hugo Modules.

This is a broad subject, but some keywords include:

* A new `module` configuration section where you can import almost anything. You can configure both your own file mounts nd the file mounts of the modules you import. This is the new recommended way of configuring what you earlier put in `configDir`, `staticDir` etc. And it also allows you to mount folders in non-Hugo-projects, e.g. the `SCSS` folder in the Bootstrap GitHub project.
* A module consists of a set of mounts to the standard 7 component types in Hugo: `static`, `content`, `layouts`, `data`, `assets`, `i18n`, and `archetypes`. Yes, Theme Components can now include content, which should be very useful, especially in bigger multilingual projects.
* Modules not in your local file cache will be downloaded automatically and even "hot replaced" while the server is running.
* Hugo Modules supports and encourages semver versioned modules, and uses the minimal version selection algorithm to resolve versions.
* A new set of CLI commands are provided to manage all of this: `hugo mod init`,  `hugo mod get`,  `hugo mod graph`,  `hugo mod tidy`, and  `hugo mod vendor`.

All of the above is backed by Go Modules.

Fixes #5973
Fixes #5996
Fixes #6010
Fixes #5911
Fixes #5940
Fixes #6074
Fixes #6082
Fixes #6092

@bep bep closed this in #5960 Jul 24, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
9 participants
You can’t perform that action at this time.