Create annotated Starterkit

site/blueprints/pages/about.yml

@@ -1,14 +1,25 @@
+# Each page blueprint must have a title, the title may be different from the file name
 title: About us
+
+# Each page can have an icon that is shown in page listings when no preview image is available.
 icon: ☎️
 
+# Limit the possible page statuses to `draft` and `listed`.
+# More about page statuses: https://getkirby.com/docs/reference/panel/blueprints/page#statuses
 status:
   draft: true
   listed: true
 
+# Page options allow you to control how users can interact with the page.
+# Here we prevent changing the page slug and page deletion
+# More about page options: https://getkirby.com/docs/reference/panel/blueprints/page#options
 options:
-  url: false
+  changeSlug: false
   delete: false
 
+# Define the form layout with two columns, each column has a set of fields
+# Columns are optional but help structure the form layout
+# More about columns: https://getkirby.com/docs/guide/blueprints/layout#defining-columns
 columns:
   - width: 1/2
     fields:
@@ -18,6 +29,8 @@ columns:
         size: huge
 
   - width: 1/2
+    # Kirby has many different field types, from simple text fields to the more complex structure field that contains subfields
+    # All available field types: https://getkirby.com/docs/reference/panel/fields
     fields:
       address:
         label: Address

site/blueprints/pages/album.yml

@@ -1,13 +1,25 @@
+# Each page blueprint must have a title, the title may be different from the file name
 title: Album
+
+# Each page can have an icon that is shown in page listings when no preview image is available.
 icon: 🖼
 
+# Page status can be limited, here to `draft` and `listed`.
+# More about page status: https://getkirby.com/docs/reference/panel/blueprints/page#statuses
 status:
   draft: true
   listed: true
 
+# Define the form layout with two columns
+# Columns are optional but help structure the form layout
+# The first column defines an files section, the second a set of fields
+# More about different types of sections: https://getkirby.com/docs/reference/panel/sections
+# More about columns: https://getkirby.com/docs/guide/blueprints/layout#defining-columns
+
 columns:
   - width: 2/3
     sections:
+      ## The `images` files section shows all images of the current page that use the `image` template
       images:
         type: files
         layout: cards
@@ -20,6 +32,8 @@ columns:
         size: small
 
   - width: 1/3
+    # The second column contains a set of fields
+    # List of all available field types: https://getkirby.com/docs/reference/panel/fields
     fields:
       cover:
         type: files

site/blueprints/pages/default.yml

@@ -1,7 +1,17 @@
+# Each page blueprint must have a title, the title may be different from the file name
 title: Simple Page
+
+# Each page can have an icon that is shown in page listings when no preview image is available.
 icon: 📝
+
+# Page presets are a quick way to set up a standard page layout
+# More about page presets:
+# - https://getkirby.com/docs/guide/blueprints/presets and
+# - https://getkirby.com/docs/reference/panel/presets/page
 preset: page
 
+# Custom descriptions of page statuses depending on use case
+# More about page statuses: https://getkirby.com/docs/reference/panel/blueprints/page#statuses
 status:
   draft: true
   unlisted:
@@ -11,9 +21,12 @@ status:
     label: Menu Page
     text: The page is listed in the main menu
 
+# Limit subpage display to certain templates in a page preset
 pages:
   template: default
 
+# A page preset can have a freely defined set of fields
+# List of all available field types: https://getkirby.com/docs/reference/panel/fields
 fields:
   text:
     type: textarea

site/blueprints/pages/error.yml

@@ -1,4 +1,9 @@
+# Each page blueprint must have a title, the title may be different from the file name
 title: Error
 
+# Page options allow you to control how users can interact with the page.
+# Here we prevent reading of the page, so it is not shown to anyone in the Panel.
+# If you want to allow users to modify the error page content in the Panel, remove this option.
+# More about page options: https://getkirby.com/docs/reference/panel/blueprints/page#options
 options:
   read: false

site/blueprints/pages/home.yml

@@ -1,15 +1,24 @@
+# Each page blueprint must have a title, the title may be different from the file name
 title: Home
+
+# Each page can have an icon that is shown in page listings when no preview image is available.
 icon: 🏠
 
+# Page options allow you to control how users can interact with the page.
+# Here we prevent changing the page slug (the home page cannot be deleted)
+# More about page options: https://getkirby.com/docs/reference/panel/blueprints/page#options
 options:
   status: false
 
+# Here we define an info section and a pages section (`photography`)
 sections:
   info:
     headline: Info
     type: info
     text: All content for the homepage is being pulled from the photography page.
 
+# The photography section extends a pages section defined in the `/site/blueprints/section/album.yml` blueprint
+# More about reusing and extending sections: https://getkirby.com/docs/guide/blueprints/extending-blueprints#reusing-and-extending-sectionss
   photography:
     headline: Photography
     extends: sections/albums

site/blueprints/pages/note.yml

@@ -1,7 +1,15 @@
+# Each page blueprint must have a title, the title may be different from the file name
 title: Note
+
+# Sorting number scheme that is applied when page status is changed to `listed`
+# More about page sorting: https://getkirby.com/docs/reference/panel/blueprints/page#sorting
 num: date
+
+# Each page can have an icon that is shown in page listings when no preview image is available.
 icon: 📖
 
+# Custom descriptions for each page status depending on use case
+# More about page status: https://getkirby.com/docs/reference/panel/blueprints/page#statuses
 status:
   draft:
     label: Draft
@@ -13,14 +21,20 @@ status:
     label: Published
     text: The note is online and listed in the blog
 
+# Define the form layout with two columns
+# Columns are optional but help structure the form layout
+# More about columns: https://getkirby.com/docs/guide/blueprints/layout#defining-columns
 columns:
   - width: 2/3
+    # This columns only has a single field
     fields:
       text:
         type: textarea
         size: large
 
   - width: 1/3
+    # This second column holds a fields section with multiple fields
+    # More about fields sections: https://getkirby.com/docs/reference/panel/sections/fields
     sections:
       meta:
         type: fields
@@ -31,6 +45,8 @@ columns:
             default: now
           author:
             type: users
+          # Fields types can be added using the shortcut `fieldname: true`
+          # (however, you can only use a fieldname once per page and this only makes sense for simple fields without configuration)
           tags: true
           gallery:
             type: pages
@@ -40,4 +56,5 @@ columns:
             empty: "No gallery selected"
             image:
               cover: true
+            # Use the `help` property of fields and section to provide editors with helpful information
             help: Place the {{ gallery }} tag anywhere in your text to add the selected gallery

site/blueprints/pages/notes.yml

@@ -1,8 +1,16 @@
+# Each page blueprint must have a title, the title may be different from the file name
 title: Notes
+
+# Each page can have an icon that is shown in page listings when no preview image is available.
 icon: 📖
 
+# Define the form layout with two columns
+# More about columns: https://getkirby.com/docs/guide/blueprints/layout#defining-columns
+
 columns:
   - width: 1/2
+    # In the first column, we reuse the `notes` section
+    # (defined in `/site/blueprints/sections/notes.yml` twice with different page status and headline
     sections:
       drafts:
         extends: sections/notes
@@ -15,8 +23,11 @@ columns:
         status: unlisted
 
   - width: 1/2
+    # In the second column, we reuse the same section, this time for listed pages and with a different headline
     sections:
       listed:
         extends: sections/notes
         headline: Published
         status: listed
+
+# More about pages sections: https://getkirby.com/docs/reference/panel/sections/pages

site/blueprints/pages/photography.yml

@@ -1,6 +1,11 @@
+# Each page blueprint must have a title, the title may be different from the file name
 title: Photos
+
+# Each page can have an icon that is shown in page listings when no preview image is available.
 icon: 🖼
 
+# Here we extend two sections which are defined in `/site/blueprints/sections/albums.yml`
+# They differ in their page status and the headline.
 sections:
   drafts:
     extends: sections/albums

site/blueprints/pages/sandbox.yml

@@ -1,10 +1,22 @@
+# Each page blueprint must have a title, the title may be different from the file name
 title: Sandbox
+
+# Page presets are a quick way to set up a standard page layout
+# More about page presets:
+# - https://getkirby.com/docs/guide/blueprints/presets and
+# - https://getkirby.com/docs/reference/panel/presets/page
 preset: page
+
+# Sorting number scheme that is applied when page status is changed to `listed`
+# More about page sorting: https://getkirby.com/docs/reference/panel/blueprints/page#sorting
 num: zero
 
+# Limit subpage display to certain templates in a page preset
 pages:
   template: sandbox
 
+# A page preset can have a freely defined set of fields
+# List of all available field types: https://getkirby.com/docs/reference/panel/fields
 fields:
   headline:
     type: text