Hugo Lacks SCSS

Hugo’s Missing Parts

Hugo doesn’t support SCSS, which is really a shame for me. The Hugo community does have plenty of support for Themes and CSS, but if you want to build themes or use materials from other SCSS frameworks you’re on your own.

Well, you have me but I’m just one dude. If you like you can let other smart people build stuff for you. While that’s nice, I’m a bit of a control freak - I like to build things myself, and I assume a lot of other people do too.

If you follow the Hugo walk-through like I did, you soon come upon something called “themes” and if you’re anything like me, then you ask “I wonder how easy it is to make my own theme.” And before you answer that question you’ll say “I totally want to make my own theme.” How easy is it? The answer depends.

• Do you like CSS?
• Do you like any CSS preprocessor?

If you lean towards the former, you’re either a CSS master, old guard, or you’ve already got a CSS pipeline up and ready. If you’re like me, and you want to use SCSS to modify some frameworks you already know, then you’re going to have to set up that pipeline yourself.

It’s not spelled out in the documentation. In fact, when I read it the documentation really felt like it was saying you could use SCSS or SASS right out of the box. Until push came to shove and I had to deep dive, and eventually I bottomed out when I found out you basically need to add a pipeline for SCSS.

Unfortunately, I don’t know if the other popular static site generators are just as difficult to wrangle. What I ended up doing getting a Webpack pipeline and start using Hugo in spite of itself, which I’ll admit was a bit fun.

Hugo’s Middling SCSS Support

Hugo does support pipes and minification, and I guess if your SCSS library of choice doesn’t use all of the features that the preprocessor provides, you may be good to go.

How would you know if your library works? Your guess is as good as mine, the Hugo documentation also doesn’t say which version of Sass it supports, nor which projects it uses to interpret your SCSS (not in the documentation at least).

You can avoid this pain by going down the “Don’t do anything yourself,” model. For me that’s not as fun. One of the reasons I made this site was to have a project that I built myself. It’s not really about getting a platform, or building a brand. The more I use Hugo, the more I find that I’ll really need to hack at it. But oh boy is it hackable.

Bridging the Gap

What I ended up doing was building this out in Webpack. When I bring up Webpack to my buddies, usually they try to get as much distance from me as possible. I don’t hang out with web developers, but hey Webpack isn’t that bad. It’s quite hefty but it’s disappointing that Hugo “The world’s fastest framework for building websites” can’t handle the tools I want to use; I’d rather not have to need Webpack if I’m honest.

It’s been almost two years since @use was created, and the running commentary is “Sass isn’t going to drop @import so it’s fine.” sure. If you can’t tell, I’m a little salty about the whole ordeal. Luckily I’ve gotten it working for a while now, and it’s all the better. I learned a lot about Webpack, and once again the Hugo forums and community is the bulwark of the whole project.

How to improve Hugo

Well, full SCSS support would be one way. Unfortunately this is tied up in another project who’s implementing an SCSS interpreter apart from the normal Node / Dart / Ruby gang. So I could try and pick up yet another project, or wait for that project to clear up this problem.

Honestly, fixing other tech on other projects is the right direction: with these free and open-source projects out there in the open, if you’re missing a feature and it’s got an open issue flag, you should develop it! But really, I don’t have the time set aside for that right now. I’m also a terrible C++ / Go programmer, so I wouldn’t hold my breath on me fixing this myself.

Documentation is also sticky. What really got me is that I have to really dive in to get to know how to do simple things, like get all of my assets in a row, or get my SCSS framework to work correctly. It’s still not clear to me how I’m intended to use themes. It’s implied that they’re modular, and you can modify them. The truth is most themes are opaque and convoluted. In my opinion, it’s easier to roll your own if you have a vision. If you don’t have a vision, or if someone had a better idea and already built it out, then good for you: one of those themes will probably work out great for you.

What’s broke

So, what if you want to use SCSS pipes in Hugo?

Here are some of the sticking points I ran across while fixing this myself:

• @use isn’t supported in the SCSS compiler hugo provides, so SCSS isn’t fully supported no matter how you slice it. If you want to use a Style library that uses the @use function, you’re out of luck with vanilla Hugo
• The final structure of the published directory isn’t clear from the documentation. What I had to do was work by trial and error and it worked.
• Modules and how load order works is a maze from the documentation. There are a lot of lists about ‘default load orders’ for all sorts of things. I really had to learn this part by myself.
• When ‘missing’ resources, it’s nearly impossible to tell what Hugo does see. When I was trying to use the material-components library (which was futile since Hugo doesn’t support SASS) it’d be a half-and-half hodgepodge of various errors. The errors didn’t really help out too much.

So if these seem easy to you, or if you’ve already solved them on your site, then please send send me an email about your blog so I can link it here - you’d probably know how to talk about these things better than me!