Upgrading my site to Kirby version 4

Dean Verleger

Posted / in Technical

I just finished upgrading Kirby CMS for a client site and decided to keep up momentum and upgrade my own site as well. The first upgrade project was from version 2 and rather involved. My site, the version 3 upgrade, fell together without much issue in comparison. That said, each project had its own learning experiences.

Converting kirby-builder to Blocks

The biggest source of work on the v2 upgrade had to do with Kirby having introduced the Blocks system as a way to enable ‘Page builder’ with core functionality.

A ‘Page builder’ experience is a common CMS feature typical of marketing sites. It’s differentiated from a WYSIWYG or rich text editor by allowing content to be constructed as a series of distinct and specially formatted elements. These elements can vary in terms of semantic meaning or design representation and may rely on specific data points being indicated (i.e., URLs, options, or subheadings). As I implied, this feature is old news. WordPress added it as a core part of their CMS back in 2018 in their “Gutenburg” update (granted, it seems to be routinely ignored in favor of more feature-rich plugin alternatives like WPBakery).

The Kirby v2 site used such a plugin, kirby-builder, to build its page-building content entry experience. The main difference between this and Blocks is the way editor previews are handled. Kirby Blocks use Vue templates for editor previews where the kirby-builder used php snippets. Thus, implementing Block previews requires some comfort with view logic and templating in Vue.

Kirby has 3 docs sites: Guide, Reference, or Cookbook. I was eventually able to find reference on vue templating for kirby block in the Cookbook.

Plugin directory

Just about every 3rd party plugin used on these sites were incompatible with Kirby 4. The silver lining is that Kirby has a healthy plugin directory. Consistently, I was able to find some good option for one-off functionality: sitemaps, robots.txt, feed generation, SEO and meta tags, redirects, form submissions. Two favorites: SEO and Redirects.

Kirby plugins are great for site development

I found that Kirby plugins are an intriguing way to organize development in general. It seems all framework features can be implemented in a plugin. Thus, all the code for a particular feature can be organized modularly and logically.

I.e., the blueprints, snippets, and previews for custom blocks can all be stored in the same plugin.

<?php
Kirby::plugin('cookbook/block-factory', [
  'blueprints' => [
    'blocks/awesomeblock' => __DIR__ . '/blueprints/blocks/awesomeblock.yml',
    // more blueprints
  ],
  'snippets' => [
    'blocks/awesomeblock' => __DIR__ . '/snippets/blocks/awesomeblock.php',
    // more snippets
  ],
]);

The same goes for features involving controllers, routes, models, and templates.

For fun, I split my wiki and blog functionality into plugins. I’m curious what other open-source features are out there, ready to be dropped into a Kirby site.

Last updated