Site redesign w/Jekyll part 1

The website you are on is the first major revision I have made in seven years. It speaks to the growing maturity of web standards that it took that long for the accumulated improvements in web technologies to make this worthwhile. This is the first in a series of blog posts about what I did for this revision.

The rationale

The last version of my website was created in 2015. At that time, Wordpress was probably the most common tool used by Average Joe Website Creator to put something on the internets. Given my nerd credentials, I wanted to have no part of that.

I settled on using what is termed a ‘flat file CMS’ to dish up my web stuff. I chose a product named Statamic to create my website. The key difference between Statamic and Wordpress ⊕I am not dissing Wordpress. It is an excellent product, especially for a non-technical user who wants to create a site without a lot of hassle. I used it for years, but my propensity for tinkering with my site's appearance and organization ran head-first into a wall of PHP knowledge that I did not possess. that Wordpress requires the site to have a real, honest-to-goodness database live and running on the site, while Statamic just accesses a set of text (flat) files.

This approach presents three main issues in my opinion. The first is that any database is potentially a security hole and can be subject to SQL-injection attacks. The second is that a database just adds a layer of complexity to the site building process and is inherently slower since every page requires a PHP function to make a query to the database to get the pieces needed to build the page. The final issue is that it is hard to leverage great version control products like Github to store versions of the site content.

Statamic represented the cleanest approach in 2015 to creating websites from a set of text files. It runs on PHP and just grabs files and quickly builds a webpage based on a set of templates. A template is essentially a scaffolding for a particular page that has generic placeholders for bits of content. When the page is built, it goes into the file system of the site and pulls the flat files it needs to construct a page.

The issues

All that is great. But what it meant in practice is that I had to design a website from the ground up. All the CSS, all the HTML and all the things. I bit the bullet and did it. I made a design decision to have both visual and written content served from the site. Getting it up and running required a lot of effort over a period of months, and the end result was nice, but probably not as slick-looking as it could have been. But I had a lot of fun doing it and learned a lot. That last sentence probably reveals a disturbing view of my definition of fun.

I did all sorts of fancy-pants things like make API requests from Flickr to serve up my photos. I spooled up my own Amazon AWS EC2 erver and got a webserver up and running from scratch. And I learned a lot in the process. This process gave me a view into the guts of the internet that was really enlightening. But that also means that I have to be a decent Unix sysadmin to keep my site running. I had experience in that from my full time job, so it was not as heavy a lift as it might be for some, but I still had to remember to log into my server every few months and type in sudo yum update to make sure that I was running all the correct internet trinkets that are needed to maintain a fully available webserver.

However, in the meantime, all my photo acquaintances seemed to be migrating to hosted services like Squarespace and Wix. And their sites looked good. A lot gooder than mine.

The pandemic hits, and there suddenly appeared a little extra time to deal with site jealousy. I looked at a lot of alternatives and finally decided that Squarespace offered the best place for me to showcase my visually-oriented photography work. But it kind of sucks for blogging. Squarespace certainly suppprts blogs and has plenty of template pages for blogs, but what it does not do in my opinion is get out of the way and allow a blogger to just write, upload a file and have it easily accessible and version controlled.

Jekyll static site generator to the rescue

I had been dabbling in the meantime with a static site generator named Jekyll. I had gone so far as to create a Jekyll theme that allows bloggers to create website with the same layout style as championed by Edward Tufte in his books: tufte-jekyll–on-github. To my surprise, this theme has proved very popular (at least by Jekyll standards!), especially with academics because it allows a blogger to write technical posts with math expressions and other extra goodies.

In some ways, a site created with Jekyll harkens back to the very beginning of blogging on the internet. All the content is created from simple text files that are written in a text editor. These files are written in the brilliant Markdown syntax created by Jon Gruber of Daring Fireball and the late Aaron Swartz. Markdown allows one to write structured content in a simple text editor without littering it with a bunch of HTML tags.

For instance, say we want to have a level two heading followed by a paragraph. In HTML it would be written like this:

<h2>My level two heading</h2>
<p>My amazing paragraph blah blah blah...</p>

In Markup, the same content is written like this:

## My level two heading

My amazing paragraph blah blah blah...

Markdown content is much easier to read than a bunch of HTML tag-littered content. And it has become a de-facto standard in many writing applications in realms outside the internet. I wrote my last book in Markdown which made it extremely easy to port it into whatever format the publisher needed by using a variety of applications.

Another very nice thing about Jekyll is that it is an integral part of Github and allows users to host any number of static sites (i.e. sites that are only a set of HTML files linked together). For free. That is kind of cool. If asked to create a low, or no-cost website for some organization, creating one on Github pages is about as good as it gets.

Since I had become familiar with Jekyll during this time,I decided that it is really a fantastic way to make sites that are text-centric. I then decided to separate the two sides of my web presence: use Squarespace for all the visual stuff, and a github-hosted Jekyll static site to host all of my written content.

Once this decision was made, I decided to forgo creating a theme from ground-up. Having been through that with the Tufte-Jekyll theme, I did not want to invest that kind of time in taking care of every design decision. So I decided to find an existing theme that was close to what I wanted and then modify it. There are several theme aggregation sites that have a large number of themes in one place to browse through. One such site is jekyllthemes.org, another is jekyllthemes.io, and yet another is jekyll-themes.com. Notice that startling lack of originality in their sites names? Me too.

I found a theme named Lanyon that was available as a repo on Github. It had what I wanted in terms of look. The theme is centered around reading content with minimal visual distractions. It has all the site navigation stuff accessible by a slide-out menu activated by the now ubiquitous ‘hamburger’ menu icon on the upper left corner of the pages. It was simple, clean and attractive. And when I examined the site layout and organization, it was simple and logical, and it was easy to figure out how to make things work.

Now that I had a starting point, I dove in to modify the theme to make it work best for my use case.