Create annotated Starterkit

site/blueprints/files/image.yml

@@ -1,5 +1,11 @@
+# Each file blueprint must have a title, the title may be different from the file name
 title: Image
 
+# Like page blueprints, file blueprints can define a layout with tabs, columns, sections and fields
+# File blueprints define what sort of information should get stored in a file's meta data file
+# In addition to the fields defined in this example blueprint, you can also set what type of file is acceptable
+# when this blueprint is used, which allows you to control what users can upload.
+# More about file blueprints: https://getkirby.com/docs/reference/panel/blueprints/file
 columns:
   - width: 1/2
     sections:

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

site/blueprints/sections/albums.yml

@@ -1,3 +1,7 @@
+# This section blueprint defines a pages section that can be reused across multiple blueprints
+# or multiple times within the same blueprint, see `/site/blueprints/pages/photography.yml`  and `/site/blueprints/site.yml`
+# Sections can have different layouts and display additional information or a preview image
+# More about pages sections: https://getkirby.com/docs/reference/panel/sections/pages
 type: pages
 headline: Photography
 parent: kirby.page("photography")

site/blueprints/sections/notes.yml

@@ -1,3 +1,7 @@
+# This section blueprint defines a pages section that can be reused across multiple blueprints
+# or multiple times within the same blueprint, see `/site/blueprints/pages/notes.yml` and `/site/blueprints/site.yml`
+# Sections can have different layouts and display additional information or a preview image
+# More about pages sections: https://getkirby.com/docs/reference/panel/sections/pages
 type: pages
 headline: Notes
 parent: kirby.page("notes")

site/blueprints/site.yml

@@ -1,16 +1,34 @@
+# The site blueprint must have a title, the title may be different from the file name
+# The `site.yml` blueprint defines the look of the start page (Dashboard) of the Panel.
 title: Site
 
+# The site blueprint usually provides easy access to all main pages of the site.
+# In this example blueprint, we also show subpages of the `photography` and `notes` pages.
+# More about the site blueprint: https://getkirby.com/docs/reference/panel/blueprints/site
+
+# The layout of this form has two columns:
 columns:
+  # The first column has one section for the subpages of the `photography` page in card layout
+  # It reuses the pages section defined in `/site/blueprints/sections/albums.yml`
   - width: 1/2
     sections:
       albums: sections/albums
+
+  # The second column has two sections, `notes` and `pages`
   - width: 1/2
     sections:
+      # The `notes` section reuses the pages section defined in `/site/blueprints/sections/notes.yml`
       notes: sections/notes
+
+      # The `pages` pages section shows other main pages of the site
+      # Using the `templates` option, we limit which types of pages are shown
+      # Using the `create` option, we limit the type of page that can be created when a new page is created
+      # Note that the `sandbox` page and the `error` page that also exist in the content folder but use different blueprints thus do not show up in the list
+      # Since the error page's blueprint is set to `read: false`, it wouldn't show up here even if you added the error blueprint to the templates list
       pages:
         type: pages
         create: default
-        template:
+        templates:
           - about
           - home
           - default

site/blueprints/users/default.yml

@@ -1,3 +1,9 @@
+# User blueprints are used to create new user roles, define form fields for each user role and set role permissions.
+# By default, Kirby only has the `admin` role, a user role that is allowed to do anything.
+# The title is required, everything else is optional.
+# The default user blueprint does not define a role, but a standard set of fields
+# available for each defined user role with blueprints that only contain a title.
+# More about users, roles and permissions: https://getkirby.com/docs/guide/users/managing-users
 title: User
 
 columns: