Why are user customizations supposed to be made under themes/my-doks-theme/ and not in top-level dirs?

[salim-b]

Hyas (or the respective file structure in create-hyas) instructs to put user customizations under themes/my-XYZ-theme/ instead of just using the Hugo project's top-level dirs. IMHO this unnecessarily complicates the setup (two instead of one place for users to customize files). Any particular reason for this?

Moving all the Hugo component folders from themes/my-XYZ-theme/ two levels up would be more intuitive I think. It would also allow us to cut down module config by two entries per Hyas theme.

[h-enk]

Any particular reason for this?

Follow Hugo's site skeleton and keep themes override things separated.

Note that in line with that, there's an integrations directory for integrations overrides.

I'm not sure what's more intuitive (keep things separated or all in one place) and what setup minimizes possible conflicts best?

[h-enk]

[..] I think it's a worthwhile goal to keep it as simple and standard-conformant as possible. [..]

Agreed.

To conclude things and make a decision going forward, I think the common current practice should guide us here.

When you come from Drupal or WordPress, the themes and plugins (or integrations) directories make sense. However, when you come from Hugo or other Node.js frameworks (like e.g. 11ty and Astro) not so.

Since Hyas' main user base will be rooted in Hugo, I think we should follow Hugo's way, id est use the root component folders — only.

Do you want to tackle this yourself or would you welcome a PR?

I will do this then.

[pensivedog]

I'm an amateur and perfectly happy to defer to others in this discussion. My interest is in ensuring the sites I build with Hyas can be easily updated to benefit from future Hyas improvements, and that I can refer to Hugo documentation when working on my Hyas-based sites.

I think we should follow Hugo's way, id est use the root component folders — only

At a glance, including a themes directory seems to be the Hugo way. Other than this thread, is there any official discussion of deprecating the themes directory in Hugo?

Hugo's directory structure and site skeleton include a themes directory and themes are still included in official Hugo documentation. In my understanding, which is admittedly quite limited, the themes directory provides modularity by allowing theme inheritance and keeping theme components separate from the rest of a Hugo site. Wouldn't removing the themes directory remove some modularity, or make it more complicated to achieve?

In my experience, the themes directory also seems to be widely used in community and premium themes.

There's a lot I don't understand about Hugo and best practices of Hugo developers, so my apologies if I've added extraneous detail to this discussion.

[h-enk]

The actual Doks theme (Doks core) lives in the node_modules/@hyas/doks-core folder. You could look at it as a Hugo themes subfolder (theme) and think of it as a parent theme. The module can easily be updated for future improvements.

The themes (and integrations) directories were added for customizations/overrides (think child theme) only — so not fully in line with the Hugo way.

With the new setup, modularity is still there — at the main level — and more in line with the Hugo way.

[salim-b]

My interest is in ensuring the sites I build with Hyas can be easily updated to benefit from future Hyas improvements,

Your site will be as easily updateable if you use the top-level folders for customizations as it was when using the themes/ subfolder. In both cases you will automatically benefit from updates to doks-core when running npm update, and in both cases you'll need to manually incorporate improvements to the default configuration in create-hyas, like gethyas/create-hyas#27 for example.

and that I can refer to Hugo documentation when working on my Hyas-based sites.

Official Hugo documentation should totally apply if you're using top-level dirs.

At a glance, including a themes directory seems to be the Hugo way.

As I explained, not necessarily anymore. It depends on how your site is configured to use the theme. Using the themes dir the (old) Hugo way would necessarily include setting theme = [ "my-doks-theme" ] in your project's main hugo.toml config file and incorporating the whole theme directly in themes/my-doks-theme/ either via Git submodules or copying files.

Doks opts for a more powerful and user-friendly approach by using mounts from the more modern Hugo modules infrastructure instead of the themes subfolder and does not use Hugo's theme config option.

So no, Doks current folder duplication is not the Hugo way as I see it.

In my experience, the themes directory also seems to be widely used in community and premium themes.

Yes, that's true and probably in partial due to how outdated/incomplete Hugo's official docs are. For example the Theme components chapter has an info notice at the top saying

This section contain information that may be outdated and is in the process of being rewritten.

That notice was added 4 years ago by the great guy who mainly developed Hugo modules but at the same time didn't care too much about doing the necessary documentation refactoring and resolvement of conceptual conflicts (bep, Hugo's current lead dev). This may also be because Hugo's documentation is to a much further degree a community project with many more contributors than the underlying Hugo Go codebase. And bep seems to be too reticent regarding refactorings of documentation sections he didn't write himself.

Note that the old themes-way of configuring a Hugo site without Hugo modules will most likely continue to work for another decade or more since Hugo devs really like to stay backwards compatible if possible.

There's a lot I don't understand about Hugo and best practices of Hugo developers, so my apologies if I've added extraneous detail to this discussion.

Don't worry, sober deliberation is always a promising path to insight. 🙂

[pensivedog]

Thank you both for clarifying all these details!