Stefan Zweifel

Notes on rewriting my Site with Jigsaw

• 2 min read

A couple of weeks ago I've decided to rewrite my site with Jigsaw.

The reason is simple: Static site generators are on vogue right now, just serving HTML comes with a lot of benefits and Jigsaw is one of the few generators written in PHP which I really like.

Previously I've used Kirby to power stefanzweifel.dev. It's a great CMS and I still enjoy working with it (their recent 3.0 release looks great!), but for my personal site I wanted to "go back to the roots" and use a static site generator. Having a folder with HTML-files makes deploying and scaling much easier.

As mentioned above, I've chosen Jigsaw because it's written in PHP, uses Blade for templating and uses Collections. All stuff I know very well and enjoy working with it.

I've used Jekyll in the past (this blog was once powered by Jekyll 5 years ago), but I don't know Ruby. I ran into errors, didn't know how to fix them and got angry about the tech stack.

Next, Gatsby, Nuxt and VuePress all look great and but are written in JavaScript. I know JavaScript well enough and love working with it in bigger applications, but when writing for my site I don't want to deal with random dependency issues, webpack configurations or other random quirks of the JavaScript eco-system (Exhibit A).

Starting a new Jigsaw project is super simple and migrating all the content of my site to Markdown only took me like 1 to 2 hours.

I had the most fun figuring out how to improve little details, like:

As with every piece of software out there, there is stuff that you don't like or could be improved. The points I'm mentioning below however, are not directly pointed to Jigsaw but rather the underlying Markdown package Jigsaw uses (Parsedown) or the Markdown spec itself.

  1. No support for the figure/figcaption element: To add images to a Markdown documents you use ![]() (spec). Parsers will convert this syntax to img-tags. This is fine, as the spec says it should just render an image, but I would like to be able to use the figure-element instead, as I think it makes more sense in blog posts.
  2. Footnotes are broken: This is something that bugged me in Kirby too. The current stable release of Parsedown can't render footnotes correctly (see #118). A fix has already been merged into master, but no stable release of v1.8.0 has been tagged yet. So this is something that will be fixed soon.
  3. Extending Jigsaw or Parsedown without overriding core classes: The above points could be fixed, if I could hook into those packages and monkey-patch the implementations myself. A pull request for "Hooks" has been submitted to Parsedown, so maybe I might be able to do this soon.

Overall, I'm happy that I made the switch. Working with a static site generators brings me joy and the overall speed improvements are great.

Next on my list is to migrate the site to Netlify and open sourcing the code on GitHub.