Hugothemes: Hugo Themes that depend on Hugo Extended

[onedrawingperday]

@digitalcraftsman

Following the introduction of Hugo Pipes in 0.43 I am seeing theme submissions that rely on Hugo Extended features like this one:

{{ $style := resources.Get "scss/tale.scss" | toCSS | minify }}
<link rel="stylesheet" href="{{ $style.Permalink }}">

However with this setup a theme's demo will not be generated with the build script, because the Hugo site is currently deployed on Netlify and Hugo Extended is not supported there yet.

Also in my opinion a theme should work with the basic edition of Hugo.

I think that the README of the Themes repo and the theme submission issue checklist should be updated to let theme authors know that their theme will work with the basic edition of Hugo, if they commit the contents of /resources/ under the root of their theme.

Also see relevant comment by @bep https://github.com/gohugoio/hugoThemes/pull/394#issuecomment-408596955

[digitalcraftsman]

Hi Alexandros,

Netlify is using binrc to map a specified version to a binary. According to the README the resolutions looks for the binary at OWNER/REPO-NAME and looks for a binary that matches the version number set in the .netlify file.

I don't think they can distinguish between two binaries in the same release. However, for a CI service like Netlify it would make sense to use the extended version as default.

Hence we should add a (temporary) note to our README. However, why should a theme not use the features of the extended version for the theme demo? Once Netlify can use the extended version of Hugo I don't see any hurdles. But that are just my two cents.

[digitalcraftsman]

I opened an issue in the binrc repo. See https://github.com/netlify/binrc/issues/18

[onedrawingperday]

However, why should a theme not use the features of the extended version for the theme demo?

A theme with Hugo Extended features requires the installation of this version along with the relevant dependencies.

These themes will not work for people on the Hugo basic edition.

So there are two options:

1. Display a notice on the themes site so that users know that these themes are only for Hugo Extended.

OR

1. Ask theme authors to commit the contents of /resources/ after generating them so that these themes can work for people who are on the basic Hugo edition.

The choice is yours and @bep

[bep]

For now, a theme that uses Hugo Pipes must commit /resources to the theme.

[ghost]

For now, a theme that uses Hugo Pipes must commit /resources to the theme.

No concerns here. But in the case where resources is only used as a temp directory for piping out inline code (e.g. critical css) would having the resources directory checked into the theme still produce the expected result? (example inlining)

[bep]

@jhabdas I have no idea what you talk about, but it feels like it would fit better on the forum.

[onedrawingperday]

@jhabdas

You would need to commit a theme's /resources/ only if you had written your styles in SCSS and then used Hugo's transformation method toCSS to compile (these are the features that require Hugo Extended).

In the link you posted you don't use any of the above. So in your case there would be no need to commit /resources/ for your theme to work with the basic edition of Hugo.

[bep]

Let me put it this way: If I want to use pretty theme A I would be a little turned off if I had to install PostCSS and the extended version to get my site up and running. This will get even more obvious in the future when we get some dependency management in place.

Themes' styles should be considered stable.

There will we cases where you will want to recompile the SCSS, but it should be working out-of-the-box.

[EmielH]

I'm a newcomer to Hugo and its themes, so forgive me if this goes contrary to the way Hugo works. I've been following this thread as my theme is one of the themes that seems to have sparked this discussion.

I get the point that a _user_ of a theme should not have to compile SCSS as it should be considered stable.

As a theme developer, wouldn't it then be more correct to copy the CSS result of the pipes to /static/css and then refer to those files in the layout templates, instead of committing /resources/, which contains a _gen folder and fingerprinted files? The latter seems a bit 'hacky' to me, but, again, I'm new to Hugo so I could be completely wrong.

[bep]

The latter seems a bit 'hacky' to me

Why is that hacky? And what would be the suggested workflow if you want to copy the CSS to /static and use that for the theme? What if the user wants to modify the SCSS? Add his own color variables?

[EmielH]

It seems hacky to me because I am used to never committing generated resources; especially if they look generated, e.g. when they are placed in folders like _gen or have fingerprints in their filenames.

On the other hand, the workflow when copying to /static is far from ideal too: first the template needs to contain the pipes to generate the CSS, then you have to copy the generated CSS to /static and alter the template to refer to those files. If you then want to make a change, the template needs to be changed back to the version with the pipes, etc.

However, if the user wants to modify the SCSS, s/he will have the extended version of Hugo anyway and using pipes is no problem.

[bep]

I have had this discussion before. Committing /resources is perfectly fine for stable resources. Theme SCSS is a prime example. Not sure how fingerprinting has anything to do with this. In fact, doing it this way makes much more sense security wise. To generate SRI integrity hashes on some random server and not putting them under source control makes very little sense to me.

We need some more "workflow support" around this, but I'm not buying into some argument about "generated sources" not belonging in your GitHub repo.

[EmielH]

I wasn't trying to convince you, my apologies if my comments made it seem that I did! As a newcomer, I was trying to learn about the design choices and trying to think along, since both options didn't seem ideal to me. I will commit /resources to my theme, and I do agree that more workflow support for this would make things a bit easier!

[bep]

I wasn't trying to convince you, my apologies if my comments made it seem that I did!

No problem, It's just that I have seen similar comments coming from left and right. I think it helps to think that peoples' choice of workflows in this department is very individual.

Hugo Pipes was a big commit (it was one commit, which is also considered bad practice) -- and while we did have many discussions about how this should work, it is pretty clear that it wasn't the finished product. It's a little bit the same with the Theme Components -- it works on the technical level, but lots is missing in the work flow department.

[EmielH]

I'd be glad to help and think along, as I was planning to use Theme Components as well -- but I'm going off topic. Thanks for your explanations!

[onedrawingperday]

@digitalcraftsman So for now as @bep said theme authors who use Hugo Pipes features like toCSS and PostCSS need to commit the /resources/ directory for their themes to work in the basic edition of Hugo.

I think that this issue needs to be closed.