26 December 2024
Choosing the New Platform for this Blog
Every time I start to think about something that might be a web project I start with WordPress, and usually decide to do something else. At the moment, this blog, and the site of a club I belong to, are the only things running on my multi-site WordPress installation. I do most of my writing in AsciiDoc or Markdown, and I prefer working in those formats to working in Post Editor on WordPress.
Because the Text Editor -> Commit -> Push workflow fits my style of working, I’ve thought about going to a static site generator and tried out Jekyll and some others in the past. On this round of thinking about it, Grav and Jekyll were the leading choices. Another platform that interested me is Payload CMS. All three of these are considered Headless CMS, which means that in contrast to WordPress, Drupal and Joomla, they are not dependent on a front end application.
Payload
While both Grav and Jekyll work with Markdown files, Payload is radically different. Payload is a framework written on top of the Nextjs React Framework. Everything in Payload is TypeScript. It will work with any backend data you will it to. To look at it in the proper prospective it is a collection of components that you build your TypeScript/NEXTjs/React with to get CMS components pre-built. When I started working with it I was hoping that it would work as an on ramp to gradually learning those platforms.
What I found is that, if I wanted it to be my platform, I needed to work from the other end and build my Java Script developer skills first. While I liked how everything became code in Payload, it wasn’t a practical choice, and it was going to be tied to a database, even if completely up to me which one.
Grav
The next choice on the list was Grav. Grav is a flat file CMS written in PHP. Like WordPress, you need to run the application live on a server. For the club site I host, Grav has a working (but not great) Administration Plugin, and Jekyll does not, so I decided to give that a go next. After working on converting both the club’s site and this blog, I came to a number of points of frustration, some of which were limitations imposed by the twig templating system it uses.
Jekyll
So finally I came back to Jekyll. After putting the effort into Grav, I found Jekyll a lot easier to work with. While Jekyll has a jekyll-admin plugin, it had dependency problems that could only be resolved by installing really old components.
Another group I belong to was organizing a major event and I decided to make a calendar app for it, in Jekyll. I was able to put together a simple app. Having a job rebuild the site every hour, I had no trouble figuring out how to make it do the opposite of normal blog behavior — only show future posts and not past ones.
Sinatra
Because the event app needed to be updated on the fly and by people who would not be comfortable doing it in vi via ssh, I needed to create a way of doing this in a browser. This is why I had gone to Grav first. In Jekyll I was able to create some forms for updating/creating posts, I know enough Ruby that I was able to create a really simple sinatra app to act as an api backend. My complaint about Sinatra, is that it is only willing to run behind a proxy if the environment is production, but I needed to proxy it in development because the Jekyll webrick development server and sinatra are two separate processes on two different ports, so I had to set Sinatra’s environment to production in development. To deploy, there had to be two sites, the public static generated site, and the other using web server authentication for the admin site running the jekyll development server and sinatra.
Bridgetown
After being able to provide limited Content functions by adding Sinatra, Jekyll was much easier to work with. Although superficially similar to Grav’s twig, the Liquid Template engine is superior. While Liquid is adequate for my needs, the BridgeTown fork of Jekyll supports erb out of the box, and lets you use both templates on the same site.
There are small changes between the two, which means you have to make adjustments, since there is far more coverage of the primary Jekyll branch. When using a coding assistant you need to remind them that you’re working with Bridgetown rather than Jekyll. As an example you might typically use site.posts to access the default posts collection in Jekyll, but in Bridgetown collections.posts.resources. Bridgetown also implements esbuild, both using the default of src/_components/js | css is easy enough, creating a src/assets folder is an easy wat to bypass the build system. For a project where the Static Site Generator was backing a more involved TypeScript application, having the plumbing already in place is a plus (the official recommendation is to use // @ts-check in vscode and not to use Typescript).
The Winner
Bridgetown. For this blog both Jekyll and Bridgetown will work well. The Gaming Club website is deciding what they want to do. At the moment I have time to build them a site in BridgeTown and pair it with a Sinatra app, even better, Bridgetown comes with Roda and doesn’t need the external app to handle the admin site, a clear win. Markdown has great portability for the next platform switch. Hosted WordPress is inexpensive if they choose to stay with it.