A Fresh Start

This blog has had several incarnations. Originally, it was hosted using a different domain name because my vanity domain wasn't available at the time; I snatched it up later when its original owner did not renew it. If memory serves, I used a custom-written blog at first, and eventually transitioned to Habari and later WordPress.

I do want to stress that there was nothing wrong with any of these solutions. They served my needs at a particular point in time and ceased to be the ideal solution for me at a later time. That pattern is merely continuing its cycle.

To that effect, it seems I've come full circle. For a while, I've been considering moving to a static site generator for easier maintainability. I reviewed solutions like Jekyll, Sculpin, Spress, and Hugo. Ultimately, I made the decision to roll my own solution again.

Requirements

The focal point of this new transition was simplicity, in everything from the aesthetic design and backing toolset to the hosting and deployment process.

PHP is my lingua franca, so I wanted to be able to use it to minimize mental friction in the process of transitioning and maintaining the blog.

The choice of using a static site generator was partly influenced by being able to keep content under version control on GitHub and to easily deploy and host for free using GitHub Pages with a custom domain.

I enjoy writing content in Markdown and wanted to be able to do so for the next iteration of this blog. Ideally, I also wanted the option to extend the parsing of Markdown content to add features as needed in the future.

With regard to the structure of the site itself, I wanted to maintain several static pages as well as posts authored over time, where the index page would house the latest individual post and site navigation would include a link to an archive of all past posts in reverse chronological order.

To avoid breaking any more critical existing URLs indexed by search engines, I needed to have some control over URLs used for both pages and posts. I settled on a directory structure mimicing existing WordPress URLs and containing static HTML index files, which avoids the need for any web server URL rewriting.

Building the Generator

I wanted a simple PHP templating engine, as I expected to have few fairly and relatively basic templates. This turned out to be the case: I ended up with one template for layout and one for the archive page. I settled on league/plates.

Next, I needed something to parse the Markdown files I would use for content. I decided to use league/commonmark, as it would allow for customization of both parsing and rendering.

The next need I encountered was for generating slugs based on post titles, which would allow me to create filesystem-safe directory names for each post. After some digging on Packagist, I managed to find cocur/slugify, which does the job perfectly.

My build script iterates over designated directories for pages and posts. For pages, it creates root-level paths using the name of the content files. For example, content/pages/about.md is used to generate about/index.html.

Posts are a bit more complicated. The build script uses the league/commonmark parser to walk over an AST representing the parsed Markdown. The first top-level Heading element is assumed to be the title. The first Emphasis (i.e. italic) element following the title is assumed to be the date. From these two bits of data, a directory path of YYYY/MM/DD/title-slug is derived.

The rest of the process is simply injecting Markdown content converted to HTML into templates and writing the result to static HTML index files.

I've released this generator with the name Scribing under the MIT License. Feel free to download and play with it. I hope you'll consider using it for your own site so that it can be as helpful to you as it has been to me.

Creating the Design

For larger displays, I wanted a simple two-column layout focusing on the content with a smaller column for navigation. For smaller displays, I wanted the layout to be responsive, shifting the navigation to a smaller collapsible top bar to consume less screen real estate.

I considered using Bootstrap to do this, but because my use case was fairly simple, I ultimately decided to just write a media query myself. Bootstrap's documentation was fairly useful for determining device widths to consider, though. The Responsive Design Mode in Firefox was particularly useful for testing as I built this out.

Likewise, I could have used something like jQuery or an alternative to it, but since I only needed to show or hide a menu when a hamburger button was clicked, I wrote a small snippet of vanilla JS to handle it.

Being that recent releases of the major browsers all included support for CSS Grid, I decided to use that for the layout itself. As someone who was a developer during the First Browser War, it's wonderful to see browser vendors collaborating to release new features so that they're universally available.

To keep color as readable as possible with minimal distraction, I chose a monochromatic color scheme. Likewise, I wanted a font that was both stylistic and easily readable. After some perusing, I decided on the Libre Baskerville font available from Google Fonts. For social media icons, I chose the excellent Font Awesome toolkit hosted on BootstrapCDN. These are the only third-party dependencies downloaded by the client to view this site.

Writing the Content

Much of the page content was migrated over from my old site; I merely updated it in the process of porting it over to Markdown from HTML. For this, I use a CLI script that uses the wonderful league/html-to-markdown companion library to league/commonmark.

I made heavy use of referencing GitHub for things like all the commits and issues I've authored and a summary thereof in the form of my GitHub résumé. Likewise, I referenced Joind.in to represent my past speaking engagements.

For the content license, I used the Markdown version of the Creative Commons Attribution-ShareAlike 4.0 International license.

Finally, I took a page out of Jeremy Kendall's book and moved my résumé to a GitHub repository so I could also maintain it using Markdown. In cases where a person or job application site requires a file, there are plenty of utilities for converting documents from Markdown to PDF.

Deploying the Site

It turns out that Travis CI offers support for deploying to GitHub Pages, which I learned from this blog post. With some tweaks, I was able to adapt its examples for my own site. Now, when I push to the GitHub repository housing the content for my blog, it will build and push the generated static files to my GitHub Pages repository.

I did run into one related issue where pushing to Travis CI seems to wipe out the Custom Domain setting. Per the reporter's comments, adding a CNAME file appears to fix this.

Additionally, I was able to secure my site with HTTPS using the Cloudflare Free plan.

Epilogue

Overall, I'm fairly pleased with how this little experiment has turned out, and I hope to write more about the longer-term experiences of maintaining this blog in the future and that you'll enjoy my future writings. Thanks for reading!