RE: Date and Time with a Static Site Generator

Jim Nielsen is asking the internet, or at least those building websites with static site generators, how they handle dates and times.

He’s running into some weirdness with dates, times, and timezones because he’s using Metalsmith.

For me, I record the publish date once: in the filename (e.g. 2023-05-16-my-slug.md). That YYYY-MM-DD string in the filename is the canonical location for my posts’ publish date.

Now that date is fuzzy because, you know, timezones. If somebody looks at one of my blog posts and it says, “Published 2023-05-16” what does that mean? Is that today? Or yesterday? Well, it depends on where and when in the world you’re looking at that post. “2023-05-16” in Denver is not the same as “2023-05-16” in Melbourne.

This is something I’ve had to consider lately because after migrating from Mastodon to Friendica I had tried adding my site’s RSS feed as a contact so that its posts would get syndicated as my own. It doesn’t seem to work, and I thought it was because my RSS feed wasn’t valid. And why wasn’t it valid? Because the post dates in my metadata weren’t RFC 822 dates.

Why weren’t my post dates in RFC 822 format? It was my own damn fault. I had taken to inserting dates in Emacs using date -R. However, I didn’t read the fucking manual carefully enough, because the -R switch is for RFC 5322¹.

-R, --rfc-email

output date and time in RFC 5322 format. Example: Mon, 14 Aug 2006 02:34:56 -0600

The long-form version of -R, --rfc-email should have been a dead giveaway. Likewise, if I had bothered to actually read the RSS 2.0 spec. According to the spec, <pubDate> needs to be Mon, 14 Aug 2006 02:34:56 EDT.

Fortunately, date can easily generate dates in that format, but the man page doesn’t tell you that you need to use --rfc-822. Maybe the info page does, but texinfo isn’t my favorite GNU project² and I’d rather read a man page than deal with the info tool³.

So, once I figured that out I had to through all of my posts and fix the dates. Fortunately, I didn’t have to do it manually. date has a -d switch that will let you specify a date and time other than that given by the system clock. There’s a catch, though. If you don’t specify the time zone you’ll still get the current time zone. So, if I run date --rfc-822 -d "2023-01-01 23:58:13" today (May 19) the time will will be given as EDT instead of EST, which which will result in an validation error in my RSS feed because we don’t do Daylight Savings Time in January.

That’s where the -u or --utc options come in handy. My posts’ metadata gives all dates and times as UTC (Universal Coordinated Time). That way, when the shell scripts I use to build my website process timestamps they’ll apply the proper time zone and my feeds will validate. Also, I don’t just have timestamps in my RSS feeds. The date at the top of each post? That’s provided inside a <time> element that prefers timestamps in ISO-8601 format.

So, that’s how my static site generator handles dates. I have a RFC-822 timestamp in UTC time in each post’s ‘date’ metadata field, and the varioous scripts I use feed it into date -d with various options to generate dates in the appropriate format.

Incidentally, when I was doing “view source” on Jim Nielsen’s site to peek at the generator tag and see what he was using, I noticed the following.

<!--

👋
Want to read the code behind this code?
It’s available on GitHub.
https://www.github.com/jimniels/blog/

-->

I like this, so I’m going to steal the idea for myself.