Blueprints vs Templates?

I’ve been poking around, learning how Kirby works for about a week now. At this point, I’m excited to purchase a license now that I’ve decided it’s exactly what I’m looking for.

One thing I’m a little confused about, however, is the difference between blueprints and templates. I thought I understood at first (templates determine how pages are displayed, and blueprints determined how they are created), but after reading through the Docs, I’m not so sure.

The main issue is that the Docs and the Panel seem to reference “templates” when they mean blueprints. For example, adding a new page in the Panel gives you 3 fields (“Add a new page”, “URL-appendix”, and “Template”). The “template” field is populated with blueprints.

Another example is in the Docs ( where they keep referencing blueprints as templates.

So I guess my question is am I missing something obvious here? Blueprints and templates are entirely different things, correct?

Bonus question:
How do restrict the blueprints/templates that can be chosen at the site level. Specifying it inside site.txt doesn’t seem to do anything, and it’s a little weird creating pages at the root/site level showing every template/blueprint possible.

Well, the most obvious distinction between blueprints and templates is:

  • blueprints are only needed if you use the panel, they determine what sort of content a user can add via the panel, they have a yaml-structure and can be regarded as a sort of template for the panel view. Or as is says in the docs:

Blueprints are the counterpart of each of your templates. They create individual forms in the panel which make it easy to insert the required data. Blueprints offer a wide set of options to customize those forms and even provide help to panel users while they enter data.

  • templates determine what sort of content is displayed on a page and how the content in the text files is displayed. They are created by using a mixture of PHP and HTML.

Both template and blueprint have the same name as the corresponding text file.

When you add a new page in the panel, choosing a blueprint is the same as choosing a template, cause the file gets a name that determines the template that is used to parse the contents.

In some cases, however, you may have a blueprint for page but not a template, i.e.if you do a one pager.

You can restrict the templates that can be used for a page/subpage in the blueprint: On the site level, you would do that via a site.php blueprint.

1 Like

I think that clears things up a bit. So when you create a new page, the “template” field is populated with available blueprints. In addition to setting up fields and other options, selecting one of these sets the actual file name for that page, which in turn determines what template is applied (one with the same name, or “default.php” if a match isn’t found) when the page is accessed.

Also, adding a site.php blueprint fixed my last question, so thank you. I was naming it “home.php” which looks to be why it never worked.