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.



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