🌉 Migration from Jekyll to Bridgetown

For a long time, this website has been built using Jekyll. Jekyll does its job quite well. It has a mature, battle-tested codebase, a lot of available plugins, a fairly large community, and hundreds of websites are still running Jekyll. You can do really a lot of things with it, and you are likely to be satisfied.

However, there are some problems that you might not notice at first glance, like I did. Moreover, I hadn’t noticed them for a long time until I started running into issues with further website development.

What’s wrong with Jekyll?

Shortly, it’s a little bit “outdated”. In every way. It lacks maintenance, it doesn’t release new major features, its plugins are usually too outdated, and if you want to implement something special that isn’t covered by tutorials or documentation, you’ll likely have a difficult time. If you’re cool with Jekyll and you just write stuff, then its “outdated-ness” might not bother you. Jekyll might still work for you, as it does for many others. I started noticing that I was missing something in Jekyll when I began to improve my website not just by writing but also by implementing new features. Well, what exactly motivated me to move forward:

• If you need some frontend features in your projects, it’s not an easy task with Jekyll. Your website is probably doomed to be coded in vanilla JavaScript.
• Here is also going CSS processing: if you’re looking for minifying and sourcemaps, or maybe adding some CSS packages, it’s better to forget about trying to deal with it in Jekyll.
• You have to deal with outdated gems (or Ruby itself) everywhere; usually, forking something is the only way to workaround it. Sure, you can say that it’s not a Jekyll problem, but lacking out-of-the-box features heavily encourages you to use plugins. With time moving on, it becomes harder. Dancing around version conflicts is now your daily routine.
  • For example, jekyll-assets, the only mature plugin to process assets, is abandoned (last commit was 4 years ago). To use it today, you have to fork it and update, but it’s not an easy task to do. Surely, its’ functionality, like at least hashes in CSS files, somehow should be bundled in Jekyll itself, but it’s not.
  • Another example, jekyll-spaceship, which is Jekyll swissknife with many useful functions, is abandoned too. You should either update it yourself, or consider copy-n-paste some functionality directly to your project.

And, as I found lately, there are a lot of articles about current Jekyll state and I’m not the one who is worried about:

• Is the Jekyll project dead?
• Future of Jekyll project (engine behind GitHub Pages) in doubt?
• Jekyll and the Genesis of the Jamstack.

Why Bridgetown?

So, I decided to move on with Jekyll. These days there are really a lot of static website generators: Hugo, Next.js, Nuxt, 11ty, Gatsby and so on. They are actively developing, also have a large community, tons of plugins and bundled features, and probably if you’re starting from scratch, it’s better not to start with Jekyll. All of them have their pros and cons, so consider carefully, because once you choose something, it would be with you for a long time and migration probably will be painful.

Bridgetown, Jekyll’s fork, is among the alternatives. Although it’s far from the most popular solution, I bet it’s the most painless thing to migrate from Jekyll.

What does Bridgetown offer? Tons of new features, new ideas, and new possibilities. I’m not going to describe all of them, but here are some notable:

• “Easy” migration for Jekyll adopters. “Easy” because you’ll probably still have to rewrite everything from nearly scratch, but still Bridgetown and Jekyll have many things in common, so you already know how things work here. It’s better than, for example, migrating into a completely unknown JavaScript framework.
• Integration with esbuild, npm and other things from the frontend world. No more restrictions with JavaScript and CSS.
• Templates are no longer restricted with Liquid. You can use ERB or even some exotic less-known options.
• Extended plugins API.
• Bundled support for API endpoints and file-based routing, in case if you need some. With truly static websites, you’re usually not, but now at least you have such ability.
• Expressive documentation. There is really a lot of documentation.

And much, much more. You should just dive into the documentation to get it known yourself. Also, be aware that Bridgetown 2.0 is coming soon (2.0.0-beta3 was just released), so if you’re just starting, stick to the “edge” documentation, as long as it comes with a lot of breaking changes.

Migration

Migration took me weeks until everything worked as before, but it definitely worth it in perspective. Shortly, I just created a new project, moved all my markdown content there, and started restoring functionality.

The only big problem which I encountered is that there is nothing like jekyll_picture_tag for automatic responsive image generation. All other commonly-used plugins from the Jekyll world are already implemented: bridgetown-feed, bridgetown-related-posts, bridgetown-seo-tag, bridgetown-sitemap. Also, here you can find a curated list of official and third-party plugins.

Frontend integration works great, there were no unsolvable problems with it. JavaScript and CSS files are processed like they should be. As example, I easily configured open-props and PurgeCSS which would be a nightmare on Jekyll.

Also, I would like to highlight HTML and XML Inspectors API, which allows you to easily manipulate your HTML output. With this thing, you can painlessly add custom code to your generated pages, which was extremely painful with Jekyll.

Meet bridgetown_picture_tag

As I said, the only problem was the missing plugin for generating responsive images. So, now it’s here: seroperson/bridgetown_picture_tag. It’s a fork of jekyll_picture_tag, but adapted for Bridgetown. Everything works completely the same, so you can follow the docs from the original library. Also, I added a working Bridgetown example in tests.

To get it into your project:

gem "bridgetown_picture_tag", git: "https://github.com/seroperson/bridgetown_picture_tag.git"

Just a beautiful doggy (webp cropped to 5:4 ratio with various responsive sizes)

However, I’m not an involved Ruby developer and did it just to satisfy my website’s needs, so I’m not going to actively develop this. I still wait for a native solution or maybe for someone who will maintain it nicely. I saw that original author was willing to unify this solution to work for both Jekyll and Bridgetown, so probably that’s what we need. I created an issue there, maybe it will result in something.

Conclusion

Thank you for reading this little article, I hope it will be useful to someone. Feel free to reach me if you have something to say.

And also take a look on the posts on similar topics:

• 🔄 Yet another way to establish Notion + Jekyll synchronization
• 🌐 Building Jekyll website with Nix
• 🖼️ Notion + Jekyll images synchronization