Using Jigsaw as My Static Site Generator cover image

Using Jigsaw as My Static Site Generator

Posted on July 7, 2019


I've been looking for a PHP static site generator for a while. So when I saw that Jigsaw was built not only on PHP but on Laravel as well, I was already sold.

It also ended up being a perfect excuse to reboot this blog and start talking about software again (it's been too long).

Turns out, developing a blog with Jigsaw is quite a bit easier than other static site generators I've used, most notably GatsbyJS.

While I love used React to build my previous site, I had a hard time getting used to the GraphQL syntax. Also (and probably the most annoying thing about using JavaScript to power a static site generator (SSG)) was the onslaught of constant updates to JavaScript packages.

In comparison, PHP packages undergo a much less grueling release cycle than their JavaScript counterparts.

For those looking to maintain a PHP workflow in a SSG world, here are my top 3 favorite things about Jigsaw:

1. Familiar Environment

Of course, I already alluded to this but it deserves repeating. I'm a PHP fanatic. I mean, I love PHP. It's one of the main reasons I've stuck with WordPress for so long, despite its frustrating transition into modern technologies.

I mean, just look at this config file (which looks so wonderfully familiar to a WordPress-born developer):

<?php

return [
    'baseUrl'    => 'https://www.calvinkoepke.com',
    'production' => true,
];

Beautiful. And not a whole lot different than the environment files I build for my WordPress websites.

2. Blade Templating

Before switching to Jigsaw, I didn't have much experience with Blade files. But they have a low learning curve, especially if you've lived PHP for any amount of time. Blade files make it easy to do basic things like loops and conditional statements, and even support hooks using syntax like @stack and @push (examples below).

The main benefit of a Blade file (IMO) is that you don't have to do all the <?php opening and closing tags that normally interrupt HTML in PHP. With Blade conditionals, it just flows.

To give you an idea, they look like this (taken from my header.blade.php file):

<link rel="home" href="{{ $page->baseUrl }}">
<link rel="icon" href="/assets/images/logo-small.png">

@stack('meta')

@if ($page->production)
<!-- Analytics code here -->
@endif

This does 3 notable things:

  1. The brackets you see that look like this {{ content }}? Those parse dynamic data, sort of like echoing PHP inside of HTML.
  2. The @stack('meta') instance lets me push other code to that section, by doing things like @push('meta') CONTENT @endpush.
  3. I can check environment variables to output conditional code, as seen in the @if section.

3. Powerful Architecture

One of the great things about Jigsaw is how it handles content relationships. Essential, the project structure handles all content in the form of collections.

This lets me set up a collection of posts, notes, and even categories like PHP and business.

But the cool part comes when I can tie collections together through the front matter. For instance, in this particular post, my front matter looks like this:

---
extends: _layouts.post
section: content
title: Using Jigsaw as My Static Site Generator
date: 2019-07-07
description: Why and how I started using Jigsaw as a static site generator for my personal website and blog.
cover_image: /assets/images/using-jigsaw-static-site-generator
categories: [php, architecture]
featured: true
---

To over-simplify, Jigsaw parses the categories meta as an array, just like it looks. Then, in my config file, I can generate a list of posts that have matching categories:

<?php

'collections' => [
    'categories' => [
        'path'  => '/articles/categories/{filename}',
        'posts' => function ( $page, $allPosts ) {
            return $allPosts->filter( function ( $post ) use ( $page ) {
                return $post->categories
                    ? in_array( $page->getFilename(), $post->categories, true )
                    : false;
            } );
        },
    ],
]

It takes a bit of getting use to, but the real power of Jigsaw comes in when you realize that you're building a site using PHP like normal — but with the benefits of SSG as well.

Summary

I plan to contribute to the Jigsaw SSG since I see a lot of potential in it. Namely, building a CLI to manage commands seems like a win, since I currently have to run bash scripts to start a server and then open a new terminal to run the file watcher.

Also, since Jigsaw uses TailwindCSS, I'm even more excited about how easy it is to get up and runnning quickly.

Have you used Jigsaw? I'd love to hear how it's gone for you!

Start the Conversation on Twitter

Filed Under: