Hey. Great work on Kirby! I’ve been using it for a couple of projects and was always very satisfied.
However, I am finding that there are increasingly discrepancies in the official docs/guides and the way Kirby is used in the starterkit and also the examples in the cookbook.
E.g. I see numerous options used here which I cannot find documented anywhere:
parent, info, template, empty
This makes it quite hard for me to grasp the new concepts when the usage here contradicts what I can read in the documentation.
Also using a section subfolder for blueprints is not mentioned anywhere (though I get that this is a deliberate choice to outsource reused definitions) but I imagine that things like these might confuse people that are new to Kirby.
Likely, I just overlooked the right place to find the right docs here. So can anyone help me out in this regard?
you just wrote down what I think since my start with Kirby 3 as my first Kirby version:
I totally agree: I still have a hard time to get into the Kirby 3 world because I have to check the forum, the docs, the cookbook and the starterkit to understand how many common things are realized in Kirby. Sometimes, I even have to check the Github repository for ideas or for issues. On the meta level, like structuring a site or how the developer workflow works out (like what shall I do if I have to add/delete fields in the future because something is missing/the requirements changed), it is even harder to find proper, structured information. I start to understand a lot but it’s really though. That’s why I’m glad @bastianallgeier started to create easy to understand, guiding tutorials on YouTube (Tutorial videos 📺 - Kirby).
I think that the Kirby team knows what is missing and they got a lot of useful feedback and we have @texnixe who is really engaged in the docs. So most likely, this will improve and did already short term if you check the last weeks and months. During that time, where some things lack in the docs, you have to try around, ask the lovely community and try to find workarounds. I mean, no CMS is perfect and so far, Kirby is already a real benefit to many other CMS or blog softwares I had in the past.
You are referring to a section’s properties, and they are described in the reference here:
I understand this blueprint stuff is sometimes hard to get when you start out new. Maybe we can start with adding more comments directly in the Starterkit code as this is likely the first place you stumble upon these things. Or write a cookbook article about the Starterkit.
But as already suggested by @warg above, @bastianallgeier tutorials are also a good starting point.
We try to continuously improve the documentation, when I find that many people run into the same sort of problem, I try to find ways to make things easier to understand. Unfortunately, it often sounds easier than it is. Thanks for your feedback.
I just checked the results of the Kirby site search with the terms “page parent” and “page section” and you are right: The correct spot of the documentation is listed. Maybe it makes sense to split the search results in general:
Kirby 3 reference
Cookbook and Guide
Newsletter and information from the rest of the site
This way, the results are more structured and the more important stuff is on top. I think, there should be also some filtering possible, similar to the forum categories: Do you ask about a page, a blueprint or a setting? Also a preview of the search result would be nice when you hover over a single search result. If you agree, I post this as suggestions in the Github repo @texnixe.
I don’t quite agree with you. The search in the reference already limits results to the reference, only if you click on “View all results” you get the site wide result. But please feel free to create an issue nevertheless.
I think this is because I added the Kirby 3 site search (https://getkirby.com/search?q=panel%20parent) as a search engine in my FireFox. I’m searching with “k < term >” and it calls https://getkirby.com/search?q=< term > so I always see all results because often I don’t find the relevant part when I use the tinier search in the reference site itself (sometimes I look for the wrong term or I just know the major term and not how the sub-component is called). So most likely we do searching in 2 different ways.
There is always room for improvement. I, for example, always want to search for route while the chapter is called routing, so it never turns up in the result unless a type slowly enough. I always wanted to add more keywords to the docs to allow for alternative search words…
Another idea would be to add the top 3 or top 5 terms other people searched for when they search your term. This way, you could return results more context-wise and help users if they don’t know the whole/correct term like when what you look for consists of two or more words.
Thank you very much for pointing out where to find this info! Also, I really like your annotated starterkit PR and I think it would greatly improve the start for new user. Very good to see my issue being picked up and considered this fast.