Published

Use Portfolio Starter to create a personal site with projects, pages, and posts

Screenshot of Portfolio Starter

This tutorial will teach you how to set up a personal website using Portfolio Starter, a starter kit for portfolio-driven websites made by Sam Baldwin and me. Check out the demo site to get a feel for how it looks, and visit the GitHub repo for more on how it works.

The tutorial is geared towards people that have little-to-no coding experience and are unfamiliar with things like GitHub, Eleventy, and Netlify. By the end of the tutorial you should understand terms like “repository” and “static site”; you’ll be able to edit your projects, pages, and posts; and your website will be hosted for free. Though basic experience with code such as HTML or CSS may be useful, it isn’t necessary for this tutorial since we’ll be using the hosting user interfaces to set this all up.

Let’s get started

Published

A lightweight CMS implementation for some lovely folks

I’ve been spending a bunch of time on the Host site recently and just wrote up some thoughts about working with Netlify CMS and GitHub Pages on SB-PH’s tucked-away blog.

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.

Read post

Edit 23 Jan 2019
I just deployed some small fixes (force curly quotes via the smartify filter, prevent Cards from showing if no image), but the site doesn’t seem to be updating. It’s updated if I navigate to https://hostofleyton.com/index.html but not https://hostofleyton.com. Kind of weird. This StackOverflow thread seems useful, as does GitHub’s own troubleshooting page.

Published

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.

 

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

Notes from 24 Pull Requests event

See notes and further research prompts below in relation to yesterday’s 24 Pull Requests event. It was organised by Codebar, Ladies Who Code, and Your First PR, sponsored by Gitter, Shutl, and Twitter. I left Twitter HQ with my brain fizzing, always a good thing.

Read more

Published

Linter (scss-lint) not working in Atom

Linting package linter-scss-lint was not working properly for me, with no linting occurring and no errors thrown. On top of that, other linters were functioning properly (i.e. linter-jshint). Came across issue Linters not linting…, and one comment suggested opening Atom from the command line. Tried this, and linter-scss-lint began working properly. Upon further searching, found issue noting that $PATH only present when Atom is launched from the command line.

Look in to this with Sam, he’s not having the same problems even though our .bash_profile and .bashrc files are the same. Check versions of Atom, all packages, Ruby, etc.