Best way to use shortcodes (0.55+)?

support
8

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

Thanks everyone for their input! :+1:

2 Likes