If you take a look around you might notice that our blog looks pretty different. We’ve migrated to a completely different platform, and we took the opportunity to make some changes to bring the site more in line with our current systems philosophy and modern web design. The RAC has changed a lot since Bits & Bytes first launched, and we thought that the blog should reflect those changes. This post will lay out the reasons we decided to switch things up, the process of migrating the data, some of the technical improvements under the hood, and where we go from here.
Bits & Bytes posted its first article on August 15th, 2012, and there have been about two hundred posts since. A lot has changed in that time: only one member of the D-Team from 2012 is around, the scope of the blog has moved beyond just D-Team work, and we now have many coworkers from other departments posting about what they do and how they do it. Besides the aforementioned changes, we’ve made great changes to how we, as an organization, think about our systems and their implementations. As others have written about over the years, the RAC has become increasingly invested in choosing the right tool for the job, rather than just the (seemingly) easiest tool for the job. Our technological choices should make sense for both the people using and maintaining them.
For the past six and a half years, Bits & Bytes has run on WordPress. WordPress was great for the team when we launched the blog because it was easy to set up, we could author posts in a friendly UI, and it could store all of the media files we needed in its backend. However, as time went on we started adding more plugins, more people wanted to write posts, and the D-Team, who were the de facto administrators of the site, had less and less time to spend on maintaining it. As Hillel has talked about before, it’s hard work to keep systems maintained. Updates for WordPress kept piling up and taking our time, we kept having to add new users, and we had to make sure the server was up to date. It became increasingly clear to us that a full WordPress installation was unnecessary for the type of work we were doing, and was taking more of our effort to maintain than we desired. We weren’t making multiple posts a day; we averaged a single post about every 11.5 days over the lifespan of the blog. Additionally, the blog’s design looked dated, did not meet modern web accessibility compliance, and it didn’t display well on mobile devices. It was time for a change.
Our first course of action was to identify a proper replacement. We immediately fell in love with the idea of migrating to a static site generator. Most of the sites the D-Team creates these days are static sites, generally run off of Jekyll. Static site generators are much simpler than CMS platforms like WordPress because they don’t have underlying software and databases to maintain. They store HTML files and digital files in a file system, and work by serving these files directly. Jekyll transforms plain text like Markdown, HTML, CSS, and Liquid into static sites. Additionally, GitHub Pages natively supports direct hosting of Jekyll sites, meaning we could maintain and version all of our code through GitHub. We’d have complete control over all customizations, would minimize server downtime, and could easily add content or change styling whenever we wanted. Migration from WordPress to Jekyll is well-documented and common, so it would require very little work to get the data out of WordPress, and we could spend most of our time updating Bits & Bytes for mobility and accessibility.Our only worry with using Jekyll was that it would be slightly more difficult to author content in Markdown than using a text editor. However, given the widespread success of the Documentation Project, we believed that our coworkers already had the skills and wherewithal to transform way more complicated documents into Markdown.
Once we had decided on our desired platform, it was time to move forward with the migration. At the beginning of the project we had several stated goals:
- Migrate WordPress posts, metadata, categories, and tags to Jekyll without breaking existing links
- Refresh design to meet mobile and accessibility requirements
- Explore Docker containers for Jekyll-based websites
- Explore tools to assist with Markdown writing and editing and create an annotated list of options
As mentioned above, the switch from WordPress to Jekyll is pretty common and well-documented, so we knew we had a great shot of getting everything out of WordPress fairly easily. We ended up using the WordPress to Jekyll Exporter, which created a zip file of all posts in individual Markdown files, all related media files, and wrote associated metadata to the YAML front matter of each post.
Unfortunately, while the plugin is great at getting the content out of WordPress, it doesn’t intrinsically change the built-in styling to Markdown-friendly formats. Which means we had a lot of direct HTML and CSS markup coded directly into files, some of which worked, and some didn’t.
After getting the content into Markdown, our first priority was to perform QA and QC on every exported post, so we threw all of the data up into a private GitHub repository so we could work collaboratively and version all changes. The turnaround time on this project was about 3 months, so I enlisted the help of documentation team (Hannah Sistrunk, Katie Martin, and Darren Young), and Hillel Arnold to help go through all of our posts looking for anything out of the ordinary, creating issues in GitHub, and making small changes when necessary. All-in-all we had about 25-30 issues related to Markdown cleanup tasks like: removing non-breaking spaces, converting bold text to headings when appropriate, simplifying link formatting, adding support for multiple authors, and other smaller styling issues. With all of the issues documented in GitHub it was relatively simple to solve 90% of them with quick find and replace operations or regular expressions, and then the rest were limited enough that we could manually change the Markdown without it taking excessive time.
Once we had our data in a (relatively) clean state, it was time to think about how we wanted our blog to look. Jekyll, being a widely adopted platform, already has a robust community of creators making publicly available base themes ready for customization. Why rewrite code that we don’t have to if we generally like the look and feel of a site? We ended up going with the Type Theme for a few reasons: its code was laid out in a clean way, it didn’t rely on a lot of plugins, it had mobile responsivity, and its single-column layout looked clean and uncomplicated to us. It had built-in support for basically everything we wanted to do; ultimately, we added functionality to display categories on posts, support for multiple authors on a single post, a page for lists of posts by authors, and a page for posts by Category. Working with a well-designed Jekyll site is easy because everything is laid out in separate files; I had a lot of fun messing around with the code and making small stylistic tweaks, like changing colors to fit with the RAC theme, adding a CCBY license and image, and creating the Authors and Categories pages.
The biggest issue that we ran into was redirecting our old blog posts to the new site. We had ids and permalinks for all of our blog posts, so you would think it wouldn’t be too complicated, but Jekyll, unbeknownst to us, does not handle query strings in URLs well. All of our old posts were permalinked with query strings, a setting that we had chosen many years ago in WordPress. We were left with two choices: either break all of our old links or find a way to make redirects work. We thought we almost had it with the Jekyll Redirect From plugin, but it wasn’t able to handle query strings either. Luckily, Hillel had the bright idea to add a JavaScript redirect to our home page that looks for a post’s id and works from there. We’d be able to move forward without leaving others that had saved our posts out to dry.
We also wanted to make sure that we were as WCAG 2.0 AA-compliant as possible. Hannah had already done a ton of work on accessibility for Aurora, so she took a look at the site, ran it through WAVE and Siteimprove, and then filed some issues on the repository. The most common issues we ran across were insignificant color contrasts, not enough distinguishing features to a link besides color, and lack of alt labels for some of our links that were just icons or images. Ultimately, none of the changes were particularly difficult to make, but we wanted to make sure we fixed as many as we could before going live. We’ve long said that the D-Team works with a user-centered design approach, but we’d be hard-pressed to say that we truly take our user needs into account if we didn’t spend designing systems that anyone could use. As Hannah noted in her writing about universal design, our goal is to be inclusive from the outset.
Our last two goals were to explore Jekyll container options and to create an annotated list of tools to help authors write in Markdown, both of which were pretty easy lifts. A functional Jekyll Container for Docker already exists, and the Documentation Team already did a lot of work on identifying tools that can help author Markdown, like Pandoc. As is often the case with digital archives projects, most of our time was spent on QA and QC work, or tinkering with small settings under the hood of our new site.
I wouldn’t call any of the work that we did to migrate the blog particularly revolutionary, in fact, other people had really done a lot of work for us before we even started. So why am I writing about this? The new Bits & Bytes is another stepping stone along the RAC’s path to adopting a more holistic approach to technology and the organization’s willingness to learn about and adopt new technology. The D-Team has worked hard over the past six and a half years to help the RAC become an institution with a more cohesive technological philosophy, and this new blog is just one example of how we’ve grown as an organization. We’re not worried about people being too scared to create a GitHub account or write something because it will have to be in Markdown, because they’ve already shown us that they can do it.
So, welcome to the new and improved Bits & Bytes blog, we hope you enjoy your stay! Stay tuned for more updates from us soon.