Skip to content

Kirby 4.2.0

Page blueprint

Page blueprints are located in /site/blueprints/pages and control the Panel setup and form fields for pages.

Blueprint location

  • /site/blueprints/pages

Default page blueprint

To create the same set of fields for all pages, you can setup a default.yml that is used whenever no custom page blueprint is configured.

  • /site/blueprints/pages/default.yml


The title is required and will appear in the list of selectable templates when a new page is created and multiple templates are available.

title: Article

Translated titles

The title can be translated by passing an array of translations with the matching language code as key:

    en: Article
    de: Artikel


The num option defines which numbering scheme to use when a page is published.

Default sorting is numbering (1 to x) and doesn't need any setup.

Alphabetical sorting by page uid

num: zero

Sorting by a custom sort number field

You may use a field value, for example from a field called customSortNumberField, to customize the sort order:

num: '{{ page.customSortNumberField }}'

The return value of the query has to be an integer which will be used for sorting. Learn more about Kirby's query language.

Chronological sorting by date field

If your page blueprint contains a date field, you can use that date (and, optionally time) to sort your pages chronologically. For example, for a date field named created, you can apply the following:

By date

num: '{{ page.created.toDate("Ymd") }}'

By datetime

num: '{{ page.created.toDate("YmdHi") }}'

If you use a sorting scheme other than default sorting by number, i.e. automatic sorting, manual sorting in the Panel will be disabled.


With the status option, you define the page statuses you want to allow for the page. You can also change their label and description. This option gives you a lot of flexibility how you want to use page status in your website.

The draft status of a page can not be removed or disabled – only its label and description can be changed.

Simple example

    draft: Draft
    listed: Published

Extended example

    label: Draft
    text: The article is still in draft mode. It can only be seen by editors with Panel access.
    label: In Review
    text: The article is online and can be visited with the direct URL. The team must still give the final go to publish it.
    label: Published
    text: The article is online and listed in the blog
Since 4.0.0

Page creation dialog

You can customize the page creation dialog that pops up when you create a new page. You can add fields, change the label of the title field, disable the automatic redirect to the new page and set its status.

title: Product
    label: Product name
    - price
    - brand
  redirect: false
  status: listed

The button label changes depending on the status option set:


Page creation dialog

An example how to customize the page creation dialog for building a bookmark tool.

Since 4.1.0

Automatic title and slug

The page create dialog also allows you to automatically generate title and/or slug instead of allowing the user to edit them manually. To do so, define the title and/or slug suboption as a string template:

  title: "{{ page.location }} – {{'M Y') }}"
  slug: "{{ page.location.slug }}-{{'Y-m-d') }}"
    - location
    - date

Note that the page fields you want to query within the string template need to be in the list of fields within the create option (in this example, location and date), and those fields need to be present in the page blueprint itself.

However, you can also query information not specific to the current page through the kirby or site entry points.

This means, you could, for example, create a custom site method that returns the current Unix timestamp, and use that in your string template:

  title: "{{ site.time }}"
  slug: "{{ site.time }}"

And in a plugin, define the method


Kirby::plugin('getkirby/custom-methods', [
  'siteMethods' => [
    'time' => function() {
      return time();

If title and slug are generated automatically, and no custom fields are defined for the page creation dialog, the dialog will be skipped and the page is created immediately.

Supported field types

Currently, the list of supported field types in the dialog is limited to checkboxes, date, email, info, line, link, list, number, multiselect, radio, range, select, slug, tags, tel, text, toggles, time, url. Custom field types are disabled by default. To enable them, add your field type name to:

Kirby\Panel\PageCreateDialog::$fieldTypes[] = 'yourFieldType'


With options, you can control all the page actions that should or should not be available for this particular page type. The option dropdown for pages will adjust accordingly.

Option Value Description
access true/false page is not accessible and not listed (since v4.0.0)
changeSlug true/false
changeStatus true/false
changeTemplate false or list of allowed template
changeTitle true/false
create true/false
delete true/false
duplicate true/false
list true/false page is accessible but not listed (since v4.0.0)
move true/false since v4.0.0
preview true/false/template string (see below)
read true/false page is not accessible and not listed (will be deprecated in Kirby 5)
sort true/false
update true/false

Each option can be set on a per user role for fine-grained permissions, for example:

    admin: true
    editor: false

Or using a wildcard to change the default for all roles:

    *: false
    editor: true
Since 4.0.0

Controlling accessibility for roles.

# Page is not accessible and not visible for all roles except admins.
    *: false
    admin: true
    *: false
    admin: true

Different option values per role currently don't work for the changeTemplate option (which takes a fixed list of allowed templates) or the preview option. These two options can only be controlled for all roles at once.


The icon can either be one of our own icons or an emoji. Icons appear in page lists when no preview image is available.

icon: page


icon: 📚

Image options

The image options for pages can now be defined directly in their own blueprint. This significantly simplifies the setup of sections as they all inherit the image settings. You can still set image settings in sections the good old way if needed.

  back: blue-200
  query: page.cover.toFile()
  icon: 📝

This will fall back to the icon if the page has no images. If the query option is not set, the first image will be used.

To force the icon if the page has images, set the query option to false:

  back: blue-200
  icon: 📝
  query: false

Support for queries

Panel preview image options now all support our powerful queries:

  back: "{{ page.myCustomBackColor }}"

Custom colors

back and color options for Panel preview images now support shorthands for core CSS color variables as well as HEX codes or other native CSS color properties (e.g. even gradients):

CSS color property shorthands

  back: "purple-400"

Check out the list of our color properties for available options.

Hex codes

  back: "#ff0000"

CSS rules

  back: "linear-gradient(90deg, rgba(2,0,36,1) 0%, rgba(9,9,121,1) 35%, rgba(0,212,255,1) 100%)"


You can change the link of the preview button or disable it entirely with the option setting.

Disabling the preview button

For some pages it makes sense to disable the preview entirely.

  preview: false

The preview option can also take any absolute link or a template string.

Absolute URL


Template string

You can use Kirby's powerful query syntax to create any link dynamically.

  preview: "{{ page.parent.url }}/#{{ page.slug }}"

Change templates

You must define a list of compatible templates with the changeTemplate option to allow editors to switch between page templates.

    - video-post
    - link-post
    - text-post

When an editor switches templates, all fields with the same name and type will be synced. Incompatible fields will be discarded. Be aware of this step when you define the list of compatible templates.

The previous/next item navigation in the Panel is a very effective way for editors to move between content. With navigation option you can improve the usability of the navigation for your users with additional options to customize the links.

title: Simple Page
  status: all
  template: all
title: Simple Page
    - draft
    - unlisted
    - album
    - default
title: Simple Page
  status: listed
  template: default
  sortBy: title asc


You can find examples of different types of page blueprints in the samples section.