HUGO

Misunderstanding of shortcode syntax in 0.55

support
#7

If using the {{%-syntax it will work as expected as long as you don’t have surrounding html-elements in your shortcode (black friday will not parse markdown inside of html-elements). But because it is usual to have html in the shortcode you have to work around it, see Shortcode - markdown vs html vs table of content for a possible solution.

Also: 0.55 - What am I doing wrong?

You could also use the {{<-syntax and then do {{ .Inner | markdownify }} in your shortcode, as described by @Grob above.

#8

Oh, I see. I did not realize that the surrounding HTML content is the problem.

But that is counter intuitive to the documentation. The documentation lists the {{< syntax clearly under “Shortcodes without markdown” - though i realize now it probably means “Shortcodes without markdown surrounding the inner content” (is that correct?).

#9

I think the documentation needs improvement, but in this case it is correct.

With {{< the inner content will be unparsed and left as is, but you can work around this in your shortcode by adding markdownify.

  • If using {{ .Inner }} in the shortcode the inner content will be left unparsed.
  • If using {{ .Inner | markdownify }} the inner content will parsed and markdown becomes html.
#10

Right. But: what if I want rendered markdown in the inner content of my shortcode and in the content surrounding the inner content of the shortcode? Plus the inner contnet is wrapped by html.

e.g.:

markdownify.html:

## Heading

<div clas="markdownify">
{{ .Inner }}
</div>

{{% markdownify %}}
Paragraph with a [link](https://example.com).
{{% /markdownify %}}

In this case the markdown of the inner content is not rendered to html. Or can I use | markdownify here too?

#11

In this case simply use

## Heading

<div clas="markdownify">
{{ .Inner | markdownify }}
</div>
#12

If you have markdown headings in the .Inner and you want them to show up in a table of contents you can try something like this:

## Heading

 {{ printf "<div clas=\"markdownify\">" | htmlUnescape | safeHTML }}
    {{ .Inner }}
 {{ printf "</div>" | htmlUnescape | safeHTML }}

Thank you @zwbetz for this work around.
See: Shortcode - markdown vs html vs table of content

#13

@Grob but with {{% ? (Sorry, can’t try right now)

#14

Yes, my last suggestion was for the {{%-syntax.

#15

I’m sorry for the confusion. Even if the documentation may not be clear about this, I’m convinced that current behaviour is the correct compromise. The big problem with the pre 0.55 was that it was not possible to have shortcodes that worked with ToC/footnotes – and this will be even more evident pretty soon.

#16

Yes, it was a ‘breaking’ change that caused some confusion, but the advantages are enormous. I am looking forward seeing what happens next.

Just curious to hear: Why was it not possible to generally allow markdown in the shortcodes html files and use {{% and {{< synonymously? And if you like markdown in the content, just use | markdownify. Would it just have been too much of a break?

#17

There is a history here. Once we had only {{% and it behave like it does today (more or less). But there where all kinds of issues reported with how the different markdown processors handled inline HTML etc. in Markdwon. So, beyond the very simple examples, if you want to preserve HTML as … HTML without any encoding/formatting issues, you want to use the {{<.

#18

I see. Thank you very much for your explanation, @bep.

#19

If this is too much off topic feel free to move my questions to a new topic.

What then is good and future proof shortcode style—particularly for shortcodes you may intend to publish in a theme:

  • Always use {{%—unless you really do not want any markdown rendered to HTML? (As an example the cupper theme uses ‌{{% codePen VpVNKW %}}.)
  • Always use {{< />}}—if required with markdownify—and only use {{% if there is markdown in the shortcode html file itself?
1 Like
Best way to use shortcodes (0.55+)?
#20

It’s hard to make a general rule, but the above isn’t one I would live by. The thing is that for this:

{{% myshortcode %}}

## A Markdown header

{{< someothershortcode >}}

{{% /myshortcode %}}

It is the total output that is sent as part of the surrounding document to the Markdown processor, not just the “shortcode itself”.

In the above it is obvious that you want to use “{{%”, for the codePen I would guess (I have not looked at it) that “{{<” would be a more sensible choice.

1 Like
#21

Ok. These are good arguments. Thanks again for your help and efforts!

#22

I can speak to this. So the {{% was not really an intentional decision. When I ported that theme, I tried to keep things as same as possible. When the last Hugo shortcode features were released, that particular theme shortcode still “just worked”. So I left it as is. Plus it wouldn’t break things for folks already using the theme.

Now, I did have to update a few of the theme shortcodes. If you’re interested see https://github.com/zwbetz-gh/cupper-hugo-theme/commit/5da8f5afe992659fc9f6c63e2ceeced65569d338

#23

Thank you, Zachary! Your comment helps me very much deciding how to use use/differenciate between the two possibilities.

BTW: I love your clean and simple themes and your clear template and shortcode style. I visit your projects regularly!

#24

Happy to help! And as Bep mentioned, if I was writing that shortcode from scratch, I’d use {{<

Appreciate it :slight_smile:

#25

@bep there is still another breaking change though. Consider my example from before:

myshortcode.html:

<div class="notice">
{{ .Inner }}
</div>

{{% myshortcode %}}
Lorem ipsum [dolor](https://example.org) sit amet.
{{% /myshortcode %}}

Now, as we know, this would not render the markdown of the inner content, without specifying | markdonify.

However, even with | markdownify, the output will not be as expected.

Output before 0.55:

<div class="notice">
<p>Lorem ipsum <a href="https://example.org">dolor</a> sit amet.</p>
</div>

Output in 0.55:

<div class="notice">
Lorem ipsum <a href="https://example.org">dolor</a> sit amet.
</div>

It does not render the paragraph.

Another test:

{{% myshortcode %}}
Lorem ipsum [dolor](https://example.org) sit amet.

Consectetuer adipiscing elitr.
{{% /myshortcode %}}

This in turn will render as

<div class="notice">
<p>Lorem ipsum <a href="https://example.org">dolor</a> sit amet.</p>
<p>Consectetuer adipiscing elitr.</p>
</div>

in 0.55 (with {{ .Inner | markdownify }}).

Sure we could use the {{ $_hugo_config :={ “version”: 1 }}} setting. But obviously I would rather continue with the new approach.

#27

One could say that it’s another symptom of the same breaking change. Let us discuss it here:

1 Like