But using the {{< >}} delimiter will, in most cases, be a better alternative, possibly in combination with the markdownify template func.
I looked further but cannot find what ‘better alternative’ means. Speed? Reliability? Ease of use? And does it mean that {{% %}} are a poor choice, and should change existing code to {{< >}}?
And ‘most cases’ I neither understand. What are the situations in which we definitely should not use {{< >}}?
To summarise, I just want to know if I should change everything to use {{< >}} or not.
This is not the case. This option is still supported, and its advantage is that it runs the content through the markdown processor. So for example if your shortcode creates a heading, it will show up in the page variable {{ .TableOfContents }}
If you don’t know if your .Innerwill contain Markdown then use {{%
If you know that your .Innerwill not contain Markdown then use {{<
In case of doubt use {{%.
I wouldn’t make it fix on things like “a heading could contain markup”. You don’t know what’s inside of your TOC, so use {{%. If your shortcode just inserts a smiley or an image then it’s a case for {{<. As soon as you have content to prepare that you have not created in your shortcode it’s a case for {{%
I use {{% for all my shortcodes for now until I have time to think about it and then reduce the use from there
I also found this topic where bep says (paraphrasing to keep it short):
use {{% %}} for shortcodes that produces Markdown with headers (TOC) and footnotes. This looks like a small use case, but wasn’t possible in the past and there will be more benefits in the future.
use {{< >}} for content that doesn’t need to be rendered with Blackfriday. And to prevent odd results.
if you use markdownify in your shortcode, there’s no need to have Blackfriday process it. So use {{< >}} then.
If I summarise what I learned in this thread and the linked topics, then it seems we can also distinguish between purpose:
{{% %}} for content shortcodes that, like regular Markdown files, get rendered into HTML.
These shortcodes can have some HTML (like <div>), but their main task is content processing (like our Markdown files already do).
The content cannot be inside HTML elements. When they are, Blackfriday does not process the contents. The workaround is to use markdownify, but that defeats the purpose of using {{% %}}.
Examples: content boxes like notes and tips, markdown tables preceded in a special <div> or followed by a legend hard-coded in the shortcode.
{{< >}} for HTML-heavy shortcodes, that behave more like theme components than content files.
These shortcodes can still use markdownify to turn Markdown into HTML, but that’s just part of what they do.
Examples: codepen.io embeds (suggested by bep), youtube embeds, <div> elements that contain short content (like a call out).
Apart from more complex shortcodes I have two use cases for a simple markdownify shortcode:
use markdown in .html files and
use markdown within html tags (e.g. <div/>)
If I get it correctly | markdownify is absolutely necessary in both cases. Therefore I prefer using {{< >}}, although I used {{% %}} before Hugo 0.55+.