How does the blueprint syntax work?

Hi, I have a hard time wrapping my head around the new blueprint structure and syntax, transitioning from Kirby 2 to 3. My context: I have created several websites in Kirby 2, all with some panel alterations. I have read all the blueprint documentation and looked around in the starterkit.

A few questions regarding the blueprints in Kirby 3 starterkit:

I read in the blueprints 3 different ways to refer to ‘pages’:

  • pages:
  • type: pages
  • preset: pages

What is referencing to what? And what does ‘pages’ mean in each situation?

I read in the site.yml of the Starterkit:
- about
- home
- default
Why is this referencing to the template? And what does it do?

I looked into the Starterkit blueprint sections. I’m totally lost…
Site.yml refer to the albums like this:
albums: sections/albums
Why does it refer to sections and albums twice?

type: pages
headline: Photography
parent: site.find(“photography”)
size: tiny
info: “{{ page.images.count }} image(s)”
layout: cards
template: album

So many questions here:

  • How can it be “type:pages” when it’s a section?
  • What does “parent: site.find(“photography”)” do?
  • what does a template mean in this context? Does this refer to the blueprint pages ‘album.yml’?

I get the feeling these 3 blueprints interact with each other:

  • albums.yml
  • album.yml
  • photography.yml

Please help me understand this complexity! I’m getting error’s for hours, trying to configure the panel.

Not quite sure what the first bullet point refers two.

Ad 2. type pages can be either a pages field or a pages section

A pages field stores the selected pages in the content file, a section doesn’t. It’s only there to create new pages.

Ad 3. That is a preset: Pages | Kirby CMS

A quick way to create a page that is mainly a container for subpages (e.g. a blog page)

The template option filters the pages that are shown in the section and only displays those with the given templates/blueprints.

The pages section is defined in /site/blueprints/sections/albums.yml

It queries the parent page, in this case the photography page. The section will then show the children of this page.

photography.yml is the blueprint for the parent page
album.yml is the blueprint for the subpages of the photography page
albums.yml is the section blueprint, instead of defining it three times in the photographyblueprint, it is “outsourced” and reused: Reusing & extending blueprints | Kirby CMS

Thank you for the quick reply, and helping me out.

The first bullet point (pages: ) is listed in the site.yml like this:

  • width: 1/2
    type: pages
    create: default
    - about
    - home
    - default

I still don’t understand how the album section is build up. How is the photography page a parent? And if it’s a parent why does it need to be referenced, or searched in the site, because it already is a parent…

Why does the section “albums.yml” need to be there in the first place? Why not list it like this:
type: pages
create: album
- album

Well, a section has a name (pages in this case, but you can call it anything), a type (pages in this case, but there are also files sections, fields section or info sections)

It is a parent because it has children (album pages), the logic is the same as in Kirby 2.

I already answered it above, to prevent having to repeat the same stuff over and over again if you want to use the section in multiple places, in this case in the site.yml and in the photography.yml. It keeps your blueprint clean. Of course you don’t have to put the definition into a separate file if you don’t want to, but it is highly recommended.

Alright, it all becomes a bit clearer now.

The section name still feels weird. I read it like “sections: blank” “pages: blank”. Wouldn’t it be easier to read if it stated “sections: pages”?
Anyway, I digress…

Still can’t grasp the section blueprint setup. It’s probably me. I will leave this for now. Always good to have something to learn :slight_smile:

Thank you very much for your help!

Maybe go through the guide step by step again. The blueprint setup in Kirby 3 is more complicated than in Kirby 2, yes, but it gives you a lot more flexibility to create the forms just as your clients need them.