DEV Community: Bryce Wray

Leaving Google Domains for Porkbun

Bryce Wray — Fri, 16 Jun 2023 16:39:14 +0000

Out of the clear blue yesterday came an announcement that Squarespace had agreed to buy Google Domains from Google’s parent company.

Having been a satisfied customer of Google Domains for several years, I was not pleased — but, fortunately, I’d already suspected something like this might happen someday, so I had an exit strategy ready to go.

(Incidentally, my discomfort with this surprising news was by no means unusual among my fellow nerds.)

I’d long admired Google Domains' technical excellence, transparent pricing, and (relatively) good GUI; but Google is infamous for shutting down even popular projects, so I knew I needed to be ready in case Google Domains ever wound up on the death list.

More on that shortly, after I clear up one item which may otherwise seem to blunt the impact of this event. That’s because, in this case, Google isn’t killing Google Domains. It’s selling it — to a company that typically charges quite a bit more.

“Oh,” you might say, “but didn’t the announcement promise that, once the deal had gone through, pricing wouldn’t change right away for existing Google Domains customers?” Yep, it sure did:

Under the terms of the agreement, Squarespace will honor all existing Google Domains customers’ renewal prices for at least 12 months following the closing of the transaction . . .

And that sounds fine, but let’s finish that sentence:

. . . as well as provide additional incentives to encourage Google Domains customers to build a website with Squarespace and adopt other Squarespace offerings.

Alert! Upsells incoming! Those with PTSD from hosting companies like GoDaddy and Bluehost — not to mention “We’re so cheap in the first year (so we can screw you thereafter)” come-ons from cell service providers — should shield yourselves!

Uh, no. Just no. Not now; not ever.

(Besides: as a web dev nerd, I have a general objection to the Squarespaces of the world, as you might have detected in 2021’s “Easy-peasy.”)

Anyway, back to that aforementioned exit strategy . . .

I’d noticed that, whenever people on Hacker News debate the merits and demerits of various domain registrars, one called Porkbun seemed to get a lot of love. After doing some research of my own and confirming that Porkbun looked like a good choice, I decided to give it a try.

At the time, I had three different domains on Google Domains but I’d never actually used one of those domains for anything, so transferring it to Porkbun proved a pretty safe way to sample the experience. Porkbun’s marketing is perhaps a little too playful for my old-curmudgeon-like tastes, but the company does the real domains-handling stuff quite well, and at very fair pricing that I’ve found about as transparent as Google’s has been. Moreover, the people behind it seem to be genuinely nice, honest folks.

So, after getting wind yesterday of the Google Domains sale, I promptly moved the other two domains to Porkbun.

I’m not getting a dime to say this; but, if you, too, need to find a domain registrar (even if you couldn’t care less about what’s happening with Google Domains), I can highly recommend Porkbun.

Hugo and Tailwind: peace at last (maybe)

Bryce Wray — Sat, 03 Jun 2023 17:45:04 +0000

In the beginning, there were the Hugo static site generator (SSG) and the Tailwind CSS styling framework. Separately, they were great; but, when you tried to put them together, things got complicated. Now, it appears, that’s been resolved. [Pinky-swear.]

Things first got weird between Hugo and Tailwind early in 2021, when v.2 of the latter included a just-in-time (JIT) compiler. At first, JIT was opt-in, then opt-out, and, since v.3, has been thoroughly baked into Tailwind. The problem has been that Tailwind/JIT just didn’t work all that smoothly with Hugo Pipes, Hugo’s built-in assets-handling pipeline, especially during development.

In November, 2021, I described a community-created, albeit somewhat convoluted, procedure that got Hugo to work with Tailwind v.2. However, only a few weeks later, the Tailwind folks brought out v.3. Again, the Hugo community adapted and, before long, I was able to explain a smoother procedure that worked if paired with Tailwind v.3.0.11 or newer (within v.3, of course; more on that later). Still, these solutions admittedly were hacks, necessary only because the Hugo team hadn’t yet managed to deliver an official fix for the glitch — albeit not for lack of trying, to be fair.

That changed with the recent release of Hugo v.0.112.0. Its major enhancement was a new build.cachebusters option that was targeted at, finally, solving the whole Hugo/Tailwind/JIT problem. Here’s a summary of how each product is to be configured as a result, given the example in that link.

Hugo (in development mode):
- Constantly updates the hugo_stats.json file, which automatically tracks the project's HTML tags, CSS classes, and IDs.
- Uses the build.cachebusters settings, including for files “watched” by Tailwind, to tell Hugo when to update the dev server.
Tailwind CSS:
- “Watches” the hugo_stats.json file, as well as the other usual locations, to trigger JIT-based changes in the CSS output during Hugo’s development mode.

Update, 2023-06-05: The example code provided in the Hugo v.0.112.0 release notes seems to assume the use of Hugo Modules. I initially thought that, if not using them, you wouldn’t need the module settings to make this work. However, I’ve since learned otherwise.

And I can tell you that it works quite well. I’m currently working on a freelance project that pairs Tailwind v.3.x with suitably cachebusters-ed Hugo v.0.112.x (Hugo/Tailwind is the customer’s preferred arrangement), and the interaction between the two is just as it should be between Tailwind and any site-building platform.¹

Outstanding news, right? So why did I put “(maybe)” in the title? And why did I use the “Pinky-swear” wink-wink in the intro?

Well, it’s because Tailwind v.4 can’t be far off. Consider the cadence of the framework’s major version releases:

v.1.0.0 — 2019-05-13.
v.2.0.0 — 2020-11-18, eighteen months after v.1.0.0.
v.3.0.0 — 2021-12-09, nearly thirteen months after v.2.0.0.

Thus, as of the initial publication of this post, it’s been nearly eighteen months since the release of v.3.0.0. Note also that Tailwind creator Adam Wathan said last November:

Goals for Tailwind CSS v4.0:

🤏 Simplify mental model, fewer framework-specific concepts
🪄 Less configuration, without less power
✂️ Fewer dependencies
⚡️ 10x faster

Aggressively defend against complexity, double down on robustness and stability 🤝

All of these, along with certain references in replies to various issues reports on the Tailwind CSS GitHub repository, suggest one should expect a v.4 release sooner rather than later.

The history of major Tailwind releases has been that each new one requires some juggling to make it work properly with Hugo. It’s been an “arms race” kind of thing. So, while Hugo v.0.112.x (and up) now gets along well with Tailwind v.3.x, we’ll have to wait to see what happens with future releases of Tailwind — and Hugo, for that matter.

I don’t know whether the aforementioned Hugo/Tailwind hacks still work but, in any event, you don’t need them any longer. ↩

Here, not there — or, making styling behave

Bryce Wray — Sun, 19 Mar 2023 20:45:00 +0000

All I wanted to do was make my bold and slanted text instances a little easier to see, as I’d seen done on others’ sites. But, man, did that ever end up involving some convoluted-looking styling. On the chance that you might need to do something similar, here are the details.

Note: Before I proceed, I must acknowledge Stefan Judis’s article, “How to select elements that are not children of other elements in CSS,” without which I’d have been lost as a goose in what I’m about to describe.

Using sans-serif fonts, like my site is doing as of the initial publication of this post, can make some styling combinations hard to see under certain viewing conditions. While this is true for slanted text, it surprisingly can happen with boldfaced text, too, especially if one is viewing in dark mode.

(Obviously, where slanted text is concerned, what we’re talking about with many sans-serif web fonts is obliquing rather than the more commonly mentioned italicization. However, since I suspect readers will be more familiar with calling slanted text “italics” than calling it “oblique,” I’ll use the former term from here on. Also: equally obviously, truly italicized text, like an italicized serif font, is a completely separate consideration.)

I’ve noticed some sites, such as Chris Coyier’s, use some subtle styling to make bolds and italics stand out slightly from surrounding plain text, so I decided to try that on this site. I thought at first that it would be fairly simple: just set each variation to be a little darker in light mode and a little lighter in dark mode.

. . . But, not so.

First, I had to take into account the possible pairing of boldfaced and italicized text, like this.

Then, I remembered I’d also need to provide for all these variations to work within a blockquote, which starts out looking a little different than the surrounding plain text:

Here is a blockquote with bold, italic, and bold italic text.

And, finally, there was the matter of making sure the specified color differences didn't futz with colors that I didn’t want to change, such as within links like this one to my home page and within the red class I occasionally use for things like the Important, below (although it won’t be red on this dev.to version of my original post):

Important: This is a really big deal, so you should pay attention to it.

But if you were to suspect this would require a mountain of gnarly CSS — or Sass/SCSS — you’d be only half-correct. Gnarly? Oh, yeah. But a mountain? Nope.

Before we get into the actual SCSS involved, note that the color variables to which it refers come from this (and, yes, I’m shamelessly cribbing those $twcss colors from the Tailwind CSS color palette and then adding a couple more courtesy of Eric Meyer’s Color Blender tool):

// These are relevant excerpts from
// a partial called `_variables.scss`.

$twcss: {
    gray-50: #f9fafb,
    gray-100: #f3f4f6,
    gray-200: #e5e7eb,
    gray-300: #d1d5db,
    gray-350: #b7bcc5,
    gray-400: #9ca3af,
    gray-500: #6b7280,
    gray-600: #4b5563,
    gray-650: #414b5a,
    gray-700: #374151,
    gray-800: #1f2937,
    gray-900: #111827
};

With those variables set, here we go. (You may want to copy the code into a text editor for more comfortable, scroll-free viewing.)

// These are relevant excerpts from
// my `articles.scss` file, which
// comes into play only when a
// page has the `article` element.

@charset 'utf-8';
@use 'partials/variables' as var;

article {

    // First, we assign colors to
    // boldfaced and italicized text
    // that is **not** in the class
    // `red`, **not** inside a link,
    // and **not** within a blockquote
    // (we'll get to blockquotes below).
    //
    // Note that we cover not only
    // <strong> but also <b>, and
    // not only <em> but also <i>;
    // in addition, we take care of
    // groupings --- <strong><em>,
    // <em><strong>, <b><i>,
    // and <i><b>.

    strong:not(.red *):not(a *):not(blockquote *),
    b:not(.red *):not(a *):not(blockquote *),
    em:not(.red *):not(a *):not(blockquote *),
    i:not(.red *):not(a *):not(blockquote *),
    em strong:not(.red *):not(a *):not(blockquote *),
    strong em:not(.red *):not(a *):not(blockquote *),
    i b:not(.red *):not(a *):not(blockquote *),
    b i:not(.red *):not(a *):not(blockquote *) {
        color: map-get(var.$twcss, gray-800); // (vs. gray-700)
        @media (prefers-color-scheme: dark) {
            color: map-get(var.$twcss, gray-200); // (vs. gray-300)
        }
    }

    // Now we deal with the blockquotes,
    // including links within them. Here,
    // we assign colors to boldfaced and
    // italicized text that **is** within
    // a blockquote but is **not** inside
    // a link. (We cover the same tags
    // and groupings as before.)
    //
    // In essence, we're giving this
    // normally grayed-out text some
    // color treatments to differ slightly
    // from usual blockquote styling.

    strong:is(blockquote *):not(a *),
    b:is(blockquote *):not(a *),
    em:is(blockquote *):not(a *),
    i:is(blockquote *):not(a *),
    em strong:is(blockquote *):not(a *),
    strong em:is(blockquote *):not(a *),
    i b:is(blockquote *):not(a *),
    b i:is(blockquote *):not(a *) {
        color: map-get(var.$twcss, gray-650); // (vs. gray-600)
        @media (prefers-color-scheme: dark) {
            color: map-get(var.$twcss, gray-350); // (vs. gray-400)
        }
    }
}

Would I want to fool with such spaghetti-ish stuff on a regular basis? Oh, my, no. But when you need it, you need it and, fortunately: (a.) any valid CSS works in Sass; and (b.) modern browsers’ CSS support has advanced sufficiently over the years to handle situations like this one.

Hugo via npm?

Bryce Wray — Mon, 20 Feb 2023 19:11:31 +0000

Important: Be sure to check the 2023-11-18 update at the end regarding a dependency issue with the Hugo Installer package described herein.

During my years of using the Hugo static site generator (SSG), I’ve occasionally seen mentions about how you could install, and even run, Hugo’s Go-based binary by using one or more JavaScript packages sourced via npm. Having long ago understood the usual, very un-npm-ish Hugo methods for installation — much less the un-npm-ish nature of Hugo use in general — I never bothered looking into these JS-based alternatives. Besides, I figured, how could they even work? And, if they did, in what use cases did they make more sense than normal Hugo use?

But, yesterday, I began to grasp a bigger picture.

The point, and it does have one . . .

While I was helping someone resolve an apparent problem with his own Hugo site, I saw that his chosen theme installed and employed Hugo through just such an approach. In this case, the npm package was Hugo Installer, created and maintained by Dominique Müller.

My usual reaction, bordering on disdain, soon gave way to my oft-cited nerdy curiosity, although I still had the same primary questions from those earlier encounters with references to an npm-style way to handle Hugo. Then, as I read up on Hugo Installer and how it was used in a variety of sites and themes, I started to get the point.

Like the more venerable, more popular, but (in my opinion) less suitable hugo-bin, Hugo Installer makes it easier to manage Hugo use in projects already making thorough use of Node.js packages — which seems to describe a huge majority of the projects you’ll find on places like GitHub and GitLab:

If cloning/forking a project, one usually does a simple npm install to get all the goodies needed to make the project run either locally or on a remote host.
In a multi-developer project, it’s important to keep everyone’s tools on the same versions through use of package.json.
On the other hand, it’s sometimes necessary for separate projects on the same machine, or within a team’s machines, to use different versions of one or more tools. For example, a dev or dev team might inherit a project that, for whatever reason, goes belly-up unless used with an older version of a specific tool.¹

Now, with Hugo Installer and appropriate scripting onboard, even a Hugo project can meet these requirements just as well as can a project anchored by a JS-based SSG.

How it works

When run from a package.json script, Hugo Installer checks for the presence of a Hugo binary — by default, in the project’s bin/ folder, although you can pick a different location — and, only if it doesn’t find the binary, downloads and installs a version, which you must specify. The check goes very quickly and, thus, I suggest you make a package.json script that does only the Hugo Installer part, and use it with your other Hugo-related scripts. Here are some examples, some of which use Müller’s exec-bin package so the installed Hugo binary will run as you would expect:

{
    "name": "my-project",
    "description": "TBD",
    "config": {
        "hugo": "0.110.0"
    },
    "scripts": {
        "install:hugo": "hugo-installer --version $npm_package_config_hugo --extended",
        "dev:hugo": "npm run install:hugo && exec-bin bin/hugo/hugo server",
        "prod:hugo": "npm run install:hugo && exec-bin bin/hugo/hugo --minify",

You’ll note my use of a config object, in which I provide the desired Hugo version. This allows me a clear, easily identified place to change that spec at a moment’s notice whenever I wish. Down in the install:hugo script, I call back to that specification by using $npm_package_config_hugo.²

Any sour points?

Earlier, I cited this method’s advantages vs. “normal” Hugo. But are there comparative disadvantages?

In my use so far, I’ve noticed only one: for anything you’d have normally done through a hugo command from the terminal, you’ll have to change it to a script within the given project’s package.json. Let’s say you want to recreate the hugo new command for starting a new post, e.g.:

hugo new posts/2023/02/my-next-post.md

In a project using Hugo Installer, you’d need a package.json script like this:

"hugonew": "exec-bin bin/hugo/hugo new",

Once you have that, the previous example would become:

npm run hugonew posts/2023/02/my-next-post.md

. . . which is hardly worth mentioning where one’s muscle memory is concerned. However, if you typically use a lot of hugo commands and thus would have to make a package.json script for each, you’ll probably have a much different opinion about the whole thing.³

Anyway, there you have it: a totally different way of installing and using Hugo.

This month, I took my site squarely into npm-ville when I brought in the npm version of Sass and added PostCSS to make "future" CSS work with current browsers. As it turns out, those changes made my site an unexpectedly appropriate target for the use case that Hugo Installer presents. I’m sure I’ll find nits to pick over time but, for now, I’m impressed by what I’ve seen.

Update, 2023-11-18

Due to a vulnerability in one of the dependencies in the current version of Hugo Installer, be sure to add the following to your package.json (and do an npm install to install it, of course):

  "overrides": {
    "semver": "^7.5.4"
  }

Where Hugo is concerned, one possible scenario of this type would be if a project required the Blackfriday Markdown parser, Hugo’s support for which ended with the release of Hugo 0.87.0 in August, 2021. For that matter, Hugo began transitioning away from Blackfriday with Hugo 0.60.0 (November, 2019), when Goldmark became Hugo’s default Markdown library. ↩
I encourage you to read Brian Childress’s 2018 article, “Variables in package.json,” which was a great help in this aspect of the changeover. ↩
One other thing to keep in mind is that, if you already have a more conventional Hugo installation on your machine, especially a global installation, you'll probably want to uninstall it before trying this method. Otherwise, you might not know whether Hugo Installer is working properly, because your machine may — and likely will — be using its previously installed Hugo version rather than the one you're trying to install and use. But, if you have multiple Hugo projects on the machine, you’ll then have to use Hugo Installer with all of them, and only you can decide is it’s worth it. ↩

Sweeter searches with Pagefind

Bryce Wray — Thu, 08 Dec 2022 14:52:42 +0000

If you lurk in some of the same tech forums that I do, you’ll see a lot of griping about the declining quality of online search. Who’d have ever thought that contorting search results, stuffing them with ads, inadequately curating them for quality, and otherwise caring only about their financial upside could have proved so counterproductive? (“Me,” you and I can yell in unison.)

Fortunately, while there are limits to how much you’ll be able to improve your experience with online search in general, you can optimize your own website’s search capabilities. That’s assuming, of course, that your website is built with a static site generator (SSG), as I’ve recommended on my own website over the years, and has search capabilities in the first place. If it lacks search, you can fix that readily enough with the free Pagefind tool about which I wrote earlier this year.

As newer versions of Pagefind appear, its powers grow; and one of those enhancements has enabled me to make my site’s search results better — specifically, by cutting out stuff which really didn’t belong. I’ll give a couple of examples herein, explaining the respective procedures for my two favorite SSGs, Eleventy and Hugo.

Taking out the trash

Before I go there, however, let’s talk about exactly how you can make Pagefind exclude things you want excluded. Pagefind examines your site’s actual HTML, so you can use multiple methods to identify items for exclusion.

First, you can add data-pagefind-ignore to something’s opening HTML tag. You’d do this in your chosen SSG’s templating. For example, I exclude my site's HTML sitemap with:

<div class="sitemap-Container" data-pagefind-ignore>

While the data-pagefind-ignore exclusion capability was in Pagefind from the beginning, a more recent enhancement has been the addition of the exclude_selectors instruction for use in the site-wide Pagefind configuration file (in my repos’ case, that's pagefind.yml). As I’ll show you below, it gives you the power to exclude items even when you can’t directly edit the HTML as you can in templates.

Footnote references

It’s no secret to my regular readers that I like to use footnotes. The problem that presented for Pagefind search results was the appearance of numerical footnote references. These are the superscripted numbers that go in the main text and link down to the actual footnotes. Without dealing with these footnote references, one might see things like this in search results:

This1 is where a footnote appears in the main text.

. . . since there’d been a ¹ next to This in the original sentence that Pagefind had located.

Fixing this is where exclude_selectors comes into play, since writing your main text in Markdown doesn’t allow you to edit footnotes' HTML directly.¹

In Eleventy, a footnote’s HTML begins like this if one is using the most typical footnotes-ready Markdown setup, i.e., the markdown-it parser combined with the markdown-it-footnote plugin:

<sup class="footnote-ref">

. . . so you’d put this in an Eleventy repo’s pagefind.yml:

exclude_selectors:
  - "[class='footnote-ref']"

As for Hugo with its built-in goldmark Markdown parser and included Footnote extension, a footnote’s HTML begins like this (here, it’s the first footnote in a page):

<sup id="fnref:1">

. . . thus needing the following for a Hugo repo’s pagefind.yml:

exclude_selectors:
  - "[id^='fnref']"

Code blocks

As this post shows, I also like to include code blocks, and on occasion they can be, um, large. You might think it would be a good idea to include those in site searches, but my experience has been that they get in the way of more plain-English results. After all, code blocks can have many ordinary words for which someone might be searching but expecting very un-code-block-ish results. Since I annotate many of my code blocks with comments-as-documentation, this can further exacerbate the potential problem.

Thus, we once again employ exclude_selectors.

In Eleventy — assuming one is using the official Eleventy syntax highlighting plugin, as I would recommend — a code block begins with something like this (here, the code itself is JavaScript, since the class varies according to the language being highlighted):

<pre class="language-js">

. . . so now our Eleventy pagefind.yml will have:

exclude_selectors:
  - "[class='footnote-ref']"
  - "[class^='language']"

In Hugo and its built-in Chroma syntax highlighting, a code block begins with:

<pre class="highlight">

. . . which means our Hugo pagefind.yml now needs:

exclude_selectors:
  - "[id^='fnref']"
  - "[class='highlight']"

For more information on managing how Pagefind provides search results for your visitors, consult the Pagefind documentation.

Well, technically, you could do so if you did your footnotes completely manually — since you can mix HTML in your Markdown — but that would be a major pain and completely waste the exemplary footnote-handling likely offered by your SSG. ↩

Tailwind CSS v3.2: revisiting my “feature creep” warning

Bryce Wray — Sat, 22 Oct 2022 13:43:00 +0000

Note: This also was the subject of a Hacker News thread.

Earlier this week, a blog post introduced version 3.2 of the popular Tailwind CSS styling framework.

The “absolutely massive amount of new stuff” the post trumpeted includes:

Multiple config files in one project using @config

Browser-support-based styling with supports-*

ARIA attribute variants

Data attribute variants

Max-width and dynamic breakpoints

Dynamic group-* and peer-* variants

Dynamic variants with matchVariant

Nested group and multiple peer support using variant modifiers

Container queries

. . . the details of which all sound impressive, to be sure. However, as I read about them, I was reminded of something I wrote near the end of the “Should you adopt Tailwind 3?” piece I did back in January for the Stackbit blog:

Because of Tailwind’s need to stay not simply relevant but also popular, the project is particularly vulnerable to the dangers of feature creep. . . . [R]emember that the idea behind Tailwind, like every other utility-first CSS framework, is to make styling easier, especially for front-end developers who dislike getting under CSS’s hood. The more capabilities that get added to Tailwind, the more complex Tailwind becomes. It may not yet be near a tipping point, but that’s a danger for which the Tailwind team will have to be on the lookout.¹

That was nine months ago. Although I surely wasn’t expecting to be proven right this soon, all the new features in this v3.2 release of Tailwind, especially on top of the many other additions to Tailwind over the last two years in particular, add up to a project that now does seem, uh, a bit much.

I’ll cut to the chase for all the aforementioned “front-end developers who dislike getting under CSS’s hood”² . . .

The more features that get added to Tailwind, the more you have to know about CSS before you can use those features. Right? So why not just bite the bullet and learn to use CSS without the additional tooling (and weird, often lengthy additions to your HTML) that Tailwind and other utility-first styling frameworks require?³

That said: if you insist on using Tailwind because you utterly can’t bear to deal with vanilla CSS (although it’s not really all that vanilla anymore), Tailwind v3.2 provides quite a bit more to cram into your ditty bag of styling powers. You’ll have to decide when it reaches that inflection point where its use consumes more time and brainpower than it saves.

This includes a few edits for my site's style, as opposed to how it appeared both in the original form on the Stackbit blog and its contractually required re-publication on my site. ↩
And those who manage them, given that Tailwind is especially popular as a way of enforcing styles among corporate development teams — where CSS expertise can vary widely. ↩
For my own site, I’ve used Tailwind off-and-on over the years, but kept returning to Sass/SCSS as a more comfortable, bullet-proof styling method vs. what utility-first frameworks entail. (Then again, I’ve been working “under CSS’s hood” for 20 years, so there’s that.) ↩

Simplifying switcheroos

Bryce Wray — Fri, 23 Sep 2022 14:25:43 +0000

It’s a web meme that began as a line from Jurassic Park:

. . . your scientists were so preoccupied with whether or not they could that they didn't stop to think if they should.

Well, the other day, my oft-mentioned enthusiasm for switching my site among various static site generators (SSGs) manifested itself in an idea that I immediately thought was so cool that I had to make it happen.

And, no, I didn’t stop to think if I should.

But the thing is, I’ve heard from and read about others out there who, as do I, like to perform these switcheroos in which they move their sites from one SSG to another. It’s not just moi. So I thought I’d write up the whole thing, just in case my fellow migratory nerds out there might find it useful.

The former way

First, here’s a brief summary of how, before now, I would perform such site moves. The term project below refers to a website instance in my web host of choice, Cloudflare Pages. Terms vary from host to host (e.g., Vercel also calls them projects, while Netlify calls them sites), but you understand what I mean.

For each SSG of interest, I’d have my site's content in a project. Of course, only one project at a time could be the site — we’ll call it the Site Project — and so only that one was set to receive traffic for my brycewray.com domain, unlike however many Non-site Projects I might be maintaining.

When I chose to do a switcheroo, I’d have to:

Go into the Site Project and disable its settings for that custom domain, thus taking my site offline.
Go into the Non-site Project to which I wanted to move the site and set it up for that custom domain.
Wait until the host “blessed” the change, at which time the switcheroo would become official and my site would be online again.

While experience born of sheer repetition allowed me to do the first two parts in well under a minute, and the subsequent “blessing” usually¹ occurred almost as quickly, sometimes Stuff Would Happen and my site would be offline for minutes.

It’s not as if my site is mission-critical to humanity or anything like that, but I still was annoyed by that (usually) brief period of offline-ness. I was sure there had to be a better way — other than the obvious choice of never migrating, that is.

This is where my idea comes into play.

The new way

It was obvious that the failure point was in the domain-switching part. The just-as-obvious answer was that I would simply not switch the domain. Instead, I’d set up just one project, to which the domain would always be assigned, and point different repos to that project.

“But, wait,” you say, “even that repo switch can involve some period of down-time, right?”

Yes, if you do the switchover through the host’s GUI.

But what if you don’t?

What if you do it completely through CI/CD?

Bingo.

So here’s what I did.

I created a new project, called static-site.
For static-site’s default content — the repo that the host's GUI assigns to it via the usual Git connection — I assigned a for-testing-only repo which, on publication, has just a couple of minimal pages and nothing more.²
In each SSG-specific repo (i.e., each repo with my site’s real content and using a specific SSG of interest), I created a GitHub Action (GHA) that would publish to static-site, and thus the site.
Then — and this is how the whole trick works --- I make sure that only the SSG-specific repo I want to use has its GHA in the right location (.github/workflows/) so it’ll work, while each other SSG-specific repo has its GHA in a standby location which GitHub won't “see” as a trigger point.

This way, I can work with and push commits to each remote repo as much as I want, but only the one I want to be the site repo at any given time will actually have its content published to the website on each push.

Thus, I can effortlessly, instantly switch my site between Eleventy and Hugo, or between Hugo and Astro, or between Astro and . . . well, you see.³

The proverbial “devil’s workshop”

Whether anyone else might ever have a use for such a method, I obviously can’t say, but it works for me. If you can find value in it, there you are.

And, if not: well, try not to pity me too awfully, okay?

Besides, it could’ve been worse: I had a fleeting thought of trying to come up with a monorepo with multiple SSGs and their respective configurations, file/folder “lookup orders,” etc. — so I could share just one set of content among all the SSGs, making switcheroos that much easier. At least I didn’t go there.

Well . . . not yet, anyway. [Evil laugh.]

Later note: For those who may be morbidly curious about that last item, be advised that, my curiosity too much to bear, I did attempt just such a monorepo-based approach. While I got it to work with very bare-bones-ish content, I couldn’t determine how to make different SSGs respect — or, more accurately, ignore — each others’ components, shortcodes, etc. (at least without show-stopping errors). That’s where the mad-scientist-level experiment ended.

More often than not, it’s a function of how quickly the host can auto-issue a new SSL certificate so the site will have that https: goodness. Under normal circumstances, the cert is issued within a minute. In my case, I get it for both brycewray.com and www.brycewray.com, but these happen sufficiently simultaneously that the doubling-up usually isn’t a factor. ↩
Why did I even bother with that? Because it’s the easiest, quickest, least glitchy way of getting the static-site project online at all. I’ve not yet found a way to initiate such a project strictly via CI/CD without first setting up at least a bare-bones presence via the host’s GUI — mainly because there are certain parameters that I can’t even put in CI/CD until the project exists. It’s a chicken/egg thing. ↩
One drawback to such switches — one which will probably keep me from executing them in too willy-nilly a fashion — is that they tend to re-send recent entries in the site’s RSS and JSON feeds. I’m sure there’s a way to avoid that, perhaps through working to make each SSG’s feed output as identical as possible, but I haven’t yet found it. ↩

Cache-busting in Eleventy: a simpler way with Sass

Bryce Wray — Tue, 20 Sep 2022 10:00:37 +0000

If you use the Eleventy static site generator (SSG) and Sass to build your website, read on for some cool stuff.

Back in late 2020, I wrote three posts about how to perform “cache-busting” on an Eleventy site’s CSS, which ensures the vast majority of web browsers will reliably show your most up-to-date styling. In the end, I suggested a method that accomplished this through a combination of package.json scripting and build-time JavaScript runs. It worked, but it was somewhat of a time drag during dev mode. Besides, it’s a lot clunkier than how one can do it in Hugo via that SSG’s built-in asset pipeline, Hugo Pipes. Thus, I’ve continued to look for a better way.

Now, I’ve found it.

It comes in the form of two recently introduced Eleventy plugins by Kentaro Imai: eleventy-sass and eleventy-plugin-rev. The former provides Sass-to-CSS compilation, and the latter adds filters you can access to provide versioning-based filename changes for cache-busting.

It’s as simple as this. First, go to your Eleventy project directory and install the two plugins from npm:

npm i -D eleventy-sass eleventy-plugin-rev

Then register them in the project’s config file, usually a top-level .eleventy.js file, as in this simplified example (see the eleventy-sass documentation for more details about available options):

const pluginRev = require("eleventy-plugin-rev");
const eleventySass = require("eleventy-sass");

module.exports = function(eleventyConfig) {

  eleventyConfig.addPlugin(pluginRev);
  eleventyConfig.addPlugin(eleventySass, {
    rev: true
  });

  /*
    other Eleventy config as usual...
  */
}

Finally, add the following to your template for the site-wide head tag (the following assumes you have an index.scss file within src/styles/):

<link rel="stylesheet" href="{{ "/styles/index.css" | rev }}" type="text/css" />

That’s all!

Compared to my method from 2020, this requires no weird gyrations in package.json and no build-time machinations in JavaScript. It’s so much cleaner and simpler.

Now, on each run of Eleventy, the combo of eleventy-sass and eleventy-plugin-rev will create a CSS file with a hashed filename that changes every time you make a change to index.scss or any partials that index.scss might @use. (And you’ll want to @use, not @import, because the Sass-to-CSS compilation in eleventy-sass is done with Dart Sass, rather than the deprecated LibSass.)

Incidentally: in my own testing of this setup in dev mode, Eleventy’s --incremental flag keeps the dev server’s refresh functionality from calling the renamed CSS file when you alter the SCSS (and therefore cause that renaming to occur). Also, I found this to be true with both Eleventy 1.x and the still-in-development Eleventy 2.x; so I’d suggest not using --incremental if you don’t want to have to do a dev server refresh every time you make an SCSS change.

That little gripe aside, I encourage all Eleventy/Sass users to consider adopting this quick config improvement, courtesy of some neat coding by Kentaro Imai. It’s ’waaay cleaner than any other Sass-using, cache-busting solution for Eleventy that I’ve yet encountered, and you can have it up and running in just a few minutes.

Get good Git info from Eleventy, too

Bryce Wray — Mon, 05 Sep 2022 15:54:55 +0000

In “Get good Git info from Hugo,” I explained how to use the Hugo static site generator (SSG)’s built-in Git info variables to display page-by-page Git commit data for one’s static website. Well, lo and behold, you can get that kind of information in the Eleventy SSG, too. You just need to add a little code, in the form of a shortcode that takes advantage of Eleventy-supplied data.

It requires CI/CD

The one potential kink to this for you is that, in order for this to work best, you’ll have to use a CI/CD method of deploying your site. For anybody likely to find this article, you’ll typically be using either GitHub Actions or GitLab CI/CD. The reason this is necessary is because this method uses git log, and — at least as far as I know — there's no way to use any of the Jamstack-savvy web hosts’ UIs to specify fetch-depth: 0, which is necessary for this to work.

It’s outside the scope of this article to explain the CI/CD part, but I’ve written other posts about it (see my search page, especially regarding GitHub Actions) which you may find useful in pressing ahead with it.

The shortcode: go easy

In putting together this shortcode, we’ll follow the advice I gave in “Take a load off” about how not to overtax your development environment. While that article was about limiting accesses of remote APIs, it also applies to getting Git data. This is because git log is notorious for its potentially high impact on local device performance; it was built to be comprehensive, not to save CPU cycles. Thus, we’ll set the shortcode, which I call gitinfo.js, so that it does the heavy lifting only in production.

Of course, be sure to enable gitinfo.js (or whatever you choose to call it) in your Eleventy config file through the usual procedure.

Note that gitinfo.js assumes you have installed the luxon package, to be used here for formatting dates from Git commit data. (On the other hand, child_process is included in Node.js.) Notice also that you’ll have to supply, in the repoLink variable, the URL for your online repo’s commits.

const { DateTime } = require("luxon")
const childProcess = require('child_process')
const environment = process.env.NODE_ENV

module.exports = (pubdate, filename) => {
    let stringToRet = ``
    if (environment === "production") {
        let repoLink = ``
        /* ================
            For `repoLink`, fill in the starting URL
            for commits to your project's online repo!
            If you use GitHub, it'll usually be 
            in the format of:
            https://github.com/your-github-name/your-repo-name/commit/
        ================ */
        pubdate = DateTime.fromJSDate(pubdate).toFormat("yyyy-MM-dd")

        const lastUpdatedFromGit =
            childProcess
            .execSync(`git log -1 --format=%cd --date=short ${filename}`)
            .toString()
            .trim()

        const abbrevHash =
            childProcess
            .execSync(`git log -1 --pretty=format:"%h" ${filename}`)
            .toString()
            .trim()

        const longHash =
        childProcess
            .execSync(`git log -1 --pretty=format:"%H" ${filename}`)
            .toString()
            .trim()

        repoLink += longHash

        if (longHash !== '') {
            stringToRet = `Latest commit: <a class="mono" href="${repoLink}" rel="noopener">${abbrevHash}</a>`
            if (pubdate !== lastUpdatedFromGit) {
                stringToRet += `, ${lastUpdatedFromGit}`
            }
        } else {
            stringToRet = `&nbsp;`
        }

    } else {
        stringToRet = `[Git info will appear here in production.]`
    }

    return stringToRet
}

You may have noticed that the shortcode took two parameters: pubdate and filename. Here’s where the Eleventy-supplied data comes in. Wherever you want the Git data to occur, use the gitinfo shortcode as follows:

{% gitinfo page.date, page.inputPath %}

This will automatically feed to gitinfo a Markdown file’s date (derived by default from the file’s front matter but, if it’s not there, Eleventy has fallbacks) and inputPath. In a typical Eleventy repo, inputPath takes this form:

./src/path/to/my-markdown-file.md

As for the final message conveyed in your site by stringToRet, you’re obviously free to make stringToRet say what works best for your site. The main thing is that the code here shows you how to get the data that it needs in the first place. And, to be specific about that data, in production the gitinfo shortcode invocation brings back a string containing:

lastUpdatedFromGit — The date of the file’s last Git commit in yyyy-mm-dd format. (If this is on the same day as the initial date of publication, lastUpdatedFromGit doesn’t appear.)
abbrevHash and longHash — The short and long versions, respectively, of the commit’s hash. The returned string combines repoLink with longHash to produce the URL to which it then links abbrevHash.

If you typically show each page’s initial publication date and last-modified date, you can choose to avoid worrying about that latter part from here on by just using gitinfo’s output, instead. (Some prefer to provide the last-modified info manually, to indicate only true content changes; by contrast, gitinfo can report only the last time the file was changed/committed at all, even if just to eliminate a totally invisible empty line someplace.)

So, while it’s indeed cool that Hugo wields Git info-handling prowess out of the box, this shortcode gives Eleventy the same powers. (I’ll avoid the “great responsibility” trope.) Perhaps you can make good use of them.

Acknowledgements and related material

Zachary Betz, “Create React App: Show Current Git Branch and Commit Hash From Any OS” (2021-06-22).
Aleksandr Hovhannisyan, “Add Build Info to an 11ty Site” (2022-05-31).
Hector Molina, “Moving away from GitHub Pages to Cloudflare Pages” (2022-07-03).
Michael Schnerring, “Create a Hugo Website with GitHub Pages, GitHub Actions, and Cloudflare” (2021-03-19).
Mike Street, "The Git Commit Hash" (2020-05-28).
Hugo Discourse forum
- “Adding Last Modified Git Status to Pages?” (initially posted 2020-05-10).
- “Problems with GitInfo in CI” (initially posted 2019-12-25).
îles GitHub Discussions, “Any way to expose Git data?” (initially posted 2022-06-10).
Node.js v18.8.0 documentation, “Child process” (accessed 2022-09-04 for this article).
Pragmatic Pineapple, “Add Updated At To Your Gatsby Blog” (2021-02-08).
Stack Overflow
- “Get hash of most recent git commit in Node” (initially posted 2015-12-29).
- “Why The Output Of ‘git log’ Is Different In Terminal and execSync In node.js” (initially posted 2020-08-31).

Astro and the move to MDX

Bryce Wray — Sun, 31 Jul 2022 17:47:01 +0000

Grizzled old guy that I am, I saw the original “Hail Mary” play when it happened¹ back in 1975, so I like to think I know a good “Hail Mary” when I see one. In fact, I may have done just that.

In April, I wrote “Is Astro ready for your blog?” In it, I noted that, although the Astro static site generator (SSG) was (as it still is) justly receiving a lot of love for its many cool features and the leanness of Astro-built sites, it did suffer somewhat regarding the developer experience on a site containing a large number of Markdown files:

. . . larger sites don’t refresh all that quickly when you edit either Markdown or an .astro file . . . . where refresh-in-dev-mode speed is concerned, all the other competitors currently have an edge on Astro for this item, with the stunningly fast Hugo obviously leading the pack.

(Link added to original text.)

Here's what I meant. When I’m running Hugo in dev mode and save a change to any of my site’s “watched” files (content, style, layout, etc.), I see the result almost instantly on-screen; but, with Astro back then, such actions caused Astro to “think about” the change for several seconds before it would display the revision.

In the subsequent “Mulling over migration?” post, I added more details:

If your current site has only a few pages, you’ll find Astro's dev server refreshes the browser quickly enough to suit you. However, after your content gets up to and beyond about the 100-page level, even a fairly simple content edit will cause the refresh to take several seconds when you save the file you’re changing, and the lag will get longer as the site gets bigger.

The Astro devs are aware of the issue — perhaps related to Astro's interaction with Vite — but it’s unknown when it’ll be fixed. Thus, with a larger site, you may want to get used to writing your content outside of development mode and, only then, activating the Astro dev server to check the new page’s appearance.

This dev-mode sluggishness wasn’t the main reason why, as I wrote near the end of that post, I had moved my site off Astro and back to Hugo in May after only a few weeks with the newer SSG, but it didn’t help.² Still, I retained interest in and curiosity about Astro, so I continued occasionally to look in on its Discord community.

Along the way, I saw that the launch of Astro 1.0, originally planned for early June, had slipped multiple times. As of now, it’s set for next week, assuming the current Release Candidate (RC) suffices. This post is about one key decision that came very late in the dev process: Astro is shifting content management support from Markdown to MDX. (While Markdown will still work in Astro at least for the time being, it’ll do so under a “legacy” flag.)

As for why the Astro team made such a decision, especially so close to the desired date for “shipping” v.1.0, one recent comment on the Astro Discord by Astro co-creator Fred K. Schott may be especially telling. When a user wondered about problems with using components in Astro-flavored Markdown, Schott replied:

Yeah, you’ve kind of hit [on] the thing it’s taken us a year to learn: it’s really hard to build your own MD [plus] components system and syntax[.] 😅 We’re experimenting now with MDX as a better solution for components in [Markdown;] instead of us having to develop our own system we could leverage MDX instead. We already have experimental support . . . but if all goes well this would become standard in time for v1.0 with us deprioritizing our own[.]

This is somewhat reminiscent of the Astro devs’ decision late last year to transition Astro from their own Snowpack platform to Vite. It wasn’t easy, but the performance win was significant.

In similar fashion, making the move from Markdown to MDX this late in the ballgame is a big gamble. However, with the hassles the Astro devs have encountered while trying to make Markdown and Astro play nicely together, it makes sense — particularly considering how much of Astro’s raison d'être involves not only a pleasant DX but also smooth interaction between markup and components.

By this weekend, the Astro team appeared to have MDX working smoothly with the latest RC version, so I put it through some tests. Specifically, I wanted to see the DX for an Astro site with about as many MDX files as my current Hugo site has Markdown files. In fact, I even stacked the deck a bit against Astro by giving the test project more such files. (Each MDX file had numerous paragraphs of “lorem ipsum” boilerplate, enough to constitute plenty of text for Astro to manage.)

Based on my tests, the move to MDX looks like a winner. In dev mode, edits to “watched” files show up virtually immediately (I’d say Astro's MDX DX, so to speak, is very similar to that of Eleventy’s with plain Markdown). This could simplify a move to Astro for some folks with big, Markdown-heavy sites, folks who simply couldn’t stomach the molasses-like DX that they’d encountered before Astro/MDX interactivity became a thing.

So what could be wrong with this picture? Well, anyone who had already transitioned existing Markdown content from another SSG to Astro — especially given the changes such a move required — now must do so again. However, for those who hadn’t yet made that wrenching change, it’s a lot easier to move regular Markdown files to an MDX-equipped Astro site: you just change their extensions from .md to .mdx. Of course, you’ll have to address any “special” stuff you may have put in that Markdown on the other SSG, just as you would in moving between any two SSGs; but, now, generic Markdown as .mdx will work just fine in Astro.

The stability of Astro, like any other SSG (especially a JavaScript-based one), is only as good as the stability of its many third-party dependencies; and some of those are still a little shaky at this writing. That said, where the RC’s readiness for becoming the real v.1.0 is concerned, the team is pretty near the finish line on this count — and, in my view, the new MDX compatibility is a surprisingly big reason why. The switch was a gutsy move to make at all, much less at this point in the run-up to v.1.0, but also one that needed to be made.

To the good folks at The Astro Technology Company: I think you just threw one whale of a “Hail Mary” as the fourth-quarter clock was ticking down to zero. Here’s hoping v.1.0 is a winning touchdown.

Sorry, Minnesota Vikings fans, but I’m not interested in your complaints about offensive pass interference on the play. It was a long, long time ago. Get over it. (Also: in the famous film sequence of Drew Pearson as he crossed the goal line with the winning score, that was an orange thrown onto the field by a fan, not a penalty flag thrown by a referee. Truth hurts; I know.) ↩
In time, though, I found other reasons to prefer the Hugo DX, especially as I delved more deeply into coding projects requiring access to remote APIs. Hugo makes that work considerably easier than does any Node.js-based SSG. ↩

Using iCloud Mail with a custom domain

Bryce Wray — Mon, 13 Jun 2022 20:20:52 +0000

I was excited a year ago when, at its 2021 Worldwide Developers Conference (WWDC), Apple announced that one feature of its new extra-cost iCloud+ package was support for custom domains in iCloud Mail.

Up to that point, only an @icloud.com address would work with this service¹ but, now, people like me who got their email on one or more custom domains would be able to use those domains in connection with iCloud Mail. I knew I’d be an iCloud+ customer, anyway — the bundled Apple services to which I’d already subscribed are cheaper via iCloud+ rather than as separate offerings — so this additional benefit sounded like the feature which I’d long hoped Apple would provide.

As I’d mentioned in 2019's “The Holy Mail,” one advantage I gained in my 2017 move from a generic Gmail address to a custom-domain address (hosted by FastMail) was that, if I ever wanted to change providers in the future, this never again would involve telling all my various contacts to use a new address. Instead, I simply would point the appropriate online records for the domain to the new provider, and everything would continue to work just fine.

Don’t get me wrong; I’ve been mostly very satisfied with FastMail — but it is about fifty bucks a year. That price includes many services that I rarely or never use and which, I think, seem more useful for businesses than individuals; so I took this Apple announcement as a way I might get out of that.

As always, Reality ain’t pretty

Unfortunately, the new custom-domains feature got a lot of mixed reviews² when it went live later in 2021. Then, when I first tried it last October, certain resulting oddities gave me some qualms, so I quickly reverted the domain to my still-active FastMail account. In essence, there seemed to be some technical issues that Apple still hadn’t resolved sufficiently to make the switch as clean, or as compatible with other email providers, as I’d hoped following the WWDC reveal.

In the ensuing months, I continued to monitor developments and, after reading various reports that iCloud Mail’s custom-domains support seems now to be working more smoothly³, I once again decided to give it a try. Last night, I pointed one of my two custom-domain email addresses to iCloud Mail. In fact, it’s the address to which you can send by clicking that “Reply via email” link at the bottom of each post on my website.

Before you think, “Holy crap, he’s spending $100 a year for personal email,” please understand that this first domain I’m trying with iCloud Mail previously was just an alias on FastMail. That means it already came with my existing fifty-dollar-a-year subscription. Speaking of email aliases: any custom-domain email you put on iCloud Mail is just an alias within that service, too⁴. At one time, that would’ve been a deal-breaker for me but, now, I don’t care.

Important note: if you’re doing the same — bringing a FastMail alias over to iCloud Mail — you’ll want to kill both the alias and the alias’s domain entry on FastMail. I found out the hard way that doing only the former but not also the latter, even if only to play it safe, can cause SNAFUs during the switchover process. If that sounds like too much of a jump off the bridge for you, remember that you can always reverse the process if necessary. It’s tedious, but you can do it.

Progress report

It’s early, so the proverbial jury is still out; but I’ve been pleased so far. With a domain like this one, whose various MX and other records are hosted by Cloudflare, the Apple switchover process seems much less manual than what I encountered last October, so perhaps Apple listened to the community complaints and shored up things in the meantime. And, as for the nitty-gritty of actually using the thing: when I send emails to the address from various other-domain addresses to which I have access (long story), everything goes back and forth without any trouble.

It remains to be seen whether I’ll also switch my other address, the Big Kahuna that serves me in all aspects of life other than interactions with you folks who kindly visit my website. As you can well imagine, it will depend in great measure on how things go with this first one. I have a few months before my FastMail subscription would auto-renew, so I’ll have plenty of time to make a reasoned evaluation and act accordingly.

I’ll let you know how it goes.

Well, of course, that’s not counting those legacy @me.com and @mac.com addresses Apple issued many years ago, but I’m referring to current stuff. ↩
I’ll leave it to you to find those reports. You won’t have much difficulty, especially if you confine your searches to the second half of 2021. ↩
For example, see the endnote addenda to the otherwise “meh” review in Dominic Lauter’s “iCloud+ Custom Email Domains should be better.” ↩
See “One Mailbox” under “The SPAM and the Ugly” in Mike Lapidakis’s article from last November, “Thoughts on Custom Domains in Apple’s iCloud Mail.” ↩

Get good Git info from Hugo

Bryce Wray — Wed, 01 Jun 2022 13:14:00 +0000

While reading blog posts from other static site generator (SSG) users, I sometimes see that a post includes a link to the specific Git commit for that post’s most recent update. In this post, I’ll show you how to do it in a Hugo site, in case you’re interested in doing the same. As an additional benefit, it’ll automate something you might have been doing manually up to now.

I got the idea yesterday, when I saw a post from Aleksandr Hovhannisyan. In it, he gave a fine tutorial about displaying this data in pages built with the Eleventy SSG. Hovhannisyan’s method employed JavaScript to fetch the necessary Git data for use by his Eleventy templates.

On the other hand: with a Hugo site, things are much easier, thanks to the built-in availability of Git info variables. Once you set Hugo to fetch these variables, they’re available from within a .GitInfo object.

In your project config file, set enableGitInfo to true (here, I’m showing the Hugo default of TOML, although my own config file is actually YAML):

enableGitInfo = true

As the setting’s name implies, this activates the presence of the Git info variables.

I’ll get to the part about displaying commit info shortly but, first, let’s note that making this setting may have just liberated you from a nit-picking duty involved in how you display your posts’ dates. If you’ve been using manual entries in your posts’ front matter to indicate when they were last modified, you no longer have to do that. The Git info will, by default, provide this data as .Lastmod.¹

However, in production, you will need to deploy your site using a GitHub Action (or other CI/CD), as I've been doing lately. The problem is that, although these automated .Lastmod indications will be correct when you’re developing locally with hugo server, they’ll all take on the current date when you deploy. Fortunately, there’s an explanation and solution, from a thread² on the Hugo Discourse forum:

By default, the GitHub “checkout” action only fetches a single commit (for the ref/SHA that triggered the workflow). This results in the behavior you describe — i.e.[,] the current date/time is used for .Lastmod.

If you modify the checkout action to fetch the entire history (by specifying fetch-depth: 0), then .GitInfo and .Lastmod [work] as expected[.]

[Stylistic edits and one link applied.]

This is because (a.) hosts’ Git configurations for builds typically are set to so-called shallow-clone behavior; and, apparently, (b.) no host allows altering this in either its built-in UI or any optional config files (e.g., netlify.toml with Netlify or vercel.json with Vercel). Shallow-clone behavior causes problems with using .GitInfo data as described in this post, so keep this in mind if you typically deploy via your host’s built-in user interface rather than with CI/CD.

Note from the future: In testing for a later article, I found that, in fact, Netlify and DigitalOcean App Platform exhibit deep-clone behavior where Git is concerned, so you likely can use the information herein with their native UIs rather than having to deploy to them via CI/CD.

To make use of this answer in a GitHub Action, you could just add a with section to the GitHub Action’s Checkout default branch step:

      - name: Checkout default branch
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

. . . and, indeed, that fixes the glitch.

You might also want to test for whether a post’s day of original publication and its “last-modified” day are the same --- e.g., when you fix a typo or otherwise edit something while it’s still the same day as when you first issued the post --- and, if so, show only the “original-pub” listing, to avoid duplication. However, this requires comparing the formatted dates, since full timestamps clearly can never be the same down to the nanosecond; so here’s how you could accomplish this in an applicable template:

<p>
  <strong>{{ .PublishDate.Format "January 2, 2006" }}</strong><br />
  {{- if ne (.PublishDate.Format "January 2, 2006") (.Lastmod.Format "January 2, 2006") }}
    Last modified {{ .Lastmod.Format "January 2, 2006" }}
  {{- else -}}
    &nbsp;
  {{- end -}}
</p>

Within the paragraph, if the two are not equal (ne), this shows the “Last modified” statement; otherwise, it just inserts a non-breaking space so the height of the line will be the same.

That takes care of Git info for dates; but what about the original subject of this post, namely how you can link to a page’s most recent Git commit?

Well, the .GitInfo object also provides two variables for each commit’s hash: the full hash (.Hash) and the more familiar abbreviated hash (.AbbreviatedHash). Adding this within the proper templates is pretty matter-of-fact. The following example displays .AbbreviatedHash while the link is an exampleuser repo link plus /commit/ plus .Hash:

<p>
  {{- if $.GitInfo -}}
    <strong>Latest commit</strong>: <a href="https://github.com/exampleuser/hugo_site/commit/{{ .GitInfo.Hash }}" target="_blank" rel="noopener">{{ .GitInfo.AbbreviatedHash }}</a>
  {{- else -}}
    &nbsp;
  {{- end -}}
</p>

(The if $.GitInfo conditional prevents hugo server errors during local development while you’re working on content you haven’t yet committed.³ You can thank another Hugo Discourse forum answer for that one.)

And, yes, the previous advisory still applies: i.e., you have to deploy to your host via CI/CD in order to see the correct Git commit data for each post.

So, now, you’ve automated both (a.) displaying that Lastmod stuff and (b.) linking to the commit from which each page’s latest version originates. Yet, you needed no additional tools, and very little extra code, to do it. Not bad for a few minutes’ worth of work in Hugo, eh?

Update, 2022-10-07: If you’re interested in displaying both per-page Git info and whole-site Git info in your Hugo site, check the solution suggested by Hugo expert/contributor Joe Mooring. Thanks to Rodrigo Alcaraz de la Osa for the Q&A session that led me toward this additional information!

By default, Hugo will give higher priority to the Git info variable .Lastmod vs. other possibilities—including any manual Lastmod entries you may have already provided in your content’s front matter. ↩
The original question dates from December 25, 2019, but it took another 21 months before an answer, much less the answer, appeared. Jeeeez. ↩
The reason you don’t have to do this with the dates-display mentioned earlier is because, in that case, we’re simply using Lastmod (a variable Hugo already knows) rather than, specifically, .GitInfo.Lastmod, the absence of which for a given page gives Hugo fits. ↩