How do you handle custom tags?


While composing content to and just thinking about “how did i form the syntax of my custom markdown code” i have been wondering how you guys are managing to keep track of it?

obviously the idea is quite simple to have a tag which makes sense while typing, but i find myself always checking back my tags folder to check for my options as well as initiation word e.g.

did i use (relate: bla) or (relation: bla) …

anyhow. this comes to the conclusion that it would also be a nice idea to have a somewhat auto-complete function in the panel which checks for built-in and custom tags so when starting to open up the brackets, it could then show syntax similar to what IDE’s are doing.

this would also make customers who are not too familiar much easier to kirby. i think.

so anything else you guys are doing to keep track of it all?


This would indeed be super helpful, especially for clients.

I made a little proof-of-concept for this some time ago. Without custom kirbytags though:

It’s still very barebones, but it’s a start:


i’m not gonna lie… that’s exactly how i imagine it would be.

An addition would still be giving some information about possible parameters

such as:
image => alt, height, etc
link => popup: yes etc
file => text: bla

just theoretically, is it possible to scan though the custom tag folder and read the tag? i mean they are supposed to have the filename e.g. customtag.php => (customtag: bla) which could then be used within your proof of concept? and the next step making it possible to read the list of parameters specified in custom tags.

+1 really love that


That would be great. I also wanted to display the image names, page names etc. when using one of these built-in kirbytags.

It’s actually possible to get all built-in and custom kirbytags from the kirbytext::$tags variable. I just pushed the necessary commit for that:


If you have any idea how to automate the parameter suggestions please let me know. I’m also still not sure if the autocomplete script gets in the way of regular text editing sometimes.


i guess the easiest way integrate each custom tag’s parameters is to add an array to each custom tag which is then read by your plugin.

so whenever i would create a new tag i could specify the required and optional fields (maybe with sort of short description for the user) which will be read and outputted by autocomplete. i have just installed that plugin to give it a shot though so i didn’t take a look on what’s under the hood.

i guess either specify directly in each tag (if possible)? or doing it via c::set(). is there a way to get access to the attr array from custom tags?

lastly, i have seen that there’s some kind of default list of kirbytags. can i adjust them to my needs? e.g. the twitter and tel one is not needed, but my custom tag only comes on when i start typing…


That should be doable via an ignore list in the config that is read by the plugin.


I experimented some more with this autocomplete idea.

Thanks to @texnixe! The ignore list in the config.php is a great idea and I implemented a textarea.excludedKirbyTags and textarea.includedKirbyTags option. See the updated README for an example.

Furthermore, I can actually extract the attributes from the kirbytags. You can see the list of attributes in the console after selecting one of the kirbytags in the autocomplete dropdown.

I don’t think it would make much sense to have another autocomplete dropdown open with the (sometimes many) attributes. Imagine you’re typing (imag, hitting enter and immediately getting a list of 13 attributes you can choose from. Most of the time you only want to define a single value, maybe with one additional attribute. Having the autocomplete dropdown pop up all the time would be super annoying. That’s why I only print them to the console right now.

Not sure if it’s even possible to develop an unobtrusive, helpful autocomplete for these attributes. Any ideas?


Maybe a tooltip rather than an autocomplete feature for the attributes?


i also ment to have some sort of tooltip instead of another “popup”


similar to this … providing informations a non-experienced user might not think of… e.g. “popup: yes”… or let’s say this information could be composed within the custom tag kinda a standart which can be used with your advanced textfield


So you mean some sort of description while selecting the Kirbytag you want to expand? I’m not sure if this helps clients as they will have to remember this list of attributes, or the ones that are relevant to them, once the Kirbytag is expanded.
Or should this tooltip be visible all the time you are inside the parentheses?

Maybe it would make more sense to automatically (or easily) generate buttons in the textarea for a Kirbytag? I did this for a client who needed three different colors for his text.


The problem with autocompletion in general is that it might interfere with text input (at least if you tend to use a lot of parentheses). A button that adds the tag together with the relevant attributes might be more useful in such cases. Such a button could also include relevant attributes (maybe make that configurable).

As regards the attributes, my idea was to have tooltips if you hover over a tag in the text, not to add a description within the autocompletion. Writing text is different from writing code, in my opinion.


Depending on contexts, relevant attributes might differ a lot and anticipating them might be quite tricky.

Couldn’t such a button add the tags together with every possible attribute, and remove the empty ones on save to keep only those relevants once you’re done ?


Some tags, like the image tag, have a lot of possible attributes, most of which are pretty irrelevant for the standard editor. Adding all these automatically might be pretty confusing, even if you don’t save empty attributes.

There’s also another problem. With an attribute like class, how is the user supposed to know what values are “allowed”? I think I’ve seen a solution with a help button that shows some documentation somewhere.