The Hidden Blog

As it turns out, I do have a hostname.

Kirby: Build your own custom block

Published on May 08, 2025

For the new "Photo Post" entries I've recently added here I wanted to have a way to reference them from my text posts. Ideally there would be a preview of the images and an easy way to open the full photo post directly from that inline module.

Here's an example of the final result:

It turns out this is all relatively easy with Kirby. All we need are the following bits:

site/blueprints/blocks/photopost.yml

Here we create a new block type, the query prepopulates the select field with our list of photo posts.

name: Photo Post
label: "Select a photo post to inline a preview of the post."
type: photopost
preview: fields
fields:
  photopost:
    label: Selected Photo Post
    type: pages
    query: site.find("photos").children().listed().sortBy("date", "desc")
    multiple: false
    required: true

In our regular post template we need to add that new block type to the selection, an excerpt from that looks like this. The important part is the photopost block in the fieldset.

site/blueprints/pages/post.yml

title: Post

columns:
  - width: 2/3
    fields:
      title:
        label: Title
        type: text
      blocks:
        label: Content
        type: blocks
        help: Build your post content using blocks.
        fieldsets:
          - ...
          - photopost

site/snippets/blocks/photopost.php

The last part is the template that will help us render this inline photo post. In my case I put some of that logic into another snippet just to make it cleaner. The photo_entry_inline will just iterate over the images in the photo post and output them with some styling.

<?php
$photoPages = $block->photopost();
$photoPagesArray = $photoPages->value();
foreach ($photoPagesArray as $pageUuid) {
    $photoPage = $site->find($pageUuid);
    snippet('photo_entry_inline', ['photo' => $photoPage]);
}

That's all we need to get it our custom block up and running.

New block type in the selection on a new post
Selecting the photo post to reference
How it looks in the editor

There's great resources from Kirby itself too (of course), like this video on the YouTube channel and the Custom Blocks Documentation.