How to convert markdown to Kirby blocks at scale


I have a blog with hundreds of articles in markdown files with YAML frontmatter.
The site is built with Jekyll and I would like to move it to Kirby.

The goal is to have all blog articles converted to Kirby-compatible files/folders with the correct permalink and the markdown content converted to Kirby blocks.

With a little bit of time, I can probably write a script to convert the markdown+frontmatter files to Kirby content files/folders. But particularly the conversion of markdown to Kirby blocks will probably take some time.
I would imagine someone has done this before. So I’m hoping to find help here?

(PS: I found this but it’s quite outdated, without documentation, and I’m not very experienced with PHP and not sure how I’d use this repo)

Hi, take a look at this Cookbook from @texnixe

Thanks a lot for sharing! From what I can tell this doesn’t automatically map to Markdown, though, right?

I’d first have to turn my Markdown into HTML and from that create an array elements (headers, text, quotes etc). With that I could then convert each individual block. I guess that’s possible. I was hoping for a less manual approach.

You can convert from Markdown to HTML programatically, Kirby is using YAML and Markdown.
I have done something similar migrating from Kirby v2 to the new Kirby Blocks:

$posts =  $page->children()->listed(); // get the posts collection

foreach ($posts as $post) { 
  $text = new Kirby\Cms\Block([
    'content' => [
      'text' => $post->text()->kt(),  // convert from Markdown to HTML
    'type' => 'text',


     'text' => $text,

You’ll probably need to do a bit more to format the Jekyll content to Kirby but I hope that will serve as a starting point.
I hope this helps.

Thank you for the code example!

Do I understand this correctly that it’ll put all HTML (including headers, images etc) in a single Kirby block instead of multiple blocks?

I’ll give this a try, though.

The blocks field supports pasting of HTML content and automatically converts this pasted HTML to blocks. So I would expect it to be possible to use this feature programmatically to convert Markdown parsed to HTML into blocks.

1 Like

When calling the update method, the HTML generated in $post->text()->kt() is converted into Kirby Blocks of type header, image, text, list… automatically. If you want to keep everything in a single field, that’s fine.
In my case, what I find is that the image blocks were transformed to images with absolute paths in which you could not work well for the migration and I had to detect the image blocks and modify them so that they were inside the Kirby panel.

I leave you a Gist that I have published for you to see, I hope it sheds a little light on you.

Ah, that’s great, wasn’t aware of that.

1 Like

I hope I have understood it well, I am not a programmer and I have tried to explain it as I understand it :sweat_smile:

It’s been a real long time but I wanted to let you know that the solution worked as described. It only worked once the blueprint had the field defined as blocks.

And as you said, it automatically created multiple blocks for the different HTML tags. Thanks for the help!

1 Like

Perfect, I’m glad it worked for you :clap: