Lessons learned

General note: This site’s appearance, configuration, hosting, and other basic considerations will change over time. As a result, certain content on this page could be at variance with what you’re currently seeing on the site, but the two were consistent when this post originally appeared.

Before I delve into today’s clambake, I must extend my hearty thanks to the Hugo community for its friendly reaction to my last post, which concerned my abortive and, ultimately, wrong-headed attempt to migrate this site from Hugo to Gatsby. The day after I published the post, the Hugo Twitter account retweeted my announcement of the post, provoking a big spike in readership¹ — and quite a few retweets and friendly tweets from Hugo aficionados.

Thanks, folks. I had feared you might not appreciate my attempt to stray from the ranch, but you were very accepting of my reasoning and, to be sure, kind in your replies. I do appreciate it.

As for the dalliance itself: it wasn’t a total waste of my time. I learned some valuable lessons, which I want to share in this post. Not all are specific to a question of one SSG vs. another, mind you.

In fact, that’s the case for the first item.

Don’t mix Git and cloud sync

From the beginning, I’d had my local Hugo directory set up for cloud storage — first with Dropbox, which I’ve since punted², then with iCloud Drive — and hadn’t encountered any issues. However, it turns out I’d been lucky.

While I was trying Gatsby, I had its directory in iCloud Drive also, and soon saw that, occasionally, files I killed would come back, irrespective of what I’d done in the Git repository. Mystified, I did some research and found that there was a very good reason not to do that: in essence, using cloud sync with a Git repo is a bad idea.

So, now, I keep my Hugo directory in a drive that’s not sync’d with the cloud. Of course, it definitely is fully backed up as well as pushed to a remote repo. In fact, I now have it in three different remote repos: not only the original Bitbucket repo which feeds the site to Netlify but also repos on GitHub and GitLab.³

Oh, the typography

If you read that last post, you know the ultimate straw that caused me to cancel the whole thing with Gatsby came when I found its handling of on-screen typography to be erratic after I’d attempted to install MDX compatibility. As I made clear last year, typography is a big deal with me, no less on the web than anywhere else, so that was the final show-stopper.

Well, I want to tell you: in my admittedly limited research, I found this to be a problem with many of the newer SSGs.

More often than not, they lack — and their developers show almost a nonchalance about the importance of — “smart” typography (e.g., see this regarding the oddly Hugo-like Zola SSG). So, if you can put up with . . .

goofy-lookin' "punctuation" like this

. . . as opposed to . . .

nice-lookin’ “punctuation” like this

. . . fine. I choose otherwise.

Then there’s the whole issue of how the newer SSGs handle CSS and SCSS/Sass.

First, understand how easy we Hugo users have it where SCSS/Sass compatibility is concerned. Thanks to the out-of-the-box Hugo Pipes functionality, all you have to do is put your SCSS/Sass files in your Hugo install’s /assets directory and then call to them in templates like this (this is from my own templates, with ofotigrid.scss⁴ being the name of my primary SCSS file that @imports in content from its fellow SCSS files within /assets/scss):

<!-- CSS/SCSS -->
{{ $sass := resources.Get "scss/ofotigrid.scss" }}
{{ $style := $sass | resources.ToCSS }}
<link rel="stylesheet" href="{{ $style.RelPermalink }}">

(Note: If you’re bothered by the Go code in there, you’re apparently not alone. I’ll address that below.)

Many other SSGs make this sort of thing considerably more problematic, especially if you’re not willing to craft your own pipeline between the SSG and the CSS or SCSS/Sass files, through either plugins or other methods. (I already told you my luck with plugins, especially when there are a whole slew of them in the SSG’s config files.) Believe me, I am neither willing nor (likely) able.

Even the documentation for an SSG like Eleventy that claims to be much easier and more more logically configured than other JavaScript-based SSGs — and, in many ways, it is — makes it highly obscure in how you’re supposed to make that capability work, at least if you want to follow (in my opinion) good form and have separate files for your CSS and SCSS/Sass, rather than inlining that code. Indeed, if you go poking around the page source from numerous sites built on the newer SSGs, you’ll find a ton of inline CSS in the <head> section. Argggh.

I’ll have more to say later about the shortcomings of SSGs’ documentation. Even Hugo’s.

Because, so far, I’ve been able to land punches with glee on The Other Guys; but, unfortunately, the latter two main points leave their marks on Hugo, too.

Language barriers

In case you’ve been under the impression that SSGs are built for developers and not for “normal” people, you’re not alone. This article makes a number of good points, and some of them hurt because the author steps on many toes, including Hugo’s.

One of those toe-thumpers is about the templating languages involved, and the Go language on which Hugo is based catches a lot of heat from many. If you want a few examples, some of which are complimentary of Hugo itself but not the need to deal with Go: look here and here and here and here (that last one is really about Go itself and mentions Hugo only once, but is still germane to this topic).

I grant you that Go isn’t pretty for those of us who have no reason to deal with it except when we make changes to Hugo templates. However, in Hugo’s defense, I would only suggest to you these examples of how even code-savvy people, much less non-devs, can come a-cropper when trying to configure some of the newer SSGs.

In short: it’s not just a Hugo problem. It’s a problem with SSGs themselves. And I doubt it’ll go away any time soon. However, to be fair: if you’re gonna do any serious configuration of WordPress or Drupal, just to name two of the Old Guard, you need to use PHP. Good luck with that to This Generation Which Knoweth Not Server-Side Languages. Until and unless somebody invents an SSG that is designed for non-devs, this is going to keep being a fly in the ointment for those folks, and even some devs.

Which brings me, finally, to . . .

Docs are a nearly universal problem

Yes, we have to talk about SSGs’ documentation. It pretty much all sucks for non-devs — Hugo’s, too, although I would say Hugo’s sucks less, probably because it’s been around several more years than many of the other SSGs that hold more prominence these days, and thus there’s been more time for people to write and tweak the docs.

In one of my past Work Lives, I wrote user manuals for fax machines. (Obviously, this was a long time ago.) Our team prided ourselves on “writing for Grandma,” as we put it then, because our products were bought by people of all ages and experience levels.⁵ Thus, I am acutely aware how far short SSGs’ docs fall when it comes to being understandable by people outside the narrow circle of their own community, and sometimes even some within it.

For example, here’s an excerpt from the Gridsome documentation for doing layouts, surely a core part of learning to use an SSG:

Layout components are used to wrap pages and templates. Layouts should contain components like headers, footers or sidebars that will be used across the site.

So far, fine. Then . . .

Layouts are just .vue components located in src/layouts and need to be declared as a global component or imported per page to be used.

Assuming you’re not a dev, go ahead and re-read that. I’ll wait.

At some point, the SSG folks will have to decide whether they do indeed want to maintain their role as Merlins rather than making SSGs accessible to ordinary users, particularly in corporate life. I mean, WordPress is a God-awful, performance-eating, security-defying thing — but at least your average Joe or Jane, and most notably your average Joe or Jane in corporate settings that aren’t going to hire dev help for them, can use it. Try that with any SSG.

A parting shot

So, yes, I learned a lot of things I hadn’t expected to learn, or in some cases wanted to learn. But I thought they were worth bringing to your attention, so there you are. I hope you find them useful.

I have no particular place for this one last note, so I’ll just toss it in here at the end: you’ll find either insight, or humor, or perhaps both in this Twitter thread about the drawbacks of the many JavaScript “framework”-based SSGs that are Kewl today.

Discuss.

Latest commit (08cb79e2) for page file:
2023-04-17 at 6:18:22 PM CDT.
Page history