DEV Community

Cover image for Jekyll to Jigsaw
Jason McCreary
Jason McCreary

Posted on

Jekyll to Jigsaw

All these year in review and New Year's resolutions got me motivated. I decided use it to complete one of my own goals for the year - redesign blog. This was more or less an impromptu hackathon, which I time boxed to 4 hours to ensure I didn’t go down the rabbit hole of intricately redesigning everything.

This would be a simple facelift to modernize the template with a focus on copy, as well as a conversion of the static site generator. I decided to refactor my blog to Jigsaw. So this serves as not only my first article to christen the conversion, but also a review of the process.

Why JigSaw

My blog has been around for over a decade. I can't tell you how many times it's been converted. It originally started as static HTML, then WordPress, then Jekyll, then GitHub Pages, then Ghost, then back to Jekyll. And now, of course, Jigsaw.

Historically I used this as an opportunity to try new tech stacks. Nowadays, this is rather impractical for a few reasons.

  1. A blog doesn't really push technical boundaries. So while it may serve as an introduction, it's not going to substantiate its use for other things.
  2. My time is better spent elsewhere. If it's not a good learning opportunity, just go with something familiar. Jigsaw has a PHP core and leverages Laravel Blade templates engine. It also included a starter template developed with TailwindCSS and a little Vue.js.
  3. Both of these combined bring me to my final reason of convenience. Writing blog post is hard enough already, I don't want anything to make it harder. While Jigsaw allows me to use Blade, I can continue to use Markdown.

In the end, for me, Jigsaw balanced my time by being convenient to work with (PHP + Blade + Markdown) while still giving me some light learning opportunities (TailwindCSS + Vue.js).

Converting front matter

Although front matter is pretty straightforward, I created a lot custom keys over the years while transitioning between all the static generators. So I wrote a quick script to condense these down (and reformat) to the minimal amount of: title, description, date, categories, and a few SEO keys.

Here's a Gist of the conversion script I wrote.

Rewriting URLs

Another motivation for this redesign was to finally switch to I purchased this domain a while back, but had not made it primary. Since I was going to change the link structure for each of my posts anyway, I took the opportunity to do both.

The key thing was ensuring my URLs redirected so I didn't lose my search engine rankings. I made sure to switch the proper settings in Google Search Console and Google Analytics, as well as generating 301 redirects for each post. There was also some tweaks to the Jigsaw config and template to ensure generated URLs consistently included the trailing slash.

Here's a gist of these scripts to convert the Jekyll posts dated filenames to the dasherized Jigsaw post filenames and generate the 301 redirects.

Tweaking categories

For the most part Jigsaw was a straight conversion. The only thing that took a minute was configuring the categories. The documentation was a bit light on how these are set up (possible open source contribution…). Again since I was familiar with PHP and Blade, it wasn't too hard to dig around the code and figure it out.

Initially, it wasn't automatically generating the category pages (or collections). Ultimately, there is an source/_categories folder within the start template where I needed to create markdown files for each of my categories.

That wasn't quite it though. The categories closure in config.php also needed some tweaks. Especially since my category names were titles and contained spaces. I had two options, I could add code to generate the lowercase, dasherized URLs in the template or I could do so at build time.

Inline with my goal to keep the writing experience easy, I preferred to generate these properly at build time. So I changed the config to lowercase and dasherize the categories names from the front matter and properly group the posts. Here's the specific code as well as a Gist of the complete config.php.

'posts' => function ($page, $allPosts) {
    return $allPosts->filter(function ($post) use ($page) {
        $category = str_replace('-', ' ', title_case($page->getFilename()));
        return $post->categories ? in_array($category, $post->categories, true) : false;

Adding Read Time

Jigsaw also has fancy helper methods. This is pretty nice as it was a pain to customize such things and Jekyll - often requiring overriding or monkey patching in Ruby. With Jigsaw I simply add a closure in config.php and can reference it through the $page object just like I do the front matter.

This made it super easy to create something I wanted to add to my articles for a while - Read Time. It's a nice little UX hack to see an estimate of the time it will take you to read an article. I derived the formula from some of these calculations. Here's the specific code and also in the Gist of the complete config.php. I simply call $post->readTime() within my templates.

'readTime' => function($page) {
    return intval(round(str_word_count(strip_tags($page->getContent())) / 200));

All in all it took about 4 hours for the conversion. 2 hours were massaging the front matter, and another hour was battling the category configuration. So, in fairness, it really only took about an hour to set up Jigsaw using the starter template and begin customizing.

I plan to revisit the design, especially after reading Refactoring UI and incorporate pages for my various products and services. I like doing a little bit each time I write an article. I'll write a post and spend 15 minutes making other tweaks. So well I wouldn't call it done, I will check the box for my first 2019 goal of 2019 two redesign my blog.

Have more questions about Jigsaw? Ask me here or on Twitter. I'm glad to answer and considering packaging up some of my customizations or contributing them to the starter template.

Top comments (4)

sharu725 profile image
sharath Kumar

Nice post Jason. I would like to know why did you make the switch from Jekyll. Were there any flaws that made you switch?
I have been using Jekyll for a long time and even for a jekyll themes directory called Jekyll Themes and I love it.

pojntfx profile image
Felicitas Pojtinger

IMHO the "solution" to switching SSGs is to use Gatsby. Why? React Components are universal, so it doesn't really matter if you switch your SSG to say Next, just recreate the pages with the same components - done! Also makes it possible to use the same design system for your app (Parcel), documentation (MDX), slides (MDX), ...

gonedark profile image
Jason McCreary

Indeed, there are dozens of solutions available and as such the choice for one is quite subjective. For me, Jigsaw was a natural migration given the PHP base, with Blade + Markdown templates.

pojntfx profile image
Felicitas Pojtinger

Sure; it's a good SSG indeed. What I mean though is that you're using the SSG as a framework, an whenever you change the framework, you'll have to more or lesd rewrite your app. Using Gatsby you're writing your site/app/whatever using standard (JSX) using a library (React) - makes migration much easier later on. Not saying you're approach is wrong, I just think that it's time to stop writing web sites and rather start writing web apps (which may be implemented by a SSG, and can be just as static) ;)