# Misunderstanding of shortcode syntax in 0.55

**URL:** <https://discourse.gohugo.io/t/misunderstanding-of-shortcode-syntax-in-0-55/18538>\
**Category:** support\
**Created:** [May 6, 2019, 2:08pm UTC](https://discourse.gohugo.io/t/misunderstanding-of-shortcode-syntax-in-0-55/18538 "2019-05-06T14:08:46Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![liochan](https://avatars.discourse-cdn.com/v4/letter/l/13edae/32.png) [@liochan](https://discourse.gohugo.io/u/liochan)\
**Post date:** [May 6, 2019, 2:08pm UTC](https://discourse.gohugo.io/t/misunderstanding-of-shortcode-syntax-in-0-55/18538/1 "2019-05-06T14:08:46Z")

</div>

I use shortcodes and since 0.55 I am a bit confused about how it works.

$ hugo version  
Hugo Static Site Generator v0.55.3/extended linux/amd64 BuildDate: unknown

My project is using shortcodes in markdown files this way

```
---
title: A page title
draft: false
---
<div>
{{% intro %}}
# A title with <br /> in
{{% /intro %}}
{{% content %}}
{{% description %}}
## Markdown
{{% /info %}}
{{% practical %}}
## Markdown
{{% /practical %}}
{{% /aside %}}
{{% /content %}}
</div>

```

Mainly, my shortcodes have this syntax

```
<div class="wrapper">
  <div class="classname">
    {{ .Inner }}
  </div>
</div>

```

When I type _hugo serve -D_ only shortcode **{{% intro %}}** is rendering original markdown and not rendering content in html as others shortcodes are doing.  
You can see the results in every page here, at the left of the big red flower [https://it-gnosis.eu/](https://it-gnosis.eu/)

When I read the [documentation](https://gohugo.io/content-management/shortcodes/#shortcodes-with-markdown), I am a little bit confused of what exactly means

> outer-most shortcode  
> fully rendered  
> old behavior

This solution is working fine

```
{{ $_hugo_config := `{ "version": 1 }` }}

```

But what I am understanding from the documentation is that the inner content is rendered in html. Always in my own understanding, this is the old behavior. I think I miss the point 😉  
I will be happy to help to improve the documentation.

Last thing, I tried a test to understand by creating a test project

> **[GitHub - ioO/shortcode-test: A demo repository for issue with hugo shortcode](https://github.com/ioO/shortcode-test)**
>
> A demo repository for issue with hugo shortcode. Contribute to ioO/shortcode-test development by creating an account on GitHub.

When I first launch hugo serve, the markdown was rendered in html. I did a modification in the content file by adding `<br />` in the content. The content is rendered with original markdown. I remove the `<br/>` and my content is still rendered with original markdown.  
I also notice that I have the favicon of the previous project which is displayed in the tab.

---

<div class="post-metadata">

**Author:** ![fritzmg](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/fritzmg/32/8717_2.png) [@fritzmg](https://discourse.gohugo.io/u/fritzmg)\
**Post date:** [May 16, 2019, 9:32pm UTC](https://discourse.gohugo.io/t/misunderstanding-of-shortcode-syntax-in-0-55/18538/2 "2019-05-16T21:32:21Z")

</div>

I agree that the documentation is confusing. The documentation begins with stating, that there are two different types of shortcodes: shortcodes with the `%` delimiter and shortcodes with the `<`/`>` delimiters. It then provides two sections:

- Shortcodes with Markdown
- Shortcodes without Markdown

In the **Shortcodes with Markdown** section it mentions the `%` delimiter and that its behaviour has changed. What follows is also something that I do not get, since I do not know the inner workings of Hugo enough. But in any case: the documentation suggests that, if you want to use markdown within your shortcode, you have to use `%`, since it definitely will not work with `<`.

But in Hugo 0.55, markdown does **not** work within shortcodes at all, at least not without the odd `{{ $_hugo_config :=`{ “version”: 1 }`}}` setting.

---

<div class="post-metadata">

**Author:** ![mojoa](https://avatars.discourse-cdn.com/v4/letter/m/8491ac/32.png) [@mojoa](https://discourse.gohugo.io/u/mojoa)\
**Post date:** [May 17, 2019, 1:22am UTC](https://discourse.gohugo.io/t/misunderstanding-of-shortcode-syntax-in-0-55/18538/3 "2019-05-17T01:22:57Z")

</div>

If you think you have an idea for improving the documentation, just [follow these simple instructions](https://gohugo.io/contribute/documentation/).

Improvement is very welcome and depends upon Community involvement!

---

<div class="post-metadata">

**Author:** ![fritzmg](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/fritzmg/32/8717_2.png) [@fritzmg](https://discourse.gohugo.io/u/fritzmg)\
**Post date:** [May 17, 2019, 5:17am UTC](https://discourse.gohugo.io/t/misunderstanding-of-shortcode-syntax-in-0-55/18538/4 "2019-05-17T05:17:03Z")

</div>

First I need to understand what is going on ;). The documentation, as far as I understand it in its current state, states that if you use markdown in your shortcode content, you should use the `{{% foo %}}` syntax. However this does not work out of the box. Why?

---

<div class="post-metadata">

**Author:** ![Grob](https://avatars.discourse-cdn.com/v4/letter/g/f14d63/32.png) [@Grob](https://discourse.gohugo.io/u/Grob)\
**Post date:** [May 17, 2019, 9:19am UTC](https://discourse.gohugo.io/t/misunderstanding-of-shortcode-syntax-in-0-55/18538/5 "2019-05-17T09:19:52Z")

</div>

Let’s say you have a markdownify shortcode.

## Usecase 1

markdownify.html:

```auto
## Heading

{{ .Inner | markdownify }}

```

The `| markdownify` part is important now!

```auto
{{< markdownify >}}
Paragraph.
{{< /markdownify >}}

```

Usecase 1 renders your paragraph to HTML—but not the heading in your shortcode file itself.

## Usecase 2

markdownify.html:

```auto
## Heading

{{ .Inner }}

```

You do not need `markdownify` here.

```auto
{{% markdownify %}}
Paragraph.
{{% /markdownify %}}

```

In usecase 2 the heading will be sent to the content renderer—that is it will be rendered to HTML and e.g. part of the TOC.

---

<div class="post-metadata">

**Author:** ![fritzmg](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/fritzmg/32/8717_2.png) [@fritzmg](https://discourse.gohugo.io/u/fritzmg)\
**Post date:** [May 17, 2019, 9:36am UTC](https://discourse.gohugo.io/t/misunderstanding-of-shortcode-syntax-in-0-55/18538/6 "2019-05-17T09:36:35Z")

</div>

But in both cases the inner content of the shortcode will not be run through the markdown renderer. Is there really no way to do this in 0.55 now? (Without the setting, as already mentioned.)

---

<div class="post-metadata">

**Author:** ![lar](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/lar/32/8569_2.png) [@lar](https://discourse.gohugo.io/u/lar)\
**Post date:** [May 17, 2019, 9:44am UTC](https://discourse.gohugo.io/t/misunderstanding-of-shortcode-syntax-in-0-55/18538/7 "2019-05-17T09:44:02Z")

</div>

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](https://discourse.gohugo.io/t/shortcode-markdown-vs-html-vs-table-of-content/18282) for a possible solution.

Also: [0.55 - What am I doing wrong?](https://discourse.gohugo.io/t/0-55-what-am-i-doing-wrong/18034)

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

---

<div class="post-metadata">

**Author:** ![fritzmg](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/fritzmg/32/8717_2.png) [@fritzmg](https://discourse.gohugo.io/u/fritzmg)\
**Post date:** [May 17, 2019, 9:46am UTC](https://discourse.gohugo.io/t/misunderstanding-of-shortcode-syntax-in-0-55/18538/8 "2019-05-17T09:46:11Z")

</div>

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

> [@lar](#):
>
> You could also use the `{{<` -syntax and then do `{{ .Inner | markdownify }}` in your shortcode, as described by @Grob above.

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?).

---

<div class="post-metadata">

**Author:** ![lar](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/lar/32/8569_2.png) [@lar](https://discourse.gohugo.io/u/lar)\
**Post date:** [May 17, 2019, 9:52am UTC](https://discourse.gohugo.io/t/misunderstanding-of-shortcode-syntax-in-0-55/18538/9 "2019-05-17T09:52:08Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![fritzmg](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/fritzmg/32/8717_2.png) [@fritzmg](https://discourse.gohugo.io/u/fritzmg)\
**Post date:** [May 17, 2019, 9:57am UTC](https://discourse.gohugo.io/t/misunderstanding-of-shortcode-syntax-in-0-55/18538/10 "2019-05-17T09:57:09Z")

</div>

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:

```markdown
## Heading

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

```

```auto
{{% 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?

---

<div class="post-metadata">

**Author:** ![Grob](https://avatars.discourse-cdn.com/v4/letter/g/f14d63/32.png) [@Grob](https://discourse.gohugo.io/u/Grob)\
**Post date:** [May 17, 2019, 10:03am UTC](https://discourse.gohugo.io/t/misunderstanding-of-shortcode-syntax-in-0-55/18538/11 "2019-05-17T10:03:51Z")

</div>

In this case simply use

```auto
## Heading

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

```

---

<div class="post-metadata">

**Author:** ![lar](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/lar/32/8569_2.png) [@lar](https://discourse.gohugo.io/u/lar)\
**Post date:** [May 17, 2019, 10:11am UTC](https://discourse.gohugo.io/t/misunderstanding-of-shortcode-syntax-in-0-55/18538/12 "2019-05-17T10:11:04Z")

</div>

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:

```auto
## 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](https://discourse.gohugo.io/t/shortcode-markdown-vs-html-vs-table-of-content/18282/5)

---

<div class="post-metadata">

**Author:** ![fritzmg](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/fritzmg/32/8717_2.png) [@fritzmg](https://discourse.gohugo.io/u/fritzmg)\
**Post date:** [May 17, 2019, 10:12am UTC](https://discourse.gohugo.io/t/misunderstanding-of-shortcode-syntax-in-0-55/18538/13 "2019-05-17T10:12:15Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![lar](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/lar/32/8569_2.png) [@lar](https://discourse.gohugo.io/u/lar)\
**Post date:** [May 17, 2019, 10:17am UTC](https://discourse.gohugo.io/t/misunderstanding-of-shortcode-syntax-in-0-55/18538/14 "2019-05-17T10:17:07Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![bep](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bep/32/3332_2.png) [@bep](https://discourse.gohugo.io/u/bep)\
**Post date:** [May 18, 2019, 7:59am UTC](https://discourse.gohugo.io/t/misunderstanding-of-shortcode-syntax-in-0-55/18538/15 "2019-05-18T07:59:38Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![Grob](https://avatars.discourse-cdn.com/v4/letter/g/f14d63/32.png) [@Grob](https://discourse.gohugo.io/u/Grob)\
**Post date:** [May 18, 2019, 10:01am UTC](https://discourse.gohugo.io/t/misunderstanding-of-shortcode-syntax-in-0-55/18538/16 "2019-05-18T10:01:23Z")

</div>

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?

---

<div class="post-metadata">

**Author:** ![bep](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bep/32/3332_2.png) [@bep](https://discourse.gohugo.io/u/bep)\
**Post date:** [May 18, 2019, 11:41am UTC](https://discourse.gohugo.io/t/misunderstanding-of-shortcode-syntax-in-0-55/18538/17 "2019-05-18T11:41:08Z")

</div>

> [@Grob](#):
>
> Just curious to hear: Why was it not possible to generally allow markdown in the shortcodes html files and use `{{%` and `{{<` synonymously?

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 `{{<`.

---

<div class="post-metadata">

**Author:** ![Grob](https://avatars.discourse-cdn.com/v4/letter/g/f14d63/32.png) [@Grob](https://discourse.gohugo.io/u/Grob)\
**Post date:** [May 18, 2019, 2:16pm UTC](https://discourse.gohugo.io/t/misunderstanding-of-shortcode-syntax-in-0-55/18538/18 "2019-05-18T14:16:31Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![Grob](https://avatars.discourse-cdn.com/v4/letter/g/f14d63/32.png) [@Grob](https://discourse.gohugo.io/u/Grob)\
**Post date:** [May 18, 2019, 2:33pm UTC](https://discourse.gohugo.io/t/misunderstanding-of-shortcode-syntax-in-0-55/18538/19 "2019-05-18T14:33:59Z")

</div>

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](https://cupper-hugo-theme.netlify.com/cupper-shortcodes/#codepen) uses `‌{{% codePen VpVNKW %}}`.)
- Always use `{{< />}}`—if required with `markdownify`—and only use `{{%` if there is markdown in the shortcode html file itself?

---

<div class="post-metadata">

**Author:** ![bep](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bep/32/3332_2.png) [@bep](https://discourse.gohugo.io/u/bep)\
**Post date:** [May 18, 2019, 3:50pm UTC](https://discourse.gohugo.io/t/misunderstanding-of-shortcode-syntax-in-0-55/18538/20 "2019-05-18T15:50:10Z")

</div>

> [@Grob](#):
>
> only use `{{%` if there is markdown in the shortcode html file itself?

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

```auto
{{% 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.

[Next page](https://discourse.gohugo.io/t/misunderstanding-of-shortcode-syntax-in-0-55/18538.md?page=2)