I like static sites. As someone who builds and maintains dynamic sites for a living, I appreciate the ease of use of a static site. I even worked on a prototype for edX. All of the problems happen at rendering time during development. No need to worry about an API version mismatch or a server going down in production. More importantly, no need to worry about caching and handling load.
I have run a small WordPress MU site for a few years to host this blog, my photography site, my wife’s blog, and my dad’s campaign site/blog. When I first started, WordPress was the best, and cheapest, option. I spent a lot of hours working on themes and adding the appropriate plugins. The one thing I never quite got right was caching. Caching seemed to work on my main site, the photography site, but not on others. Recently, Michelle’s blog has had issues with updating the homepage. She would publish new posts, but the homepage would not update until I went in and cleared the cache for all sites.
I spent an hour investigating this issue to no avail. That’s when I decided to migrate her site to a static site. Of the sites listed above, my photography site is the only one that is remotely dynamic—I have a custom plugin pulling images from Flickr. WordPress is overkill for the other sites. I only used WordPress because it offered Michelle and my dad authoring tools that are easy to use.
The authoring tools for static sites have improved greatly. There are even hosted services for these tools. I chose Forestry because it is well-designed and it’s free. We’ve used it at The Blackburn Foundation for a few months now, and it has been quite a pleasant experience!
The Blackburn Foundation site is generated by Jekyll. Jekyll is the first static site generator I ever used (unless you count FrontPage). It’s built on Ruby and has a very good ecosystem of plugins, themes, and support. It’s supported by Github Pages and Netlify (my host of choice) for hosting. Free hosting and free authoring tools make the decision to use Jekyll an easy one.
It turns out moving from WordPress to Jekyll is quite easy! I followed a guide that lead me to the Jekyll Exporter plugin. The plugin exports all of the posts, pages, and uploaded files, which be dropped right into the directory of a working Jekyll site. I spent some time tweaking the configuration to ensure the Disqus comments appear on the correct posts, fixing smart quotes, removing unused static files, and fixing HTML-to-Markdown conversion errors, but the plugin did a great job.
I spent more time modifying the theme to work with the data at hand. Michelle chose the Mundana theme, which looks quite nice. However, I made a few tweaks, all of which are available on Github:
/category/:slug/) to new one (/categories#:slug)Once the site was ready, I deployed using Netlify and ran PageSpeed Insights to find areas where I could quickly make improvements. I also ran a spider tool to find broken links; there were two from a couple 2016 posts that aren’t worth fixing at this time.
Finally I updated the DNS record to point to the Netlify server. I wish I could say I did all of this with zero downtime, but the delay in DNS propagation resulted in a delay in getting an SSL certificate from LetsEncrypt. So there were a couple minutes of downtime.
All told this conversion took about six hours, off-and-on. I learned a few lessons:
Choose a Jekyll theme first. This is counterintuitive to my normal processes. I usually “get it working first, then make it pretty.” I wasted about 30-45 minutes making jekyll-archives work with the default theme, minima, to properly render category and tag pages. Mundana doesn’t use jekyll-archives for category pages, and doesn’t have a concept of tags. The work with jekyll-archives was wasted.
Not all Jekyll themes are gems. Having only used the minima theme, and been used to WordPress themes, I assumed all themes are gems and follow the same patterns. I was wrong. Some themes are published as raw layouts and pages that are dropped into an existing site. I initially intended to replicate Michelle’s site exactly, and came across a a Jekyll theme based on WordPress’ Twenty Fifteen theme. I didn’t see it published as a gem, so I mistakenly thought the theme was abandoned. This, fortunately, lead us to Mundana and the knowledge around how themes are published.
Don’t forget the certificates. I planned for everything but SSL. This isn’t to say that security is an afterthought. I’ve used LetsEncrypt for a while. It’s just been so automated—via cron job for my WordPress server, and by Netlify—that I haven’t had to think about SSL certificates. I haven’t done a postmortem on this “outage,” but it could have prevented by using Netlify to handle DNS. This would have decreased the DNS delay, and avoided the missing SSL certificate error. It also would have added about 30-45 minutes to the deployment, so probably wasn’t worth the hassle in this case.
I may eventually move the other sites to static sites, but I have no immediate plans to do so. Caching hasn’t been an issue on the other sites, and they aren’t updated nearly as frequently.