🚀 A new era: Kirby 4 Get to know
Skip to content

Structuring blueprints

With blueprints you can create highly customized layouts that display the perfect interface for any type of data.

Just some fields

The most simple setup of a blueprint is a form with just a few fields. For this setup, you can add fields using the fields keyword, then add your fields underneath with proper indentation:

title: My blueprint

fields:
  headline:
    label: Headline
    type: text
  text:
    label: Text
    type: textarea

For more sophisticated setups, you can use sections, columns and tabs to create nice layouts.

While you can use just the fields keyword either like above in the blueprint, but also in columns or tabs, if you want to mix sections and fields inside the same blueprint, column or tab (see below), you need to wrap your fields inside a fields section.

Columns

A blueprint layout is made up of columns, and each column can hold any number of sections. Kirby ships with the following section types:

You can combine those section types in any way you like and also use multiple sections with the same type in a single blueprint layout.

For some page types you might need a list of all subpages, files and a few form elements, whereas for other page types you just need subpages or a gallery. With sections, all this is possible.

Screencast

A closer look at pages sections

Show subpages as cards or list, add additional info for each page, control the card design – there are hardly any limits.

Defining columns

Columns can be defined in two ways:

Named columns

title: My blueprint

columns:
  left:
    width: 2/3
    sections:
      # sections in the left column
  right:
    width: 1/3
    sections:
      # sections in the right column

Unnamed columns

title: My blueprint

columns:
  - width: 2/3
    sections:
      # sections in the left column
  - width: 1/3
    sections:
      # sections in the right column

If you want to extend columns, you have to use named columns.

The following widths are available when defining columns:
1/2, 1/3, 1/4, 2/3, 2/4, 3/4

Sticky columns

You can make an entire column sticky. This can be handy for a setup with a smaller sidebar that should always be available, even when you scroll.

columns:
  - width: 1/3
    sticky: true
    sections:
      # sections in the sticky column

Adding sections

Once you have set up your base column layout, the fun part begins, and you can now add some sections.

title: My blueprint

columns:
  # main
  main:
    width: 2/3
    sections:

      # a simple form
      content:
        type: fields
        fields:
          headline:
            label: Headline
            type: text
          text:
            label: Text
            type: textarea

  # sidebar
  sidebar:
    width: 1/3
    sections:

      # a list of subpages
      pages:
        type: pages
        label: Subpages

      # a list of files
      files:
        type: files
        label: Files

Result

You can probably already see how flexible this is. By slightly changing the columns, we can change the interface drastically.

Sidebar on the left

title: My blueprint

columns:

  # sidebar
  sidebar:
    width: 1/3
    sections:

      # a list of subpages
      pages:
        type: pages
        label: Subpages

      # a list of files
      files:
        type: files
        label: Files

  # main
  main:
    width: 2/3
    sections:

      # a simple form
      content:
        type: fields
        fields:
          headline:
            label: Headline
            type: text
          text:
            label: Text
            type: textarea

Two Sidebars

title: My blueprint

columns:

  # sidebar left
  left:
    width: 1/4
    sections:

      # a list of subpages
      pages:
        type: pages
        label: Subpages
        template: default

  # main
  main:
    width: 1/2
    sections:

      # a simple form
      content:
        type: fields
        fields:
          headline:
            label: Headline
            type: text
          text:
            label: Text
            type: textarea

  # sidebar right
  right:
    width: 1/4
    sections:
      # a list of files
      files:
        type: files
        label: Files

Single-column layouts

If you don't need multiple columns, you can keep your blueprint a lot shorter by using the sections option instead of defining columns. This will automatically create a single-column layout for you, where all sections are listed below each other.

title: My blueprint

sections:
  drafts:
    type: pages
    label: Drafts
    status: draft
  published:
    type: pages
    label: Published pages
    status: listed

Adapt all to your needs

Kirby gives you the flexibility to set up the Panel, so that it adapts to the needs of every single page/template. Use the layout possibilities to create the structure that works best for you:

title: My blueprint

columns:
  gallery:
    width: 1/1
    sections:
      gallery:
        type: files
        layout: card
        ...

  review:
    width: 1/2
    sections:
      drafts:
        type: pages
        status: draft
        ...
      review:
        type: pages
        status: unlisted
        ...

  published:
    width: 1/2
    sections:
      published:
        type: pages
        status: listed
        ...

If this isn't yet enough ways and space for you to structure your sections and fields, move on with…

Tabs

When your blueprints get more complex, splitting up your view into multiple tabs helps to keep them organized. Tabs are basically wrappers around regular blueprint layouts. Check out how to create layouts before you get started with tabs.

A tab definition has three options:

  • label
  • columns
  • icon

The icon is optional. Please check out the list of available icons. You can also use an emoji by pasting it directly into the blueprint.

title: My blueprint

tabs:
  content:
    label: Content
    icon: text
    columns:
      # layout
  seo:
    label: SEO
    icon: search
    columns:
      # layout

Full example

title: My blueprint

tabs:

  # content tab
  content:
    label: Content
    icon: text
    columns:

      # main
      main:
        width: 2/3
        sections:

          # a simple form
          content:
            type: fields
            fields:
              headline:
                label: Headline
                type: text
              text:
                label: Text
                type: textarea

      # sidebar
      sidebar:
        width: 1/3
        sections:

          # a list of subpages
          pages:
            type: pages
            label: Subpages

          # a list of files
          files:
            type: files
            label: Files

  # seo tab
  seo:
    label: SEO
    icon: search
    fields:
      seoTitle:
        label: SEO Title
        type: text
      seoDescription:
        label: SEO Description
        type: text