Published by

Working with Netlify CMS and GitHub Pages

This was originally posted on sb-ph.com. I’ve moved it to my blog since we’ve decided to remove the blog from that site.

 

Heads up: this post is kind of old! I’ve got mixed feelings about this approach now for a few different reasons, in no small part due to Uploadcare’s new pricing. No dig at them, they gotta do what they gotta do, but it puts this out of most of my clients’ budgets. If you’re interested in additional thoughts on JAMstack CMSs, you might want to take a look at this post.

Working with Netlify CMS and GitHub Pages

We’ve recently been exploring a lightweight CMS setup for the Host site. This post summarises the thought process behind our decision to work with Netlify CMS and GitHub Pages.

TL;DR
Though it’s an unusual setup for a client site, I like the stack and would consider using it again for a similar project.

Evaluating Netlify CMS

There are two potential downsides that would rule out Netlify CMS for most of our client projects. One is that user account setup isn’t super straightforward, the authentication method makes this a little more complicated than normal. The other is that the hosting “ownership” is tied to a GitHub / GitLab / Bitbucket repository. All-in-all, this approach demands a slightly higher level of technical know-how from the client than most other CMSs we regularly use (Craft, Kirby, WordPress, etc.).

The upside is the relatively low cost to the client, both in the short and long term. Netlify CMS is free, as are a few selected static hosting providers (Netlify and GitHub Pages spring immediately to mind). The login authentication is the only step that requires a server, since the keys have to be kept secret. Previously, the server would be the big ongoing time and money sink. Certain platforms however, such as Netlify, offer selected webtasks / microservices / cloud functions for free.

When evaluating these pros and cons against the Host website requirements, it became apparent that it would be a pretty good fit. The original Host static site was built with Jekyll and jekyll-seo-tag, so we knew it would work nicely with GitHub Pages and Netlify CMS. GitHub recently introduced free private repositories for up to 3 users, so we felt less concerned about the site hosting being tied to a repository that we own since we could transfer it to Host at some point without feeling pressure to make the repository public. And the Host folks are a pretty tech savvy bunch, so I wasn’t worried about them being daunted by things like repositories or GitHub-linked authentication.

Working with Netlify CMS widgets and media

So I got started with Netlify CMS. The first thing I dove in to was the widget (field) configuration, and I was impressed. The widget configuration options are more fully-featured than I would have expected for a ~1.5 year-old CMS. While configuring the widgets I also gave the custom editor Preview components a try, however ultimately I abandoned that experiment and disabled the editor Preview. It’s out of the scope of this project, and the maintenance of these React components alongside a non-React site seems a little dicey. Something to explore separately at a later date perhaps.

Media management is a concern on static sites, and this one is no exception. We could have gotten away with hosting the images in a directory in the GitHub repo, but we wouldn’t have any nice image transforms for faster page speed and would have had to ask the client to do all of the heavy lifting with image resizing and optimisation. I would have also worried about the repository size spiraling out of control with overly-large image files. Netlify CMS v2.1.0 offers the Uploadcare media widget by default though. Uploadcare’s free tier seemed to be a very good fit for the Host website, so we got that set up as well. The implementation was pleasingly straightforward. As someone who has spent a lot of time debugging image transformations in more traditional CMSs, Uploadcare’s URL-based system is refreshing.

Configuring GitHub authentication for Netlify CMS + GitHub Pages

The final critical step was the authentication configuration. Netlify CMS offers a number of different methods. We knew we wanted to use GitHub Pages for hosting, so the two most likely options were Git Gateway with Netlify Identity or GitHub with Netlify. We went for the latter. It does require that all users have a GitHub account (unlike the former), however this ultimately feels like the right approach since much of the site documentation lives in the repo’s Readme file and we feel it gives the client a bit more ownership over and awareness of the inner workings of their site.

The authentication was a little more complicated than the rest of the Netlify CMS setup. I followed the GitHub Backend instructions, which are relatively minimal and more geared towards a site hosted on Netlify. I found this article more helpful since it addressed what we were after, a Netlify CMS-powered site hosted on GitHub Pages. One potential “gotcha” in these steps is that the OAuth application should be registered on whichever GitHub account owns the repo. I added it to my user account initially which was incorrect, since our organisation account owns the repo.

After following the GitHub backend instructions, I only ran in to two hiccups. I’m documenting them below since I didn’t find much related information elsewhere.

One problem was a post-login “dead end”. After clicking “Login with GitHub” and signing in successfully in the pop-up window, the user should be redirected to the Netlify CMS dashboard automatically. Instead, it just said “Authorized” and did nothing. This is because I hadn’t added the website URL to the Netlify project. I had assumed I didn’t have to add the URL since Netlify is not hosting the site, however the Netlify authorisation callback script checks the host URL against the custom domains. Once I added the URL to the project in Netlify, the issue resolved itself. Note that I did not repoint the DNS to Netlify since we still want to host the site on GitHub Pages, so it shows a little error / warning regarding the URL’s DNS records. This is not a problem.

So I was now being redirected successfully to the dashboard, but the dashboard was just a white screen. The console indicated an error with loading netlify-cms.js from Unpkg, specifically:

Refused to execute as script because "X-Content-Type: nosniff" was given and its Content-Type is not a script MIME type

This seemed possibly related to some security-related GitHub Pages headers, so I decided to grab the JS from the Unpkg URL and commit it to the repo and no longer use a CDN for the script. This immediately fixed the problem.

Final thoughts

I’d like to do a bit more exploration of Netlify CMS moving forward since it could be appropriate for more use cases depending upon the developers’ roadmap. I will probably look at the Git Gateway with Netlify Identity route for authorisation as well. Besides Netlify CMS though, we’re really interested in exploring Kirby 3. Kirby 2 has been excellent for a number of small-ish websites (<5 stakeholders, not a ton of relational data), so we’re excited to see where they’ve taken the newest version and if it could work with projects of a slightly larger scale.

Published by

a little tired, but up and up

I’ve been behind. The past two months haven’t been great. But things are looking better, and the holidays couldn’t have come at a better time. We were in the US this time around, got to see more friends and family than I could have hoped. Here are some of the things we got up to.

Read more

Published by

Thanksgiving 2018 notes

Grandma’s holiday open house notes

After a rotten week health-wise, it was really nice to be able to celebrate Thanksgiving yesterday with a few friends. The image here is one of Grandma Piper’s very many post-party notes, a sort of debrief she wrote to herself about what she made and what she might change next time. This particular page seems to be her neighbourhood holiday open house plan from early December 1971 for around 110 guests (guest list is on reverse). I expect she found these notes super useful, particularly since she seemed to keep every single one of them.

Here’s what I made this year, documented for a similar purpose.

Read Thanksgiving 2018 notes

Published by

◼◼◼◼◼

It’s impossible to watch GBBO without wanting something sweet… Cocoa powder brownies fill the void. Baking takes a bit of time (25 min), but the prep is very quick since there’s no fiddly chocolate melting. These lie in the fudge-y end of the brownie spectrum, very dark and dense. In fact, I’ve made this in a cake format before since it’s almost like flourless chocolate cake. Bake in a round tin and spoon fresh whipped cream and berries over the top. Finally, this takes substitutions pretty well. I’ve made these vegan and gluten free before (coconut oil not butter, blitzed and gelled chia seeds not eggs, GF flour). Comes out great, though they’re a bit gooier and have to cook a little longer.

Simple cocoa brownies

Preheat the oven to 160C (320F) and line a 20 cm (8″) square tin. In a pot large enough to hold the rest of the ingredients, melt 150 g (1 1/3 c) butter. In a small bowl, combine 250 g (1 1/4 c) sugar and 90 g (heaping 3/4 c) cocoa powder. Beat this in to the butter. Once the mix is sufficiently cool, beat in 2 eggs and a tiny splash of vanilla extract or orange flower water (optional). The mixture will come together firmly, it will be almost taffy-esque. Gently stir in 64 g (1/2 c) flour just until combined. Pour in to the lined square tin, spread it in to the corners, and bake 25 minutes. The top should be glossy when done, possibly with a few cracks. Let it cool in the tin on a rack until nearly set but still warm.

Edit 23 May 2019
Just came across Prof. Maxwell’s recipe for Churchill Brownies on his faculty page! They’re cocoa powder-based as well, so will need to give his a try. His recipe seems to make the same quantity but with (much) less butter, less cocoa powder, and more sugar. I imagine his are more traditionally brownie-esque as opposed to the nearly cake-like texture of the recipe above, we’ll see!

Edit 04 October 2019
Results are in, Prof. Maxwell’s brownies are fantastic. Metric values below for reference:

  • Oven @ 175C
  • 113 g butter
  • 59 g cocoa
  • 2 eggs
  • 200 g granulated sugar
  • 64 g flour

See his faculty page for the method and imperial values. It was hard to get rid of the lumps when I was bringing the mixture together, so I might try the method from the Simple cocoa brownies recipe above next time. This will probably be my go-to brownie recipe now, and the previous one will be what I use for gooey cakes.

Published by

Agorama #2: exploring Scuttlebutt

A wall in Rebecca’s Flat at Raven Row

This past Thursday 18 October was the second Server Co-op meetup in Rebecca’s Flat at Raven Row. See all Server Co-op notes.

I didn’t take as many notes this time, wasn’t feeling fantastic. Very sketchy notes below.

click public button twice if the Patchwork feed seems stuck after first install

how to have Scuttlebutt on multiple devices?
eh, maybe not worth the hassle, just use one device
“sameAs” is currently being worked on by devs in Scuttlebutt community

identity = private + public + network key combo
lib sodium

back up private key and gossip.json

dark crystal for backing up private key using social network

“shamir’s secrets” algorithm
kind of like horcruxes!

with Scuttlebutt, your friends are your cloud/datacentre

nothing is ever deleted (same as Dat)

could technically have multiple identities, but functionality isn’t implemented currently. Would have to swap .ssb directories

Published by

Agorama #1: outstanding home decor + P2P

The rug in Rebecca’s Flat at Raven Row

Last night I went to the first Server Co-op meetup hosted by Agorama in Rebecca’s Flat. It’s a more-is-more space, and then some. It was a lovely evening. Notes:

Check out infocivics.com by Paul Frazee. “Computing networks are social and political systems. We should attempt to answer how the technical design of a network will influence the internal politics.”

There *is* a mobile Dat browser, but apparently it’s a bit… buggy. See Bunsen for Android (nada for iOS). Still, kudos to them for taking a stab at it. Apparently the project of making a Dat browser sort of hits a brick wall due to node.js, but a bunch of devs have taken it upon themselves to make a Rust implementation of Dat. TBH I don’t understand the ins-and-outs well enough to be able to describe how that lowers the barrier, but it sounds like the future of mobile Dat might be brighter for it.

I haven’t dug in to Scuttlebutt yet, and it sounds like it’s about time. An offline-first protocol, described by KG as a database/social network/community. See also Patchwork. Feel like I heard HL say that it came about after 2011 Christchurch earthquake due to the difficulties at the time with having any sort of connectivity, but that might be wrong?

And crucially, are there ethical conversations around P2P tech that we’re failing to have, or happily skating past? I’m thinking about when Facebook and similar now-giants were in their nascent stages, surely some of the current nastiness could have been avoided if the making was accompanied by a little more thinking, more extrospection? How do you wrap your head around the potential ethical implications of something that doesn’t yet exist? I found KB’s anecdote interesting, when a few fascistic idiots attempted to hijack Scuttlebutt but were almost immediately, organically, blocked from having any meaningful impact. It feels great, but who’s to say they’re not off in their own node somewhere trolling away? Feels awful to think that Scuttlebutt might be harbouring some sort of extreme-right cell, and yet maybe so be it, should it be a decentralised network’s responsibility to police that? How on earth would that work anyway?

Separate: I got my hair cut by Dean last week and am very pleased. When it’s styled it’s a bit Josie Packard (fabulous) and when not styled, it’s very Shawn Hunter (not totally a bad thing).

Published by

Hum-worthy tunes

There are a few tunes that you turn up and hum along to when they come on. “What Becomes of the Brokenhearted” by Jimmy Ruffin ticks the box for me. It’s one of those weird ones though, a song that has a kind of uplifting melodic line but some pretty sad lyrics.

Quick edit: Oh man, and “Crying” by Roy Orbison, and “Heaven Help Us All” by Stevie Wonder, and “Bye Bye Love” by the Everly Brothers. (Solid playlist on right now, clearly.) That last one will always have the softest spot in my heart.