How do you setup/arrange your site blueprint?

It’s my first encounter with the new Kirby 3 blueprints, and I wondered how you approach these new possibilities for setting them up?

How do you setup your site.yml-blueprint? Do you tend to fall back on certain patterns? Do you focus on the “site structure” (e.g. via a section which mimics the site’s navigation) first, or deep dive directly into (certain) deeper parts?

The approach I took was to split away the common stuff i use into plugins. Most of the sites I build are 80% the same same in terms of data i need to collect. Essentially all these hang of a tab for each kind of information. For example, I have and SEO tab, a publishing tab, Social Media tab for open graph etc… You get the idea.

This means my site & page blue prints are pretty light and I build most of the site from existing tabs and blue prints. I use extends and field groups a lot too,

I also built a hero image system in its own plugin that be dropped into any site. It makes heavy use of conditional fields in order to generate fancy hero areas using slides, videos, images and text.

I use my site.yml to store things like global SEO data, the branding for the site like logo image files, and its here that I list out the sites content but I tailor this part to the needs of the current site, rather then just simply list out pages.

Just to illustrate what I mean, heres how the hero plugin is setup:


Kirby::plugin('hashandsalt/forgehero', [

    'snippets' => [
      // HERO TYPES
      'herocontent'     => __DIR__ . '/snippets/herocontent.php',
      'heroimage'       => __DIR__ . '/snippets/heroimage.php',
      'heroslides'      => __DIR__ . '/snippets/heroslides.php',
      'herovideo'       => __DIR__ . '/snippets/herovideo.php',
      'hero'            => __DIR__ . '/snippets/hero.php',

    'blueprints' => [
      // HERO FIELDS
      'image'        => __DIR__ . '/blueprints/fields/image.yml',
      'slides'       => __DIR__ . '/blueprints/fields/slides.yml',
      'video'        => __DIR__ . '/blueprints/fields/video.yml',
      'split'        => __DIR__ . '/blueprints/fields/split.yml',

      // TABS
      'tabs/hero'        => __DIR__ . '/blueprints/tabs/hero.yml',


Hope that helps.


Great idea, I’d love to see how the site.yml of others look like!
I started with something very Kirby 2-esque at first, but there are so many possibilities!

Most of the time I display a pages section (or multiple sections for different menus) and some “shortcuts”, or how you call them, “deep dives into deeper parts”.

Sometimes I need a global file pool which goes into a tab, and a tab for meta information.


For my first K3 site I had to refactor the blueprints a few times. The flexibility with panel layouts also makes it easy to develop completely different layouts for different templates, and in the end I had to spend some time to find patterns and bring consistency in the panel. I’m still in the process of figuring this all out.

For the site.yml I have a setup similar to @thguenther. I also tend to put files fields in their own tab, because I like to display files sections next to the files fields.

Two modifications in the panel.css: a ‘blank’ theme for info sections (without a background color & indentation), and a max-width + auto margins on textareas because full width textareas work fine on medium screens but become unwieldy on large desktops.


This :point_up_2:

It’s where I am at atm. I don’t want to confuse the editors.
So I hope to learn something from your findings.

This really depends on your field setup I’m afraid — can’t distil a general rule. After I was done building all the blueprints, I took screenshots of the panels, printed them out side by side and then tried to unify as much as I could.

If you find yourself reusing some patterns, extending blueprints is the best path to uniformity. Use fields, layouts and sections blueprints.

I’m very interested to hear more about your issues with consistency. Which parts made you struggle the most and what could we do to simplify this?

For me personally it’s not something you could/should easily change. There are so many different ways of setting up the blueprints in version 3, but it’s important to not reinvent the wheel on every page. At least on the same project.

“With great power comes great responsibility” :upside_down_face:

As @phm mentioned, it’s a lot more important to reuse patterns and extend blueprints now. Maybe it would be a good idea to write a best-practices page for the docs or so? It does sound a bit more “optional” than it really is for most projects:

Something that could help (new) developers as well as communicate Kirby’s strengths would be a “Blueprints” page on the website — like a “behind the scenes” of Kirby websites. Similar to the Plugins page, this could have a filter with stuff like “Photography”, “Landing page”, “About us”. I’m sure the (Slack) community would be happy to contribute screenshots/blueprints.


Bear with me since I’ve not played a lot with the panel yet (I’ve just started actually).

For me it’s the quest to:

  1. Avoid confusing editors who are used to work with the Kirby 2 panel
  2. Find a way to use the new possibilities to the max, preferably via patterns (I know extending can help here).

I like that there’s presets that mimic the K2 paradigms (pages + files sidebar, combined with the fields-section). Given that we now can break out of that paradigm in contexts that don’t take advantage of that kind of layout, we should use them responsibly (to avoid confusing layout-shifts when editors browse through the panel from content-type to content-type (aka template).

What I am struggling with is the “dashboard” when you login in the panel (~ the site-blueprint). It’s a blank canvas now, that needs to be filled in somehow. For smaller sites, I think it’s easy to find the content-based top tasks (e.g. add a blog post, add a news article, …), and focus on that with the sections you’re providing.

For sites that are a tad larger, or use a few plugins which expose options that need to be set or seen, you have to plan a bit better to make the on-boarding experience not overwhelming, but also not over-simplified. Perhaps custom widgets can do miracles here in providing some kind of overviews (such as “latest activity”, “error logs”, “shortcuts to create common content”, …)?

And how would you handle “global” settings (such as e.g. default mailto-addresses, theme options, …)? Do you plunge it all in separate tabs? Or is it possible to add stuff to settings, or even come up with our own page in the settings-dropdown?

I am interested in how other devs feel about this and how they approach it, so screenshots would be great.

1 Like

I struggled a bit with this too… I have ended up putting things I would have put under settings with K2 into tabs that I can plug into the most appropriate page. For your email example, I have a Business tab that has fields in it for anything to do with a companys contact details, and the locator field for the business address. I use this info to power structured data for SEO, and contact form recipients amongst other things. However I do miss being able to house it all under settings.


Hey there I see you’ve accomplished to build multiple panel pages and navigate between those. I’ve been trying to do this for the past 2 days and i’ve not been succesfull yet.

Would you be so kind as to explain to me how i can accomplish this ?

I think you mean the tabs in the screenshot @thguenther posted. You can learn to set these up here - Tabs | Kirby CMS

Hi thank you very much it worked

What I would like is a complete set of blueprint files to update a Kirby Starterkit v2.5.12 to Kirby 3, where the Kirby 3 panel looks like the Kirby 2 panel had looked.

I have many problems to get a feeling in the new panel for editors, who had used the Kirby 2 panel for many years.
The new Starterkit is for my blueprint-file knowledge to different to the „old“ Starterkit from Kirby 2.

An additional Cookbook page with hints would be a nice add-on.

What do you think?

@anon77445132, apart from the site-blueprint (the one that is shown when you login to the panel), I think the team has done a wonderful job in providing presets that mimic the K2 panel-layout as much as possible (except that the sidebar is on the right now - which I like better :wink:).

I believe the impact to shift from K2 to K3 blueprints should be minimal if you use those presets. So the UX-impact for the editors can be limited to learning the new dashboard (I’m still pondering on how to handle this tbh), and getting used to the new statuses (which can also be configured to how K2 used to work IIRC).

Personally I think we should not try to firmly hold on to how K2 used to work (it can work as intermediary for editors who really have a hard time for getting used to the new panel), but embrace the new possibilities the K3 panel brings us. As I read the comments above I think most feel the same, but are also on the lookout for patterns that work best.


Thank you for your opinion, which is fully ok.

But I follow „Never change a running team“, this includes not to change left and right.
Therefore I cannot use the presets, they change left and right.

For a website, running since Kirby 2.0.x, for my opinion I need the old layout of the panel, sadly not full possible at the startpage (site.yml) of the panel.

During the last 30 years I heard from the users a „help“ outcry, when something like this has changed.

All my users use Windows at home and at work, so I need the same outfit in the panel.
Within Windows all dialogs I remember, haves the files and directory window on the left part of the dialog. The Windows Explorer looks analogous.

So I need, what I have written in my last post to understand the new blueprint file possibilities. I will work on it.

If someone finds such an set of blueprint file, please give me a link. Thank you.

@anon77445132 Basically, a K2 clone would be a layout with two columns:

title: K2 clone


    - width: 1/3
        # add a pages and files section here as required
    - width: 2/3
        # add fields here

But this is off-topic and we should start a new thread if you want to continue this.

But as much as this layout makes sense for typical content pages, it was never very useful for container pages (think blog page), where the empty space on the right never made much sense, unless you filled it with @flokosiol’s subpages plugin and removed the sidebar.