Error using Subpage builder

Kirby version -

I want a subfolder auto-created every time I create a “particular page”. This is because the blueprint for the “particular page” has a section - type: pages - that has a - parent: page.find("subfolder") - which gives an error if there is no “subfolder” folder under “particular page”. Later I will be adding pages in folders under that “subfolder”.

I followed the instructions at: Subpage builder. It kind of does what I need because it creates the subfolder, but it also creates a new page in there, which I don’t need, but I can not figure out how to stop that.

When I click on “Create draft” to make the “particular page” I get the error: $page->sort() is deprecated, use $page->changeSort() instead. $page->sort() will be removed in Kirby 3.6.0. and I have to click “Cancel” to close the dialog box.

But the “particular page” is created as a draft, and its subfolder is created (It shows up when reloading the Panel).

How might I resolve this error?

  - title: Gallery
    uid: gallery
    template: gallery
    num: 1
  - title: Info
    uid: info
    num: 2
    template: info

Did you change that so that only one page is created?

Yes, I changed it to:

  - title: Subfolder
    uid: subfolder
    template: subfolder
    num: 1

And where is the unnecessary page created, as a subpage of the newly created subfolder page? If so, do you have a subpage builder defined in the subfolder blueprint?

Yes, there is an un-needed subfolder.txt file inside the subfolder


particularPage (particularpage.txt)
    subfolder( subfolder.txt)

The blueprints are: particularPage.yml and subfolder.yml

Everything seems to work, apart from the error message - which I have to resolve by clicking Cancel and then refreshing the Panel page for listing all the particularPage-s

I think I don’t understand. So there is only that subfolder with a text file, not an additional subfolder? The text file is automatically created when you create a new page. Or in other words, a page consists of a folder and a text file for the content.

Using the Subpage builder plugin, when I create the particularpage using the particularpage.yml blueprint, a folder is created named particularpage and it contains its page file particularpage.txt - and the Subpage builder plugin auto makes a folder below that named subfolder which contains its page file subfolder.txt -

This is all fine.

The problem is the Error Message that comes when making the particularpage - that has to be cancelled. Then the panel page that lists the particularpage file (as a Draft) has to be refreshed for a link to edit particularpage to show up. Only then I can proceed to enter any data for the particular page.

Only later will I be adding pages under the “subfolder” using a separate subfolder.yml

This refers to this line:


which has to be changed to


I had already tried that before I asked for help. This gives the error The page has errors and cannot be published

But it also properly creates the particularpage folder and it’s page file particularpage.txt as a Draft, and the subfolder etc. - but I have to do a refresh etc. to be able to enter particularpage and add data to it.

Could you please post your blueprint? Looks like your page definition has required fields that are not filled in at the time you are trying to publish the page.

I used a fresh installation of Kirby, and retested using minimal blueprint files. I’m still getting those errors.


Title: mainpage
    headline: Area for adding new Particular pages
    type: info
    text: <b>Writing Particular pages</b> (below) is where pages are <b>added, edited,</b> etc. to the **Mainpage** page.
    headline: Writing Particular pages
    type: pages
    status: all
    info: <br>Date published {{ page.datePublished }}
    layout: list
    parent:  site.find("mainpage/sub-mainpage")
    limit: 50
    flip: true
    templates: sub-mainpage


Title: sub-mainpage

  changeTitle: false

    - title: Subpage
      uid: subpage
      template: subpage
      num: 1

  - width: 3/4
        type: fields
        template: find("template/mainpage")
            label: Comment
            type: textarea
            label: Tags
            type: tags
            type: hidden
            default: "{{ kirby.user }}"
        type: info
        text: Now go to the top left, and click on **Draft**, and publish the new piece.
  - width: 1/4
        text: Use this <b>Subpage</b> section below to Add a Subpage Entry.<hr>When <b>Add</b>ing - the <b>new Title</b> should be the Subpage (site name).<hr>Remember to "Publish" the draft after you've saved the entry.
        headline: Subpage Creator
        help: Use this section to add a Subpage Entry,<br>Remember to "Publish" the draft when you've finished.
        type: pages
        limit: 10
        flip: true
        templates: subpage ## This uses the subpage.yml blueprint for entering data
        parent: page.find("subpage") ## This saves the entry under the subpage/ subfolder ?


Title: subpage
    label: Title of Subpage Piece
    type: text
    required: true
    placeholder: "{{ page.parent.parent.titleName }}"
    help: {{ page.parent.parent.titleName }} <- Copy this and paste above if correct. <br>This **Title** is a required field (cannot be blank) - 
    label: Link of Republished piece
    type: url
    help: **Link** is a required field (cannot be blank)
    label: Comment
    type: textarea
    help: To ensure this entry is Published, Scroll to the top and change <b>Draft</b> to Public

What I don’t understand:

In your mainpage.yml, you have a section that requires the mainpage/sub-mainpage to exist. But your mainpage.yml doesn’t have a subpage-builder that would create this sub-mainpage.

Only your sub-mainpage.yml has such a subpage builder (which is additionally wrongly added under options instead of a separate unindented section).

I corrected the placement of the subpage builder. Thank you for noticing that!

This project involves moving an existing (notepad written) static html site into kirby, so that others can make changes themselves. The kirby test site being worked on now was made by first creating the folder structure, so no thought has been put into making the panel create the main folders and subfolders.

Is this fixed now or still something not working as expected?

No, it is not fixed yet. The same problem continues.
I changed $subPage->sort to $subPage->changeSort in the Subpage builder plugin.
Then I did some tests by creating a subfolder at the top level under the content folder - and these create correctly without an error.

Is it possible that the Subpage builder plugin is having issues when auto-creating a nested subpage further down the tree? In my case, below the 3rd level?

Maybe you can provide what you currently have for testing, either all the blueprints or a download link with the project (send a PM if you don’t want to post this publicly).

I put this in:

title: Default Page
  - title: sub-mainpage
    uid: sub-mainpage
    template: mainpage
    num: 1
preset: page
    label: Text
    type: textarea
    size: large

and I used the same mainpage.yml blueprint in the previous post I made - and when I Add a new page from Mainpage (say I create the page mainpage2 - it correctly creates that, with a subfolder called sub-mainpage - with no errors. So I have the folders: content\mainpage2 (default.txt) \sub-mainpage (mainpage.txt)
So I know the Subpage builder plugin is working correctly at the top folder level, creating a subfolder page.

Again, if you want to create another subfolder in the sub-mainpage that uses the mainpage.yml then your mainpage.yml would need its own subpage_builder definition to work recursively.

Well, I believe I found the issues.
The first was a silly copy/paste mistake.
In the Subpage builder, when correcting the line:


I used:


instead of:


Note: It might be helpful if kirby docs on the Subpage builder’s code. is updated.

Once I finally sorted that out, the next difficulty was a little more perplexing.
I’m testing all this on a Windows 10 machine running MAMP.

For some reason, some folders are sometimes being locked by Windows, so they can’t be changed by kirby. This caused error messages that sometimes led to no changes taking place, partial changes, or changes where the Panel would need to be refreshed. One “breaking” partial change is when a published piece is deleted, the renumbering of published pieces stops half way if one of the other published folders is locked - resulting in broken numbering.

All well now, hopefully.

Some good lessons learnt by this beginner while figuring all this out.

One is that for the Subpage builder plugin to not “Publish” the new subfolder, but to just have it “Unlisted”, I could choose:

num: null

The other lessons learnt was getting a better idea of how - blueprints / folder-names / file names - work in the Panel. This is what I understood:

In a BLUEPRINT, the template option refers to a blueprint! This concept concept causes confusion, because displaying a page on the website also uses templates, so it is disconcerting when using the template word to refer to a blueprint.

When a new page is created:

  • the new page is created in a folder with the name of the slug of the Title name (or anything the slug is manually modified to)
  • the page-data-text-file within that new folder will have the name of the (blueprint)template specified for its creation

If the new Page is added without the blueprint specifying a (blueprint)template:

  • A Select box of possible templates is given when Adding the Title.
    • If a selection is not made, it auto chooses the first blueprint-template (top of the list)
      • This is quite easy to overlook! Intuitively, one expects 1st - a (blueprint)template matching the slug to be highlighted, or else 2nd -the default template to be the highlighted one, but it isn’t either. Just the alphabetically first in the list.

When a blueprint wants to show a page in a list, the template that created the page must be chosen!

  • Page-data text-files named a.txt need the blueprint to specify a (blueprint)template of a(.yml) for that page to show up!
  • Same way, if a page-data-text-file is named default.txt , the (blueprint)template to view it has to be set to default(.yml)

I would appreciate that, if any of what I said is incorrect, it could be clarified.


It has already been updated a few days ago.