Best way to use shortcodes (0.55+)?

I’m tweaking my shortcodes for 0.55.6, but wonder, should I use {{% shortcode %}} or {{< shortcode >}}?

The release notes say:

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. :slight_smile:

I understand that as follows:

  • {{% %}} is no longer supported.
  • {{< >}} is standard syntax for shortcodes.
  • We have to use {{ .Inner | markdownify }} in our shortcodes instead of {{% %}}

(from Hugo 0.55)

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 }}

1 Like

Thanks for the input! :slight_smile:

Is it safe to say that the new shortcode approach is:

Use {{< >}} by default, unless you need to include shortcodes headings in the TOC.

(Which is a pretty limited use case, but the only one I could think of unfortunately.)

1 Like

Great summary! This topic will help Hugo users. :slight_smile:

Hi @Jura!

That’s what I would have suggested—see here.

bep’s answer below my post is interesting.

1 Like

My 5 cents:

If you don’t know if your .Inner will contain Markdown then use {{%
If you know that your .Inner will 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 :wink:

Thanks for that link.

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: embeds (suggested by bep), youtube embeds, <div> elements that contain short content (like a call out).

Thanks everyone for their input! :+1:


This is beneficial summary. Thanks.

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+.

1 Like