Ensure a smooth transition for existing docsy-as-submodule users #848

[deining]

This PR solves #848. It implements the following behaviour:

Using docsy as git submodule

hugo serve

Using docsy as hugo module

hugo serve --environment module

This PR works as of hugo version 0.84. With this version, hugo learned to make proper use of the config directory inside themes. This is the minimum required version when using docsy theme as module. Using docsy as submodule might work with earlier versions, too, which is good since the majority of sites will still run docsy as submodule.

[chalin]

Thank you for adding the READMEs and the useful links and explanations that they contain.

This solution seems promising, but I'm concerned that it won't work for projects who want to use modules in a production environment. Might we have to revert to using multiple config files instead?

[deining]

This solution seems promising, but I'm concerned that it won't work for projects who want to use modules in a production environment.

Can you elaborate con your concerns a bit, please? What are you exactly concerned about? Why do you think that a multiple config approach might be more promising?

[chalin]

Can you elaborate con your concerns a bit, please? What are you exactly concerned about?

Some docsy code makes use of hugo.IsProduction (a feature that was added by gohugoio/hugo#6953). As far as I can tell, there can be only a single value for hugo.Environment, so setting it to module prevents projects from using production in production builds, etc. Does that make sense?

Unless we can find a way to allow hugo.IsProduction to be true while still using Docsy as a module, we won't be able to use the config directory approach.

Why do you think that a multiple config approach might be more promising?

I don't know if using multiple config files will work, but it would be worth exploring. WDYT?

[deining]

Some docsy code makes use of hugo.IsProduction (a feature that was added by gohugoio/hugo#6953). As far as I can tell, there can be only a single value for hugo.Environment, so setting it to module prevents projects from using production in production builds, etc. Does that make sense?

Yes, I see the point.

Unless we can find a way to allow hugo.IsProduction to be true while still using Docsy as a module, we won't be able to use the config directory approach.

I like the config directory approach, so I tried to make in work in another way: we now do have two config directories and we can use hugo's --configDir option to select one. That's how it is supposed to work:

Using docsy as git submodule

hugo serve --configDir configTheme

Using docsy as hugo module

hugo serve --configDir configModule

Empty default config directory at the beginning, the user has to give --configDir to get it up and running. After successful installation, the user may symlink config directory to one of both directories to make it the default way of running.
Checks are failing now for this PR, this in on purpose. Not being able to start up the site in the default setting via hugo serve may sound harsh at first glance, but I see three advantages:

• both installation types (submdule/module) are equivalent, no need to discuss about the recommended way of installation, and
• the installation will get fail safe this way. With --environment flag approach, it you want to have module installation type and forget to add -e module at intial startup, I have seen weird things happen (pulling in bootstrap 5, ...). I'm afraid that users who haven't dealt with hugo modules already before can get easily lost here.
• inside the empty config dir, we can put file README.txt, explaining how to make either submodules or modules the default. With multiple config files, that wouldn' t work out that well.

@chalin, WDYT? If you like it, I will start testing my new approach.

[chalin]

That's a very interesting proposal! Let me think about it and get back to you shortly.

[chalin]

For my detailed feedback, see #848 (comment).

[LisaFC]

I like the config directory approach, so I tried to make in work in another way: we now do have two config directories and we can use hugo's --configDir option to select one. That's how it is supposed to work:

Using docsy as git submodule

hugo serve --configDir configTheme

Using docsy as hugo module

hugo serve --configDir configModule

Ooh, that's a very interesting approach, though does it mean that if you just run hugo serve nothing will happen? Is there a way to make our current "submodules" behaviour the default as it means it won't break people's continuous deployment (including ours)?

[deining]

Ooh, that's a very interesting approach, though does it mean that if you just run hugo serve nothing will happen?

Yes, in its current form, nothing happens, which will break existing build. Not good, no option at all.

Is there a way to make our current "submodules" behaviour the default as it means it won't break people's continuous deployment (including ours)?

There certainly is a way: we simply copy config.toml from configTheme the into site root. This will bring back the default submodule functionality to docsy, this is a must since we don't want to break existing builds. The question now is: with this file added, are we still allowed to use docsy theme as hugo module. I have a way in mind, but I'm not sure that it works. I need to test it. Fortunately I do have a playground branch on my own, this wasn't the case in the past. I will come up with the results shortly.

[LisaFC]

Thanks @deining, it feels like this is the right way to go!

[deining]

This PR is superseded by #871.