Standard.site Docusaurus with Sequoia

I've kept hearing talk of Standard.site recently. But every time I heard about it, I didn't get it. I then read this primer on it, and if I'm totally honest, I still didn't entirely get it. I'm feeling a bit thick. But that's okay.

I think that it's sort of like RSS + AtProto. Ish. Well. I have a blog - you're reading it! It has an RSS feed. I'm on Bluesky - mostly (if I'm honest) for the purposes of posting picture of Hammerton's Ferry terminal each morning at dawn.

Well, since I have these two things, let's see if I can plug Standard.site support in using Sequoia. I may even learn, along the way what I'm actually doing! (And I may not, and that's okay too.)

Sequoia?

Sequoia is a CLI tool that describes itself as "a simple CLI for creating standard.site documents from your existing static blog." My blog runs on Docusaurus - which is a Markdown / React flavoured static site generator.

So I think I should be able to plug Sequoia into my blog fairly easily. Probably. I'm going to have a crack anyways.

Setting up Sequoia

First things first, the quickstart tells me to install the Sequoia CLI as a global tool. Already I can feel myself rebelling against this. For reasons that I can't fully explain, I hate installing global tools. Probably they remind me of global variables. Hard to say.

Well, I decide to fight back and roll with this instead:

And it's fine. So let's login:

Well that went great. This is the alternative option using app passwords:

I'm pretty sure that I'm going to want this flow, as I want my CI to handle publishing for me, I don't want to do it by hand. I wonder if I'm right...

Time to initialise:

I had to answer a number of questions, which eventually created this sequoia.json file:

With that, I decided to see what publishing might look like:

It suggested the following:

Tip: Add "identity": "johnnyreilly.com" to sequoia.json to use this by default.

I followed this advice. Terrifyingly, it also suggested it was going to publish every post I had ever written. Given these is hundreds of posts going back to 2012, this seemed a bit much.

Docusaurus meet Sequoia

At this point I think we have the basics of Sequoia publishing set up, we now need to make Docusaurus play nice with it. Or try.

So why is it trying to publish everything? My money is on Sequoia not being able to detect when my blogs are published. The config docs suggest I need a frontmatter.publishDate:

Field name for publish date (checks "publishDate", "pubDate", "date", "createdAt", and "created_at" by default)

Now if you look at the frontmatter for my blog posts, you'll see there is no field that matches up with the above.

You can see that the date exists, but it's simply being inferred from the folder name:

This is one of the many patterns that Docusaurus supports. But it happily supports providing date as a frontmatter item as well. So I think that's what I'll do. I'll just make every index.md file have an date: yyyy-MM-dd entry in the frontmatter.

The following Node.js script updated my existing frontmatters:

That done, I decided to npx sequoia-cli publish --dry-run once more.

This time of my 362 posts, only 2 were going to be published to Bluesky. Better. Along the way I'd fiddled with my sequoia.json and it now looked like this:

The quickstart would have me hitting publish now, but I don't want that. I want it tied into my CI.

GitHub Actions

There were docs precisely for this.

Looking at it, I wanted to check that the sequoia inject mechanism worked locally, before I shifted off to GitHub Actions. So I ran:

Ah checkmate. Okay, time to publish locally and see what happens.

Interestingly this updated every single blog post and added an entry to the frontmatter like this:

And filled out a .sequoia-state.json file as well. I don't love having this frontmatter entry in every post. It feels like a build artefact; it feels noisy. The docs suggest you don't need this and can just use inject. Okay - that's what'll I'll aim for.

Now I had published, I was safe to:

I was left with a slightly adjusted GitHub Actions workflow that added in publish and inject alongside the requisite credentials.

This all looked pretty good - but the only way to really test is to ship. Let's do that next.